]>
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 | ||
10 | #include <openssl/ssl.h> | |
11 | ||
12 | /* | |
13 | * We use the term "record" here to refer to a packet of data. Records are | |
14 | * typically protected via a cipher and MAC, or an AEAD cipher (although not | |
15 | * always). This usage of the term record is consistent with the TLS concept. | |
16 | * In QUIC the term "record" is not used but it is analogous to the QUIC term | |
17 | * "packet". The interface in this file applies to all protocols that protect | |
18 | * records/packets of data, i.e. (D)TLS and QUIC. The term record is used to | |
19 | * refer to both contexts. | |
20 | */ | |
21 | ||
22 | ||
23 | /* | |
24 | * Types of QUIC record layer; | |
25 | * | |
26 | * QUIC reuses the TLS handshake for agreeing secrets. An SSL object representing | |
27 | * a QUIC connection will have an additional SSL object internally representing | |
28 | * the TLS state of the QUIC handshake. This internal TLS is referred to as | |
29 | * QUIC-TLS in this file. | |
30 | * "Records" output from QUIC-TLS contains standard TLS handshake messages and | |
31 | * are *not* encrypted directly but are instead wrapped up in plaintext | |
32 | * CRYPTO frames. These CRYPTO frames could be collected together with other | |
33 | * QUIC frames into a single QUIC packet. The QUIC record layer will then | |
34 | * encrypt the whole packet. | |
35 | * | |
36 | * So we have: | |
37 | * QUIC-TLS record layer: outputs plaintext CRYPTO frames containing TLS | |
38 | * handshake messages only. | |
39 | * QUIC record layer: outputs encrypted packets which may contain CRYPTO frames | |
40 | * or any other type of QUIC frame. | |
41 | */ | |
42 | ||
43 | /* | |
44 | * An OSSL_RECORD_METHOD is a protcol specific method which provides the | |
45 | * functions for reading and writing records for that protocol. Which | |
46 | * OSSL_RECORD_METHOD to use for a given protocol is defined by the SSL_METHOD. | |
47 | */ | |
48 | typedef struct ossl_record_method_st OSSL_RECORD_METHOD; | |
49 | ||
50 | /* | |
51 | * An OSSL_RECORD_LAYER is just an externally defined opaque pointer created by | |
52 | * the method | |
53 | */ | |
54 | typedef struct ossl_record_layer_st OSSL_RECORD_LAYER; | |
55 | ||
56 | ||
57 | #define OSSL_RECORD_ROLE_CLIENT 0 | |
58 | #define OSSL_RECORD_ROLE_SERVER 1 | |
59 | ||
60 | #define OSSL_RECORD_DIRECTION_READ 0 | |
61 | #define OSSL_RECORD_DIRECTION_WRITE 1 | |
62 | ||
63 | /* | |
64 | * Protection level. For <= TLSv1.2 only "NONE" and "APPLICATION" are used. | |
65 | */ | |
66 | #define OSSL_RECORD_PROTECTION_LEVEL_NONE 0 | |
67 | #define OSSL_RECORD_PROTECTION_LEVEL_EARLY 1 | |
68 | #define OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE 2 | |
69 | #define OSSL_RECORD_PROTECTION_LEVEL_APPLICATION 3 | |
70 | ||
71 | ||
e2d5742b MC |
72 | #define OSSL_RECORD_RETURN_SUCCESS 1 |
73 | #define OSSL_RECORD_RETURN_RETRY 0 | |
74 | #define OSSL_RECORD_RETURN_NON_FATAL_ERR -1 | |
75 | #define OSSL_RECORD_RETURN_FATAL -2 | |
76 | #define OSSL_RECORD_RETURN_EOF -3 | |
77 | ||
79a1f3e4 MC |
78 | /* |
79 | * Template for creating a record. A record consists of the |type| of data it | |
80 | * will contain (e.g. alert, handshake, application data, etc) along with an | |
81 | * array of buffers in |bufs| of size |numbufs|. There is a corresponding array | |
82 | * of buffer lengths in |buflens|. Concatenating all of the buffer data together | |
83 | * would give you the complete plaintext payload to be sent in a single record. | |
84 | */ | |
85 | struct ossl_record_template_st { | |
86 | int type; | |
87 | void **bufs; | |
88 | size_t *buflens; | |
89 | size_t numbufs; | |
90 | }; | |
91 | ||
92 | typedef struct ossl_record_template_st OSSL_RECORD_TEMPLATE; | |
93 | ||
94 | /* | |
95 | * Rather than a "method" approach, we could make this fetchable - Should we? | |
96 | * There could be some complexity in finding suitable record layer implementations | |
97 | * e.g. we need to find one that matches the negotiated protocol, cipher, | |
98 | * extensions, etc. The selection_cb approach given above doesn't work so well | |
99 | * if unknown third party providers with OSSL_RECORD_METHOD implementations are | |
100 | * loaded. | |
101 | */ | |
102 | ||
103 | /* | |
104 | * If this becomes public API then we will need functions to create and | |
105 | * free an OSSL_RECORD_METHOD, as well as functions to get/set the various | |
106 | * function pointers....unless we make it fetchable. | |
107 | */ | |
108 | struct ossl_record_method_st { | |
109 | /* | |
110 | * Create a new OSSL_RECORD_LAYER object for handling the protocol version | |
111 | * set by |vers|. |role| is 0 for client and 1 for server. |direction| | |
112 | * indicates either read or write. |level| is the protection level as | |
113 | * described above. |settings| are mandatory settings that will cause the | |
114 | * new() call to fail if they are not understood (for example to require | |
115 | * Encrypt-Then-Mac support). |options| are optional settings that will not | |
116 | * cause the new() call to fail if they are not understood (for example | |
117 | * whether to use "read ahead" or not). | |
118 | * | |
119 | * The BIO in |transport| is the BIO for the underlying transport layer. | |
120 | * Where the direction is "read", then this BIO will only ever be used for | |
121 | * reading data. Where the direction is "write", then this BIO will only | |
122 | * every be used for writing data. | |
123 | * | |
124 | * An SSL object will always have at least 2 OSSL_RECORD_LAYER objects in | |
125 | * force at any one time (one for reading and one for writing). In some | |
126 | * protocols more than 2 might be used (e.g. in DTLS for retransmitting | |
127 | * messages from an earlier epoch). | |
128 | */ | |
129 | ||
130 | /* | |
131 | * TODO: Will have to be something other than SSL_CIPHER if we make this | |
132 | * fetchable | |
133 | */ | |
11653dcd MC |
134 | OSSL_RECORD_LAYER *(*new_record_layer)(int vers, int role, int direction, |
135 | int level, unsigned char *secret, | |
136 | size_t secretlen, SSL_CIPHER *c, | |
137 | BIO *transport, BIO_ADDR *local, | |
0c974fc7 MC |
138 | BIO_ADDR *peer, |
139 | const OSSL_PARAM *settings, | |
140 | const OSSL_PARAM *options); | |
11653dcd | 141 | void (*free)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 | 142 | |
11653dcd | 143 | int (*reset)(OSSL_RECORD_LAYER *rl); /* Is this needed? */ |
79a1f3e4 MC |
144 | |
145 | /* Returns 1 if we have unprocessed data buffered or 0 otherwise */ | |
11653dcd | 146 | int (*unprocessed_read_pending)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
147 | /* |
148 | * Returns 1 if we have processed data buffered that can be read or 0 otherwise | |
149 | * - not necessarily app data | |
150 | */ | |
11653dcd | 151 | int (*processed_read_pending)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
152 | |
153 | /* | |
154 | * The amount of processed app data that is internally bufferred and | |
155 | * available to read | |
156 | */ | |
11653dcd | 157 | size_t (*app_data_pending)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 | 158 | |
11653dcd | 159 | int (*write_pending)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
160 | |
161 | ||
162 | /* | |
163 | * Find out the maximum amount of plaintext data that the record layer is | |
164 | * prepared to write in a single record. When calling write_records it is | |
165 | * the caller's responsibility to ensure that no record template exceeds | |
166 | * this maximum when calling write_records. | |
167 | */ | |
11653dcd | 168 | size_t (*get_max_record_len)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
169 | |
170 | /* | |
171 | * Find out the maximum number of records that the record layer is prepared | |
172 | * to process in a single call to write_records. It is the caller's | |
173 | * responsibility to ensure that no call to write_records exceeds this | |
174 | * number of records. | |
175 | */ | |
11653dcd | 176 | size_t (*get_max_records)(OSSL_RECORD_LAYER *rl); |
79a1f3e4 MC |
177 | |
178 | /* | |
179 | * Write |numtempl| records from the array of record templates pointed to | |
180 | * by |templates|. Each record should be no longer than the value returned | |
181 | * by get_max_record_len(), and there should be no more records than the | |
182 | * value returned by get_max_records(). | |
183 | * |allowance| is the maximum amount of "on-the-wire" data that is allowed | |
184 | * to be sent at the moment (including all QUIC headers, but excluding any | |
185 | * UDP/IP headers). After a successful or retry return |*sent| will | |
186 | * be updated with the amount of data that has been sent so far. In the case | |
187 | * of a retry this could be 0. | |
188 | * Where possible the caller will attempt to ensure that all records are the | |
189 | * same length, except the last record. This may not always be possible so | |
190 | * the record method implementation should not rely on this being the case. | |
191 | * In the event of a retry the caller should call retry_write_records() | |
192 | * to try again. No more calls to write_records() should be attempted until | |
193 | * retry_write_records() returns success. | |
194 | * Buffers allocated for the record templates can be freed immediately after | |
195 | * write_records() returns - even in the case a retry. | |
196 | * The record templates represent the plaintext payload. The encrypted | |
197 | * output is written to the |transport| BIO. | |
198 | * Returns: | |
199 | * 1 on success | |
200 | * 0 on retry | |
201 | * -1 on failure | |
202 | */ | |
11653dcd MC |
203 | int (*write_records)(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE **templates, |
204 | size_t numtempl, size_t allowance, size_t *sent); | |
79a1f3e4 MC |
205 | |
206 | /* | |
207 | * Retry a previous call to write_records. The caller should continue to | |
208 | * call this until the function returns with success or failure. After | |
209 | * each retry more of the data may have been incrementally sent. |allowance| | |
210 | * is the amount of "on-the-wire" data that is allowed to be sent at the | |
211 | * moment. After a successful or retry return |*sent| will | |
212 | * be updated with the amount of data that has been sent by this call to | |
213 | * retry_write_records(). | |
214 | * Returns: | |
215 | * 1 on success | |
216 | * 0 on retry | |
217 | * -1 on failure | |
218 | */ | |
11653dcd MC |
219 | int (*retry_write_records)(OSSL_RECORD_LAYER *rl, size_t allowance, |
220 | size_t *sent); | |
79a1f3e4 MC |
221 | |
222 | /* | |
223 | * Read a record and return the record layer version and record type in | |
224 | * the |rversion| and |type| parameters. |*data| is set to point to a | |
225 | * record layer buffer containing the record payload data and |*datalen| | |
226 | * is filled in with the length of that data. The |epoch| and |seq_num| | |
227 | * values are only used if DTLS has been negotiated. In that case they are | |
228 | * filled in with the epoch and sequence number from the record. | |
229 | * An opaque record layer handle for the record is returned in |*rechandle| | |
230 | * which is used in a subsequent call to |release_record|. The buffer must | |
231 | * remain available until release_record is called. | |
232 | * | |
233 | * Internally the the OSSL_RECORD_METHOD the implementation may read/process | |
234 | * multiple records in one go and buffer them. | |
235 | */ | |
11653dcd MC |
236 | int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion, |
237 | int *type, unsigned char **data, size_t *datalen, | |
238 | uint16_t *epoch, unsigned char *seq_num); | |
79a1f3e4 MC |
239 | /* |
240 | * Release a buffer associated with a record previously read with | |
241 | * read_record. Records are guaranteed to be released in the order that they | |
242 | * are read. | |
243 | */ | |
11653dcd | 244 | void (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle); |
79a1f3e4 | 245 | |
e2d5742b MC |
246 | /* |
247 | * In the event that a fatal error is returned from the functions above then | |
248 | * get_alert_code() can be called to obtain a more details identifier for | |
249 | * the error. In (D)TLS this is the alert description code. | |
250 | */ | |
251 | int (*get_alert_code)(OSSL_RECORD_LAYER *rl); | |
252 | ||
253 | /* | |
254 | * Update the transport BIO from the one originally set in the | |
255 | * new_record_layer call | |
256 | */ | |
257 | int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio); | |
258 | ||
259 | /* | |
260 | * TODO(RECLAYER): Remove these. These function pointers are temporary hacks | |
261 | * during the record layer refactoring. They need to be removed before the | |
262 | * refactor is complete. | |
263 | */ | |
264 | int (*read_n)(OSSL_RECORD_LAYER *rl, size_t n, size_t max, int extend, | |
265 | int clearold, size_t *readbytes); | |
266 | SSL3_BUFFER *(*get0_rbuf)(OSSL_RECORD_LAYER *rl); | |
267 | unsigned char *(*get0_packet)(OSSL_RECORD_LAYER *rl); | |
268 | void (*set0_packet)(OSSL_RECORD_LAYER *rl, unsigned char *packet, | |
269 | size_t packetlen); | |
270 | size_t (*get_packet_length)(OSSL_RECORD_LAYER *rl); | |
271 | void (*reset_packet_length)(OSSL_RECORD_LAYER *rl); | |
79a1f3e4 | 272 | }; |
e2d5742b MC |
273 | |
274 | ||
275 | /* Standard built-in record methods */ | |
276 | extern const OSSL_RECORD_METHOD ossl_tls_record_method; | |
277 | extern const OSSL_RECORD_METHOD ossl_dtls_record_method; |