]>
Commit | Line | Data |
---|---|---|
79a1f3e4 MC |
1 | /* |
2 | * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. | |
3 | * | |
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 | |
8 | */ | |
9 | ||
79eebb08 MC |
10 | #ifndef OSSL_INTERNAL_RECORDMETHOD_H |
11 | # define OSSL_INTERNAL_RECORDMETHOD_H | |
12 | # pragma once | |
13 | ||
14 | # include <openssl/ssl.h> | |
79a1f3e4 MC |
15 | |
16 | /* | |
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. | |
24 | */ | |
25 | ||
79a1f3e4 MC |
26 | /* |
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. | |
30 | */ | |
31 | typedef struct ossl_record_method_st OSSL_RECORD_METHOD; | |
32 | ||
33 | /* | |
34 | * An OSSL_RECORD_LAYER is just an externally defined opaque pointer created by | |
35 | * the method | |
36 | */ | |
37 | typedef struct ossl_record_layer_st OSSL_RECORD_LAYER; | |
38 | ||
39 | ||
79eebb08 MC |
40 | # define OSSL_RECORD_ROLE_CLIENT 0 |
41 | # define OSSL_RECORD_ROLE_SERVER 1 | |
79a1f3e4 | 42 | |
79eebb08 MC |
43 | # define OSSL_RECORD_DIRECTION_READ 0 |
44 | # define OSSL_RECORD_DIRECTION_WRITE 1 | |
79a1f3e4 MC |
45 | |
46 | /* | |
47 | * Protection level. For <= TLSv1.2 only "NONE" and "APPLICATION" are used. | |
48 | */ | |
79eebb08 MC |
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 | |
79a1f3e4 | 53 | |
79eebb08 MC |
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 | |
e2d5742b | 59 | |
79a1f3e4 MC |
60 | /* |
61 | * Template for creating a record. A record consists of the |type| of data it | |
a566864b MC |
62 | * will contain (e.g. alert, handshake, application data, etc) along with a |
63 | * buffer of payload data in |buf| of length |buflen|. | |
79a1f3e4 MC |
64 | */ |
65 | struct ossl_record_template_st { | |
66 | int type; | |
1d367677 | 67 | unsigned int version; |
a566864b MC |
68 | const unsigned char *buf; |
69 | size_t buflen; | |
79a1f3e4 MC |
70 | }; |
71 | ||
72 | typedef struct ossl_record_template_st OSSL_RECORD_TEMPLATE; | |
73 | ||
74 | /* | |
75 | * Rather than a "method" approach, we could make this fetchable - Should we? | |
76 | * There could be some complexity in finding suitable record layer implementations | |
77 | * e.g. we need to find one that matches the negotiated protocol, cipher, | |
78 | * extensions, etc. The selection_cb approach given above doesn't work so well | |
79 | * if unknown third party providers with OSSL_RECORD_METHOD implementations are | |
80 | * loaded. | |
81 | */ | |
82 | ||
83 | /* | |
84 | * If this becomes public API then we will need functions to create and | |
85 | * free an OSSL_RECORD_METHOD, as well as functions to get/set the various | |
86 | * function pointers....unless we make it fetchable. | |
87 | */ | |
88 | struct ossl_record_method_st { | |
89 | /* | |
90 | * Create a new OSSL_RECORD_LAYER object for handling the protocol version | |
91 | * set by |vers|. |role| is 0 for client and 1 for server. |direction| | |
92 | * indicates either read or write. |level| is the protection level as | |
93 | * described above. |settings| are mandatory settings that will cause the | |
94 | * new() call to fail if they are not understood (for example to require | |
95 | * Encrypt-Then-Mac support). |options| are optional settings that will not | |
96 | * cause the new() call to fail if they are not understood (for example | |
97 | * whether to use "read ahead" or not). | |
98 | * | |
99 | * The BIO in |transport| is the BIO for the underlying transport layer. | |
100 | * Where the direction is "read", then this BIO will only ever be used for | |
101 | * reading data. Where the direction is "write", then this BIO will only | |
102 | * every be used for writing data. | |
103 | * | |
104 | * An SSL object will always have at least 2 OSSL_RECORD_LAYER objects in | |
105 | * force at any one time (one for reading and one for writing). In some | |
106 | * protocols more than 2 might be used (e.g. in DTLS for retransmitting | |
107 | * messages from an earlier epoch). | |
7c293999 MC |
108 | * |
109 | * The created OSSL_RECORD_LAYER object is stored in *ret on success (or | |
110 | * NULL otherwise). The return value will be one of | |
111 | * OSSL_RECORD_RETURN_SUCCESS, OSSL_RECORD_RETURN_FATAL or | |
112 | * OSSL_RECORD_RETURN_NON_FATAL. A non-fatal return means that creation of | |
113 | * the record layer has failed because it is unsuitable, but an alternative | |
114 | * record layer can be tried instead. | |
79a1f3e4 MC |
115 | */ |
116 | ||
117 | /* | |
4564b47d MC |
118 | * If we eventually make this fetchable then we will need to use something |
119 | * other than EVP_CIPHER. Also mactype would not be a NID, but a string. For | |
120 | * now though, this works. | |
79a1f3e4 | 121 | */ |
7c293999 MC |
122 | int (*new_record_layer)(OSSL_LIB_CTX *libctx, |
123 | const char *propq, int vers, | |
124 | int role, int direction, | |
222cf410 | 125 | int level, |
279754d4 | 126 | uint16_t epoch, |
3f9175c7 MC |
127 | unsigned char *secret, |
128 | size_t secretlen, | |
222cf410 | 129 | unsigned char *key, |
7c293999 MC |
130 | size_t keylen, |
131 | unsigned char *iv, | |
132 | size_t ivlen, | |
133 | unsigned char *mackey, | |
134 | size_t mackeylen, | |
135 | const EVP_CIPHER *ciph, | |
136 | size_t taglen, | |
7c293999 MC |
137 | int mactype, |
138 | const EVP_MD *md, | |
1e76110b | 139 | COMP_METHOD *comp, |
3f9175c7 | 140 | const EVP_MD *kdfdigest, |
359affde MC |
141 | BIO *prev, |
142 | BIO *transport, | |
143 | BIO *next, | |
144 | BIO_ADDR *local, | |
7c293999 MC |
145 | BIO_ADDR *peer, |
146 | const OSSL_PARAM *settings, | |
147 | const OSSL_PARAM *options, | |
9dd90232 MC |
148 | const OSSL_DISPATCH *fns, |
149 | void *cbarg, | |
bea8d704 | 150 | void *rlarg, |
8124ab56 | 151 | OSSL_RECORD_LAYER **ret); |
359affde | 152 | int (*free)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 | 153 | |
79a1f3e4 | 154 | /* Returns 1 if we have unprocessed data buffered or 0 otherwise */ |
11653dcd | 155 | int (*unprocessed_read_pending)(OSSL_RECORD_LAYER *rl); |
1704961c | 156 | |
79a1f3e4 MC |
157 | /* |
158 | * Returns 1 if we have processed data buffered that can be read or 0 otherwise | |
159 | * - not necessarily app data | |
160 | */ | |
11653dcd | 161 | int (*processed_read_pending)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
162 | |
163 | /* | |
164 | * The amount of processed app data that is internally bufferred and | |
165 | * available to read | |
166 | */ | |
11653dcd | 167 | size_t (*app_data_pending)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 | 168 | |
79a1f3e4 MC |
169 | /* |
170 | * Find out the maximum number of records that the record layer is prepared | |
171 | * to process in a single call to write_records. It is the caller's | |
172 | * responsibility to ensure that no call to write_records exceeds this | |
02719d5c | 173 | * number of records. |type| is the type of the records that the caller |
23bf52a4 | 174 | * wants to write, and |len| is the total amount of data that it wants |
02719d5c MC |
175 | * to send. |maxfrag| is the maximum allowed fragment size based on user |
176 | * configuration, or TLS parameter negotiation. |*preffrag| contains on | |
177 | * entry the default fragment size that will actually be used based on user | |
178 | * configuration. This will always be less than or equal to |maxfrag|. On | |
179 | * exit the record layer may update this to an alternative fragment size to | |
180 | * be used. This must always be less than or equal to |maxfrag|. | |
79a1f3e4 | 181 | */ |
23bf52a4 | 182 | size_t (*get_max_records)(OSSL_RECORD_LAYER *rl, int type, size_t len, |
02719d5c | 183 | size_t maxfrag, size_t *preffrag); |
79a1f3e4 MC |
184 | |
185 | /* | |
186 | * Write |numtempl| records from the array of record templates pointed to | |
187 | * by |templates|. Each record should be no longer than the value returned | |
188 | * by get_max_record_len(), and there should be no more records than the | |
189 | * value returned by get_max_records(). | |
79a1f3e4 MC |
190 | * Where possible the caller will attempt to ensure that all records are the |
191 | * same length, except the last record. This may not always be possible so | |
192 | * the record method implementation should not rely on this being the case. | |
193 | * In the event of a retry the caller should call retry_write_records() | |
194 | * to try again. No more calls to write_records() should be attempted until | |
195 | * retry_write_records() returns success. | |
196 | * Buffers allocated for the record templates can be freed immediately after | |
197 | * write_records() returns - even in the case a retry. | |
198 | * The record templates represent the plaintext payload. The encrypted | |
199 | * output is written to the |transport| BIO. | |
200 | * Returns: | |
201 | * 1 on success | |
202 | * 0 on retry | |
203 | * -1 on failure | |
204 | */ | |
2b71b042 MC |
205 | int (*write_records)(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE *templates, |
206 | size_t numtempl); | |
79a1f3e4 MC |
207 | |
208 | /* | |
209 | * Retry a previous call to write_records. The caller should continue to | |
210 | * call this until the function returns with success or failure. After | |
2b71b042 | 211 | * each retry more of the data may have been incrementally sent. |
79a1f3e4 MC |
212 | * Returns: |
213 | * 1 on success | |
214 | * 0 on retry | |
215 | * -1 on failure | |
216 | */ | |
2b71b042 | 217 | int (*retry_write_records)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
218 | |
219 | /* | |
220 | * Read a record and return the record layer version and record type in | |
221 | * the |rversion| and |type| parameters. |*data| is set to point to a | |
222 | * record layer buffer containing the record payload data and |*datalen| | |
223 | * is filled in with the length of that data. The |epoch| and |seq_num| | |
224 | * values are only used if DTLS has been negotiated. In that case they are | |
225 | * filled in with the epoch and sequence number from the record. | |
226 | * An opaque record layer handle for the record is returned in |*rechandle| | |
227 | * which is used in a subsequent call to |release_record|. The buffer must | |
228 | * remain available until release_record is called. | |
229 | * | |
230 | * Internally the the OSSL_RECORD_METHOD the implementation may read/process | |
231 | * multiple records in one go and buffer them. | |
232 | */ | |
11653dcd | 233 | int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion, |
2eb91b0e | 234 | int *type, const unsigned char **data, size_t *datalen, |
8124ab56 | 235 | uint16_t *epoch, unsigned char *seq_num); |
79a1f3e4 MC |
236 | /* |
237 | * Release a buffer associated with a record previously read with | |
238 | * read_record. Records are guaranteed to be released in the order that they | |
239 | * are read. | |
240 | */ | |
4030869d | 241 | int (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle); |
79a1f3e4 | 242 | |
e2d5742b MC |
243 | /* |
244 | * In the event that a fatal error is returned from the functions above then | |
245 | * get_alert_code() can be called to obtain a more details identifier for | |
246 | * the error. In (D)TLS this is the alert description code. | |
247 | */ | |
248 | int (*get_alert_code)(OSSL_RECORD_LAYER *rl); | |
249 | ||
250 | /* | |
251 | * Update the transport BIO from the one originally set in the | |
252 | * new_record_layer call | |
253 | */ | |
254 | int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio); | |
255 | ||
1853d20a MC |
256 | /* Called when protocol negotiation selects a protocol version to use */ |
257 | int (*set_protocol_version)(OSSL_RECORD_LAYER *rl, int version); | |
258 | ||
259 | /* | |
260 | * Whether we are allowed to receive unencrypted alerts, even if we might | |
261 | * otherwise expect encrypted records. Ignored by protocol versions where | |
262 | * this isn't relevant | |
263 | */ | |
264 | void (*set_plain_alerts)(OSSL_RECORD_LAYER *rl, int allow); | |
265 | ||
266 | /* | |
bfc0f10d | 267 | * Called immediately after creation of the record layer if we are in a |
1853d20a MC |
268 | * first handshake. Also called at the end of the first handshake |
269 | */ | |
270 | void (*set_first_handshake)(OSSL_RECORD_LAYER *rl, int first); | |
271 | ||
8124ab56 MC |
272 | /* |
273 | * Set the maximum number of pipelines that the record layer should process. | |
274 | * The default is 1. | |
275 | */ | |
276 | void (*set_max_pipelines)(OSSL_RECORD_LAYER *rl, size_t max_pipelines); | |
277 | ||
bfc0f10d MC |
278 | /* |
279 | * Called to tell the record layer whether we are currently "in init" or | |
280 | * not. Default at creation of the record layer is "yes". | |
281 | */ | |
282 | void (*set_in_init)(OSSL_RECORD_LAYER *rl, int in_init); | |
d0b17ea0 MC |
283 | |
284 | /* | |
285 | * Get a short or long human readable description of the record layer state | |
286 | */ | |
287 | void (*get_state)(OSSL_RECORD_LAYER *rl, const char **shortstr, | |
288 | const char **longstr); | |
4566dae7 MC |
289 | |
290 | /* | |
a53d4f83 | 291 | * Set new options or modify ones that were originally specified in the |
4566dae7 MC |
292 | * new_record_layer call. |
293 | */ | |
294 | int (*set_options)(OSSL_RECORD_LAYER *rl, const OSSL_PARAM *options); | |
1e76110b MC |
295 | |
296 | const COMP_METHOD *(*get_compression)(OSSL_RECORD_LAYER *rl); | |
435d88d7 MC |
297 | |
298 | /* | |
299 | * Set the maximum fragment length to be used for the record layer. This | |
300 | * will override any previous value supplied for the "max_frag_len" | |
301 | * setting during construction of the record layer. | |
302 | */ | |
303 | void (*set_max_frag_len)(OSSL_RECORD_LAYER *rl, size_t max_frag_len); | |
4f428e86 MC |
304 | |
305 | /* | |
306 | * The maximum expansion in bytes that the record layer might add while | |
307 | * writing a record | |
308 | */ | |
309 | size_t (*get_max_record_overhead)(OSSL_RECORD_LAYER *rl); | |
b92fc4ae MC |
310 | |
311 | /* | |
312 | * Increment the record sequence number | |
313 | */ | |
314 | int (*increment_sequence_ctr)(OSSL_RECORD_LAYER *rl); | |
7eb39ecb MC |
315 | |
316 | /* | |
317 | * Allocate read or write buffers. Does nothing if already allocated. | |
318 | * Assumes default buffer length and 1 pipeline. | |
319 | */ | |
320 | int (*alloc_buffers)(OSSL_RECORD_LAYER *rl); | |
321 | ||
322 | /* | |
323 | * Free read or write buffers. Fails if there is pending read or write | |
324 | * data. Buffers are automatically reallocated on next read/write. | |
325 | */ | |
326 | int (*free_buffers)(OSSL_RECORD_LAYER *rl); | |
79a1f3e4 | 327 | }; |
e2d5742b MC |
328 | |
329 | ||
330 | /* Standard built-in record methods */ | |
331 | extern const OSSL_RECORD_METHOD ossl_tls_record_method; | |
cc110a0a MC |
332 | # ifndef OPENSSL_NO_KTLS |
333 | extern const OSSL_RECORD_METHOD ossl_ktls_record_method; | |
334 | # endif | |
79eebb08 MC |
335 | extern const OSSL_RECORD_METHOD ossl_dtls_record_method; |
336 | ||
337 | #endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */ |