Botan 3.14.1
Crypto and TLS for C&
tls_record_13.h
Go to the documentation of this file.
1/*
2* TLS record structure of TLS 1.3
3* (C) 2022 Jack Lloyd
4* 2022 Hannes Rantzsch, René Meusel - neXenio GmbH
5* 2026 Amos Treiber, René Meusel - Rohde & Schwarz Networks and Cybersecurity GmbH
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#ifndef BOTAN_TLS_RECORD_13_H_
11#define BOTAN_TLS_RECORD_13_H_
12
13#include <botan/secmem.h>
14#include <botan/tls_magic.h>
15#include <botan/tls_version.h>
16#include <botan/internal/tls_types_13.h>
17#include <optional>
18#include <variant>
19
20namespace Botan::TLS {
21
22/**
23 * Represents the operational content of a (D)TLS record for further processing
24 * throughout the TLS protocol or to be passed to the application layer.
25 */
31
32struct ChangeCipherSpec_Record final : public Record_Content {};
33
34struct Alert_Record final : public Record_Content {};
35
36struct Handshake_Record final : public Record_Content {};
37
38struct ApplicationData_Record final : public Record_Content {};
39
40using Record = std::variant<ChangeCipherSpec_Record, Alert_Record, Handshake_Record, ApplicationData_Record>;
41
42/**
43 * Takes a generic @p record and transforms it into one of the strong typed
44 * record variants based on the contained type.
45 *
46 * @throws TLS_Exception if the record type is any other value.
47 */
49
50/**
51 * Represents a TLS record composed of a partially ossified header and payload.
52 * The record might be incomplete, i.e. not all bytes of the header or the
53 * payload have been received, yet. The record can be extended by appending more
54 * bytes to it.
55 *
56 * Once fully re-assembled, the payload buffer can be extracted from this record
57 * for decryption. This avoids an additional copy of the payload bytes.
58 */
60 public:
61 Record_TLS() = default;
62 Record_TLS(const Record_TLS&) = delete;
63 Record_TLS& operator=(const Record_TLS&) = delete;
64 Record_TLS(Record_TLS&&) = default;
66
67 ~Record_TLS() = default;
68
69 public:
70 static std::array<uint8_t, TLS_HEADER_SIZE> serialize_header(Record_Type type,
72 uint16_t payload_length);
73
74 public:
75 /**
76 * Appends bytes to an incomplete record. Once the record is complete,
77 * additional invocations will throw. If @p bytes contains more bytes than
78 * needed to complete the record, only the required number of bytes will
79 * be consumed and the rest will be ignored. The caller is responsible for
80 * keeping track of the number of bytes consumed and for discarding the
81 * consumed bytes from the buffer.
82 *
83 * @returns the number of bytes that were consumed from the buffer.
84 */
85 size_t append(std::span<const uint8_t> bytes);
86
87 /// Returns true if the record has collected all header bytes
88 bool header_complete() const { return m_header_bytes_stored == TLS_HEADER_SIZE; }
89
90 /// Returns true if the record has collected all its bytes
91 bool complete() const { return missing_bytes_hint() == 0; }
92
93 /// Returns the total number of bytes in this record, including the header
94 size_t stored_bytes() const { return m_header_bytes_stored + m_payload.size(); }
95
96 /// Returns the number of bytes needed to complete at least the record
97 // header or the entire record if the header is already complete.
98 size_t missing_bytes_hint() const;
99
100 Record_Type type() const;
101 Protocol_Version legacy_version() const;
102 uint16_t payload_length() const;
103
104 std::span<uint8_t, TLS_HEADER_SIZE> header();
105 std::span<const uint8_t, TLS_HEADER_SIZE> header() const;
106
107 std::span<const uint8_t> payload() const;
108 secure_vector<uint8_t> take_payload();
109
110 private:
111 uint8_t m_header_bytes_stored = 0;
112 std::array<uint8_t, TLS_HEADER_SIZE> m_header = {};
113 secure_vector<uint8_t> m_payload;
114};
115
116} // namespace Botan::TLS
117
118#endif
#define BOTAN_TEST_API
Definition api.h:41
Record_TLS & operator=(const Record_TLS &)=delete
Record_TLS & operator=(Record_TLS &&)=default
Record_TLS(const Record_TLS &)=delete
bool header_complete() const
Returns true if the record has collected all header bytes.
bool complete() const
Returns true if the record has collected all its bytes.
size_t stored_bytes() const
Returns the total number of bytes in this record, including the header.
Record_Type type() const
Record_TLS(Record_TLS &&)=default
size_t missing_bytes_hint() const
Returns the number of bytes needed to complete at least the record.
static std::array< uint8_t, TLS_HEADER_SIZE > serialize_header(Record_Type type, Protocol_Version legacy_version, uint16_t payload_length)
size_t append(std::span< const uint8_t > bytes)
uint16_t payload_length() const
Protocol_Version legacy_version() const
std::variant< ChangeCipherSpec_Record, Alert_Record, Handshake_Record, ApplicationData_Record > Record
@ TLS_HEADER_SIZE
Definition tls_magic.h:30
Record annotate_record_type(Record_Content &&record)
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
secure_vector< uint8_t > payload
std::optional< uint64_t > sequence_number