Botan 3.0.0-alpha0
Crypto and TLS for C&
tls_transcript_hash_13.h
Go to the documentation of this file.
1/*
2* TLS transcript hash implementation for TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_TRANSCRIPT_HASH_13_H_
10#define BOTAN_TLS_TRANSCRIPT_HASH_13_H_
11
12#include <memory>
13#include <string>
14#include <vector>
15
16#include <botan/hash.h>
17#include <botan/tls_magic.h>
18
19namespace Botan::TLS {
20
21/**
22 * Wraps the behaviour of the TLS 1.3 transcript hash as described in
23 * RFC 8446 4.4.1. Particularly, it hides the complexity that the
24 * utilized hash algorithm might become evident only after receiving
25 * a server hello message.
26 */
28 {
29 public:
31 Transcript_Hash_State(const std::string &algo_spec);
33
34 /**
35 * Recreates a Transcript_Hash_State after receiving a Hello Retry Request.
36 * Note that the `prev_transcript_hash_state` must not have an hash algorithm
37 * set, yet. Furthermore it must contain exactly TWO unprocessed messages:
38 * * Client Hello 1, and
39 * * Hello Retry Request
40 * The result of this function is an ordinary transcript hash that can replace
41 * the previously used object in client and server implementations.
42 */
43 static Transcript_Hash_State recreate_after_hello_retry_request(
44 const std::string& algo_spec,
45 const Transcript_Hash_State& prev_transcript_hash_state);
46
48
51
52 void update(const std::vector<uint8_t>& serialized_message)
53 {
54 update(serialized_message.data(), serialized_message.size());
55 }
56
57 // TODO: C++20 replace this C-style API with std::span
58 void update(const uint8_t* serialized_message, const size_t serialized_message_length);
59
60 /**
61 * returns the latest transcript hash
62 * (given an algorithm was already specified and some data was provided to `update`)
63 */
64 const Transcript_Hash& current() const;
65
66 /**
67 * returns the second-latest transcript hash
68 * throws if no 'current' was ever replaced by a call to `update`
69 */
70 const Transcript_Hash& previous() const;
71
72 /**
73 * returns a truncated transcript hash (see RFC 8446 4.2.11.2)
74 *
75 * This is useful for implementing PSK binders in the PSK extension of
76 * client hello. It is a transcript over a partially marshalled client
77 * hello message. This hash is available only if the last processed
78 * message was a client hello with a PSK extension.
79 *
80 * throws if no 'truncated' hash is available
81 */
82 const Transcript_Hash& truncated() const;
83
84 void set_algorithm(const std::string& algo_spec);
85
86 Transcript_Hash_State clone() const;
87
88 private:
90
91 private:
92 std::unique_ptr<HashFunction> m_hash;
93
94 // This buffer is filled with the data that is passed into
95 // `update()` before `set_algorithm()` was called.
96 std::vector<std::vector<uint8_t>> m_unprocessed_transcript;
97
98 Transcript_Hash m_current;
99 Transcript_Hash m_previous;
100 Transcript_Hash m_truncated;
101 };
102
103}
104
105#endif // BOTAN_TLS_TRANSCRIPT_HASH_13_H_
Transcript_Hash_State(Transcript_Hash_State &&)=default
Transcript_Hash_State & operator=(Transcript_Hash_State &&)=default
Transcript_Hash_State & operator=(const Transcript_Hash_State &)=delete
void update(const std::vector< uint8_t > &serialized_message)
int(* update)(CTX *, const void *, CC_LONG len)
#define BOTAN_TEST_API
Definition: compiler.h:51
std::vector< uint8_t > Transcript_Hash
Definition: tls_magic.h:93