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.
27 * An OSSL_RECORD_METHOD is a protcol specific method which provides the
28 * functions for reading and writing records for that protocol. Which
29 * OSSL_RECORD_METHOD to use for a given protocol is defined by the SSL_METHOD.
31 typedef struct ossl_record_method_st OSSL_RECORD_METHOD;
34 * An OSSL_RECORD_LAYER is just an externally defined opaque pointer created by
37 typedef struct ossl_record_layer_st OSSL_RECORD_LAYER;
40 # define OSSL_RECORD_ROLE_CLIENT 0
41 # define OSSL_RECORD_ROLE_SERVER 1
43 # define OSSL_RECORD_DIRECTION_READ 0
44 # define OSSL_RECORD_DIRECTION_WRITE 1
47 * Protection level. For <= TLSv1.2 only "NONE" and "APPLICATION" are used.
49 # define OSSL_RECORD_PROTECTION_LEVEL_NONE 0
50 # define OSSL_RECORD_PROTECTION_LEVEL_EARLY 1
51 # define OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE 2
52 # define OSSL_RECORD_PROTECTION_LEVEL_APPLICATION 3
54 # define OSSL_RECORD_RETURN_SUCCESS 1
55 # define OSSL_RECORD_RETURN_RETRY 0
56 # define OSSL_RECORD_RETURN_NON_FATAL_ERR -1
57 # define OSSL_RECORD_RETURN_FATAL -2
58 # define OSSL_RECORD_RETURN_EOF -3
61 * Template for creating a record. A record consists of the |type| of data it
62 * will contain (e.g. alert, handshake, application data, etc) along with a
63 * buffer of payload data in |buf| of length |buflen|.
65 struct ossl_record_template_st {
67 const unsigned char *buf;
71 typedef struct ossl_record_template_st OSSL_RECORD_TEMPLATE;
74 * Rather than a "method" approach, we could make this fetchable - Should we?
75 * There could be some complexity in finding suitable record layer implementations
76 * e.g. we need to find one that matches the negotiated protocol, cipher,
77 * extensions, etc. The selection_cb approach given above doesn't work so well
78 * if unknown third party providers with OSSL_RECORD_METHOD implementations are
83 * If this becomes public API then we will need functions to create and
84 * free an OSSL_RECORD_METHOD, as well as functions to get/set the various
85 * function pointers....unless we make it fetchable.
87 struct ossl_record_method_st {
89 * Create a new OSSL_RECORD_LAYER object for handling the protocol version
90 * set by |vers|. |role| is 0 for client and 1 for server. |direction|
91 * indicates either read or write. |level| is the protection level as
92 * described above. |settings| are mandatory settings that will cause the
93 * new() call to fail if they are not understood (for example to require
94 * Encrypt-Then-Mac support). |options| are optional settings that will not
95 * cause the new() call to fail if they are not understood (for example
96 * whether to use "read ahead" or not).
98 * The BIO in |transport| is the BIO for the underlying transport layer.
99 * Where the direction is "read", then this BIO will only ever be used for
100 * reading data. Where the direction is "write", then this BIO will only
101 * every be used for writing data.
103 * An SSL object will always have at least 2 OSSL_RECORD_LAYER objects in
104 * force at any one time (one for reading and one for writing). In some
105 * protocols more than 2 might be used (e.g. in DTLS for retransmitting
106 * messages from an earlier epoch).
108 * The created OSSL_RECORD_LAYER object is stored in *ret on success (or
109 * NULL otherwise). The return value will be one of
110 * OSSL_RECORD_RETURN_SUCCESS, OSSL_RECORD_RETURN_FATAL or
111 * OSSL_RECORD_RETURN_NON_FATAL. A non-fatal return means that creation of
112 * the record layer has failed because it is unsuitable, but an alternative
113 * record layer can be tried instead.
117 * If we eventually make this fetchable then we will need to use something
118 * other than EVP_CIPHER. Also mactype would not be a NID, but a string. For
119 * now though, this works.
121 int (*new_record_layer)(OSSL_LIB_CTX *libctx,
122 const char *propq, int vers,
123 int role, int direction,
130 unsigned char *mackey,
132 const EVP_CIPHER *ciph,
136 const SSL_COMP *comp,
142 const OSSL_PARAM *settings,
143 const OSSL_PARAM *options,
144 const OSSL_DISPATCH *fns,
146 OSSL_RECORD_LAYER **ret);
147 int (*free)(OSSL_RECORD_LAYER *rl);
149 int (*reset)(OSSL_RECORD_LAYER *rl); /* Is this needed? */
151 /* Returns 1 if we have unprocessed data buffered or 0 otherwise */
152 int (*unprocessed_read_pending)(OSSL_RECORD_LAYER *rl);
155 * Returns 1 if we have processed data buffered that can be read or 0 otherwise
156 * - not necessarily app data
158 int (*processed_read_pending)(OSSL_RECORD_LAYER *rl);
161 * The amount of processed app data that is internally bufferred and
164 size_t (*app_data_pending)(OSSL_RECORD_LAYER *rl);
166 int (*write_pending)(OSSL_RECORD_LAYER *rl);
169 * Find out the maximum amount of plaintext data that the record layer is
170 * prepared to write in a single record. When calling write_records it is
171 * the caller's responsibility to ensure that no record template exceeds
172 * this maximum when calling write_records.
174 size_t (*get_max_record_len)(OSSL_RECORD_LAYER *rl);
177 * Find out the maximum number of records that the record layer is prepared
178 * to process in a single call to write_records. It is the caller's
179 * responsibility to ensure that no call to write_records exceeds this
182 size_t (*get_max_records)(OSSL_RECORD_LAYER *rl);
185 * Write |numtempl| records from the array of record templates pointed to
186 * by |templates|. Each record should be no longer than the value returned
187 * by get_max_record_len(), and there should be no more records than the
188 * value returned by get_max_records().
189 * |allowance| is the maximum amount of "on-the-wire" data that is allowed
190 * to be sent at the moment (including all QUIC headers, but excluding any
191 * UDP/IP headers). After a successful or retry return |*sent| will
192 * be updated with the amount of data that has been sent so far. In the case
193 * of a retry this could be 0.
194 * Where possible the caller will attempt to ensure that all records are the
195 * same length, except the last record. This may not always be possible so
196 * the record method implementation should not rely on this being the case.
197 * In the event of a retry the caller should call retry_write_records()
198 * to try again. No more calls to write_records() should be attempted until
199 * retry_write_records() returns success.
200 * Buffers allocated for the record templates can be freed immediately after
201 * write_records() returns - even in the case a retry.
202 * The record templates represent the plaintext payload. The encrypted
203 * output is written to the |transport| BIO.
209 int (*write_records)(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE **templates,
210 size_t numtempl, size_t allowance, size_t *sent);
213 * Retry a previous call to write_records. The caller should continue to
214 * call this until the function returns with success or failure. After
215 * each retry more of the data may have been incrementally sent. |allowance|
216 * is the amount of "on-the-wire" data that is allowed to be sent at the
217 * moment. After a successful or retry return |*sent| will
218 * be updated with the amount of data that has been sent by this call to
219 * retry_write_records().
225 int (*retry_write_records)(OSSL_RECORD_LAYER *rl, size_t allowance,
229 * Read a record and return the record layer version and record type in
230 * the |rversion| and |type| parameters. |*data| is set to point to a
231 * record layer buffer containing the record payload data and |*datalen|
232 * is filled in with the length of that data. The |epoch| and |seq_num|
233 * values are only used if DTLS has been negotiated. In that case they are
234 * filled in with the epoch and sequence number from the record.
235 * An opaque record layer handle for the record is returned in |*rechandle|
236 * which is used in a subsequent call to |release_record|. The buffer must
237 * remain available until release_record is called.
239 * Internally the the OSSL_RECORD_METHOD the implementation may read/process
240 * multiple records in one go and buffer them.
242 int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion,
243 int *type, unsigned char **data, size_t *datalen,
244 uint16_t *epoch, unsigned char *seq_num);
246 * Release a buffer associated with a record previously read with
247 * read_record. Records are guaranteed to be released in the order that they
250 int (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle);
253 * In the event that a fatal error is returned from the functions above then
254 * get_alert_code() can be called to obtain a more details identifier for
255 * the error. In (D)TLS this is the alert description code.
257 int (*get_alert_code)(OSSL_RECORD_LAYER *rl);
260 * Update the transport BIO from the one originally set in the
261 * new_record_layer call
263 int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio);
265 /* Called when protocol negotiation selects a protocol version to use */
266 int (*set_protocol_version)(OSSL_RECORD_LAYER *rl, int version);
269 * Whether we are allowed to receive unencrypted alerts, even if we might
270 * otherwise expect encrypted records. Ignored by protocol versions where
271 * this isn't relevant
273 void (*set_plain_alerts)(OSSL_RECORD_LAYER *rl, int allow);
276 * Called immediately after creation of the record layer if we are in a
277 * first handshake. Also called at the end of the first handshake
279 void (*set_first_handshake)(OSSL_RECORD_LAYER *rl, int first);
282 * Set the maximum number of pipelines that the record layer should process.
285 void (*set_max_pipelines)(OSSL_RECORD_LAYER *rl, size_t max_pipelines);
288 * Called to tell the record layer whether we are currently "in init" or
289 * not. Default at creation of the record layer is "yes".
291 void (*set_in_init)(OSSL_RECORD_LAYER *rl, int in_init);
294 * Get a short or long human readable description of the record layer state
296 void (*get_state)(OSSL_RECORD_LAYER *rl, const char **shortstr,
297 const char **longstr);
300 * Set new options or modify ones that were originaly specified in the
301 * new_record_layer call.
303 int (*set_options)(OSSL_RECORD_LAYER *rl, const OSSL_PARAM *options);
307 /* Standard built-in record methods */
308 extern const OSSL_RECORD_METHOD ossl_tls_record_method;
309 # ifndef OPENSSL_NO_KTLS
310 extern const OSSL_RECORD_METHOD ossl_ktls_record_method;
312 extern const OSSL_RECORD_METHOD ossl_dtls_record_method;
314 #endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */