Botan 3.14.1
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 <botan/tls_magic.h>
13#include <botan/internal/tls_types_13.h>
14#include <memory>
15#include <span>
16#include <string_view>
17#include <vector>
18
19namespace Botan {
20
21class HashFunction;
22
23} // namespace Botan
24
25namespace Botan::TLS {
26
27/**
28 * Wraps the behaviour of the TLS 1.3 transcript hash as described in
29 * RFC 8446 4.4.1. Particularly, it hides the complexity that the
30 * utilized hash algorithm might become evident only after receiving
31 * a server hello message.
32 */
34 public:
35 explicit Transcript_Hash_State(TLS_Flavor flavor);
36 Transcript_Hash_State(TLS_Flavor flavor, std::string_view algo_spec);
38
39 /**
40 * Recreates a Transcript_Hash_State after receiving a Hello Retry Request.
41 * Note that the `prev_transcript_hash_state` must not have an hash algorithm
42 * set, yet. Furthermore it must contain exactly TWO unprocessed messages:
43 * * Client Hello 1, and
44 * * Hello Retry Request
45 * The result of this function is an ordinary transcript hash that can replace
46 * the previously used object in client and server implementations.
47 */
49 std::string_view algo_spec, const Transcript_Hash_State& prev_transcript_hash_state);
50
52
55
56 /**
57 * Updates the transcript hash with a new handshake message where
58 * @p tls_message_header is the 4-byte handshake message header and
59 * @p serialized_message_s is the serialized handshake message.
60 */
61 void update(HandshakeProtocolHeader tls_message_header,
63
64 /**
65 * returns the latest transcript hash
66 * (given an algorithm was already specified and some data was provided to `update`)
67 */
68 const Transcript_Hash& current() const;
69
70 /**
71 * returns the second-latest transcript hash
72 * throws if no 'current' was ever replaced by a call to `update`
73 */
74 const Transcript_Hash& previous() const;
75
76 /**
77 * returns a truncated transcript hash (see RFC 8446 4.2.11.2)
78 *
79 * This is useful for implementing PSK binders in the PSK extension of
80 * client hello. It is a transcript over a partially marshalled client
81 * hello message. This hash is available only if the last processed
82 * message was a client hello with a PSK extension.
83 *
84 * throws if no 'truncated' hash is available
85 */
86 const Transcript_Hash& truncated() const;
87
88 void set_algorithm(std::string_view algo_spec);
89
91
92 private:
93 // called by clone
95
96 private:
97 TLS_Flavor m_flavor;
98 std::unique_ptr<HashFunction> m_hash;
99
100 // This buffer is filled with the data that is passed into
101 // `update()` before `set_algorithm()` was called.
102 std::vector<std::pair<HandshakeProtocolHeader, SerializedHandshakeMessage>> m_unprocessed_transcript;
103
104 Transcript_Hash m_current;
105 Transcript_Hash m_previous;
106 Transcript_Hash m_truncated;
107};
108
109} // namespace Botan::TLS
110
111#endif // BOTAN_TLS_TRANSCRIPT_HASH_13_H_
#define BOTAN_TEST_API
Definition api.h:41
const Transcript_Hash & current() const
void update(HandshakeProtocolHeader tls_message_header, StrongSpan< const SerializedHandshakeMessage > serialized_message)
Transcript_Hash_State & operator=(Transcript_Hash_State &&other) noexcept
static Transcript_Hash_State recreate_after_hello_retry_request(std::string_view algo_spec, const Transcript_Hash_State &prev_transcript_hash_state)
void set_algorithm(std::string_view algo_spec)
const Transcript_Hash & previous() const
Transcript_Hash_State(Transcript_Hash_State &&other) noexcept
const Transcript_Hash & truncated() const
Transcript_Hash_State & operator=(const Transcript_Hash_State &)=delete
std::vector< uint8_t > Transcript_Hash
Definition tls_magic.h:105
Strong< std::array< uint8_t, 4 >, struct HandshakeProtocolHeader_ > HandshakeProtocolHeader
Holds the serialization of a TLS 1.3 handshake protocol header.