2 * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
4 * Licensed under the Apache License 2.0 (the "License"). You may not use
5 * this file except in compliance with the License. You can obtain a copy
6 * in the file LICENSE in the source distribution or at
7 * https://www.openssl.org/source/license.html
10 #ifndef OSSL_INTERNAL_RECORDMETHOD_H
11 # define OSSL_INTERNAL_RECORDMETHOD_H
14 # include <openssl/ssl.h>
17 * We use the term "record" here to refer to a packet of data. Records are
18 * typically protected via a cipher and MAC, or an AEAD cipher (although not
19 * always). This usage of the term record is consistent with the TLS concept.
20 * In QUIC the term "record" is not used but it is analogous to the QUIC term
21 * "packet". The interface in this file applies to all protocols that protect
22 * records/packets of data, i.e. (D)TLS and QUIC. The term record is used to
23 * refer to both contexts.
28 * Types of QUIC record layer;
30 * QUIC reuses the TLS handshake for agreeing secrets. An SSL object representing
31 * a QUIC connection will have an additional SSL object internally representing
32 * the TLS state of the QUIC handshake. This internal TLS is referred to as
33 * QUIC-TLS in this file.
34 * "Records" output from QUIC-TLS contains standard TLS handshake messages and
35 * are *not* encrypted directly but are instead wrapped up in plaintext
36 * CRYPTO frames. These CRYPTO frames could be collected together with other
37 * QUIC frames into a single QUIC packet. The QUIC record layer will then
38 * encrypt the whole packet.
41 * QUIC-TLS record layer: outputs plaintext CRYPTO frames containing TLS
42 * handshake messages only.
43 * QUIC record layer: outputs encrypted packets which may contain CRYPTO frames
44 * or any other type of QUIC frame.
48 * An OSSL_RECORD_METHOD is a protcol specific method which provides the
49 * functions for reading and writing records for that protocol. Which
50 * OSSL_RECORD_METHOD to use for a given protocol is defined by the SSL_METHOD.
52 typedef struct ossl_record_method_st OSSL_RECORD_METHOD
;
55 * An OSSL_RECORD_LAYER is just an externally defined opaque pointer created by
58 typedef struct ossl_record_layer_st OSSL_RECORD_LAYER
;
61 # define OSSL_RECORD_ROLE_CLIENT 0
62 # define OSSL_RECORD_ROLE_SERVER 1
64 # define OSSL_RECORD_DIRECTION_READ 0
65 # define OSSL_RECORD_DIRECTION_WRITE 1
68 * Protection level. For <= TLSv1.2 only "NONE" and "APPLICATION" are used.
70 # define OSSL_RECORD_PROTECTION_LEVEL_NONE 0
71 # define OSSL_RECORD_PROTECTION_LEVEL_EARLY 1
72 # define OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE 2
73 # define OSSL_RECORD_PROTECTION_LEVEL_APPLICATION 3
76 # define OSSL_RECORD_RETURN_SUCCESS 1
77 # define OSSL_RECORD_RETURN_RETRY 0
78 # define OSSL_RECORD_RETURN_NON_FATAL_ERR -1
79 # define OSSL_RECORD_RETURN_FATAL -2
80 # define OSSL_RECORD_RETURN_EOF -3
83 * Template for creating a record. A record consists of the |type| of data it
84 * will contain (e.g. alert, handshake, application data, etc) along with an
85 * array of buffers in |bufs| of size |numbufs|. There is a corresponding array
86 * of buffer lengths in |buflens|. Concatenating all of the buffer data together
87 * would give you the complete plaintext payload to be sent in a single record.
89 struct ossl_record_template_st
{
96 typedef struct ossl_record_template_st OSSL_RECORD_TEMPLATE
;
99 * Rather than a "method" approach, we could make this fetchable - Should we?
100 * There could be some complexity in finding suitable record layer implementations
101 * e.g. we need to find one that matches the negotiated protocol, cipher,
102 * extensions, etc. The selection_cb approach given above doesn't work so well
103 * if unknown third party providers with OSSL_RECORD_METHOD implementations are
108 * If this becomes public API then we will need functions to create and
109 * free an OSSL_RECORD_METHOD, as well as functions to get/set the various
110 * function pointers....unless we make it fetchable.
112 struct ossl_record_method_st
{
114 * Create a new OSSL_RECORD_LAYER object for handling the protocol version
115 * set by |vers|. |role| is 0 for client and 1 for server. |direction|
116 * indicates either read or write. |level| is the protection level as
117 * described above. |settings| are mandatory settings that will cause the
118 * new() call to fail if they are not understood (for example to require
119 * Encrypt-Then-Mac support). |options| are optional settings that will not
120 * cause the new() call to fail if they are not understood (for example
121 * whether to use "read ahead" or not).
123 * The BIO in |transport| is the BIO for the underlying transport layer.
124 * Where the direction is "read", then this BIO will only ever be used for
125 * reading data. Where the direction is "write", then this BIO will only
126 * every be used for writing data.
128 * An SSL object will always have at least 2 OSSL_RECORD_LAYER objects in
129 * force at any one time (one for reading and one for writing). In some
130 * protocols more than 2 might be used (e.g. in DTLS for retransmitting
131 * messages from an earlier epoch).
133 * The created OSSL_RECORD_LAYER object is stored in *ret on success (or
134 * NULL otherwise). The return value will be one of
135 * OSSL_RECORD_RETURN_SUCCESS, OSSL_RECORD_RETURN_FATAL or
136 * OSSL_RECORD_RETURN_NON_FATAL. A non-fatal return means that creation of
137 * the record layer has failed because it is unsuitable, but an alternative
138 * record layer can be tried instead.
142 * TODO(RECLAYER): Will have to be something other than EVP_CIPHER if we
143 * make this fetchable
144 * TODO(RECLAYER): mactype should not be an int
146 int (*new_record_layer
)(OSSL_LIB_CTX
*libctx
,
147 const char *propq
, int vers
,
148 int role
, int direction
,
149 int level
, unsigned char *key
,
153 unsigned char *mackey
,
155 const EVP_CIPHER
*ciph
,
157 /* TODO(RECLAYER): This probably should not be an int */
160 const SSL_COMP
*comp
,
166 const OSSL_PARAM
*settings
,
167 const OSSL_PARAM
*options
,
168 const OSSL_DISPATCH
*fns
,
170 OSSL_RECORD_LAYER
**ret
,
171 /* TODO(RECLAYER): Remove me */
173 int (*free
)(OSSL_RECORD_LAYER
*rl
);
175 int (*reset
)(OSSL_RECORD_LAYER
*rl
); /* Is this needed? */
177 /* Returns 1 if we have unprocessed data buffered or 0 otherwise */
178 int (*unprocessed_read_pending
)(OSSL_RECORD_LAYER
*rl
);
180 * Returns 1 if we have processed data buffered that can be read or 0 otherwise
181 * - not necessarily app data
183 int (*processed_read_pending
)(OSSL_RECORD_LAYER
*rl
);
186 * The amount of processed app data that is internally bufferred and
189 size_t (*app_data_pending
)(OSSL_RECORD_LAYER
*rl
);
191 int (*write_pending
)(OSSL_RECORD_LAYER
*rl
);
195 * Find out the maximum amount of plaintext data that the record layer is
196 * prepared to write in a single record. When calling write_records it is
197 * the caller's responsibility to ensure that no record template exceeds
198 * this maximum when calling write_records.
200 size_t (*get_max_record_len
)(OSSL_RECORD_LAYER
*rl
);
203 * Find out the maximum number of records that the record layer is prepared
204 * to process in a single call to write_records. It is the caller's
205 * responsibility to ensure that no call to write_records exceeds this
208 size_t (*get_max_records
)(OSSL_RECORD_LAYER
*rl
);
211 * Write |numtempl| records from the array of record templates pointed to
212 * by |templates|. Each record should be no longer than the value returned
213 * by get_max_record_len(), and there should be no more records than the
214 * value returned by get_max_records().
215 * |allowance| is the maximum amount of "on-the-wire" data that is allowed
216 * to be sent at the moment (including all QUIC headers, but excluding any
217 * UDP/IP headers). After a successful or retry return |*sent| will
218 * be updated with the amount of data that has been sent so far. In the case
219 * of a retry this could be 0.
220 * Where possible the caller will attempt to ensure that all records are the
221 * same length, except the last record. This may not always be possible so
222 * the record method implementation should not rely on this being the case.
223 * In the event of a retry the caller should call retry_write_records()
224 * to try again. No more calls to write_records() should be attempted until
225 * retry_write_records() returns success.
226 * Buffers allocated for the record templates can be freed immediately after
227 * write_records() returns - even in the case a retry.
228 * The record templates represent the plaintext payload. The encrypted
229 * output is written to the |transport| BIO.
235 int (*write_records
)(OSSL_RECORD_LAYER
*rl
, OSSL_RECORD_TEMPLATE
**templates
,
236 size_t numtempl
, size_t allowance
, size_t *sent
);
239 * Retry a previous call to write_records. The caller should continue to
240 * call this until the function returns with success or failure. After
241 * each retry more of the data may have been incrementally sent. |allowance|
242 * is the amount of "on-the-wire" data that is allowed to be sent at the
243 * moment. After a successful or retry return |*sent| will
244 * be updated with the amount of data that has been sent by this call to
245 * retry_write_records().
251 int (*retry_write_records
)(OSSL_RECORD_LAYER
*rl
, size_t allowance
,
255 * Read a record and return the record layer version and record type in
256 * the |rversion| and |type| parameters. |*data| is set to point to a
257 * record layer buffer containing the record payload data and |*datalen|
258 * is filled in with the length of that data. The |epoch| and |seq_num|
259 * values are only used if DTLS has been negotiated. In that case they are
260 * filled in with the epoch and sequence number from the record.
261 * An opaque record layer handle for the record is returned in |*rechandle|
262 * which is used in a subsequent call to |release_record|. The buffer must
263 * remain available until release_record is called.
265 * Internally the the OSSL_RECORD_METHOD the implementation may read/process
266 * multiple records in one go and buffer them.
268 int (*read_record
)(OSSL_RECORD_LAYER
*rl
, void **rechandle
, int *rversion
,
269 int *type
, unsigned char **data
, size_t *datalen
,
270 uint16_t *epoch
, unsigned char *seq_num
,
271 /* TODO(RECLAYER): Remove me */ SSL_CONNECTION
*s
);
273 * Release a buffer associated with a record previously read with
274 * read_record. Records are guaranteed to be released in the order that they
277 int (*release_record
)(OSSL_RECORD_LAYER
*rl
, void *rechandle
);
280 * In the event that a fatal error is returned from the functions above then
281 * get_alert_code() can be called to obtain a more details identifier for
282 * the error. In (D)TLS this is the alert description code.
284 int (*get_alert_code
)(OSSL_RECORD_LAYER
*rl
);
287 * Update the transport BIO from the one originally set in the
288 * new_record_layer call
290 int (*set1_bio
)(OSSL_RECORD_LAYER
*rl
, BIO
*bio
);
292 /* Called when protocol negotiation selects a protocol version to use */
293 int (*set_protocol_version
)(OSSL_RECORD_LAYER
*rl
, int version
);
296 * Whether we are allowed to receive unencrypted alerts, even if we might
297 * otherwise expect encrypted records. Ignored by protocol versions where
298 * this isn't relevant
300 void (*set_plain_alerts
)(OSSL_RECORD_LAYER
*rl
, int allow
);
303 * Called immediately after creation of the recory layer if we are in a
304 * first handshake. Also called at the end of the first handshake
306 void (*set_first_handshake
)(OSSL_RECORD_LAYER
*rl
, int first
);
309 * TODO(RECLAYER): Remove these. These function pointers are temporary hacks
310 * during the record layer refactoring. They need to be removed before the
311 * refactor is complete.
313 int (*read_n
)(OSSL_RECORD_LAYER
*rl
, size_t n
, size_t max
, int extend
,
314 int clearold
, size_t *readbytes
);
315 SSL3_BUFFER
*(*get0_rbuf
)(OSSL_RECORD_LAYER
*rl
);
316 unsigned char *(*get0_packet
)(OSSL_RECORD_LAYER
*rl
);
317 void (*set0_packet
)(OSSL_RECORD_LAYER
*rl
, unsigned char *packet
,
319 size_t (*get_packet_length
)(OSSL_RECORD_LAYER
*rl
);
320 void (*reset_packet_length
)(OSSL_RECORD_LAYER
*rl
);
324 /* Standard built-in record methods */
325 extern const OSSL_RECORD_METHOD ossl_tls_record_method
;
326 # ifndef OPENSSL_NO_KTLS
327 extern const OSSL_RECORD_METHOD ossl_ktls_record_method
;
329 extern const OSSL_RECORD_METHOD ossl_dtls_record_method
;
331 #endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */