xref: /openssl/include/internal/recordmethod.h (revision ad31628c)
1 /*
2  * Copyright 2022-2023 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 #ifndef OSSL_INTERNAL_RECORDMETHOD_H
11 # define OSSL_INTERNAL_RECORDMETHOD_H
12 # pragma once
13 
14 # include <openssl/ssl.h>
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 
26 /*
27  * An OSSL_RECORD_METHOD is a protocol 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 
40 # define OSSL_RECORD_ROLE_CLIENT 0
41 # define OSSL_RECORD_ROLE_SERVER 1
42 
43 # define OSSL_RECORD_DIRECTION_READ  0
44 # define OSSL_RECORD_DIRECTION_WRITE 1
45 
46 /*
47  * Protection level. For <= TLSv1.2 only "NONE" and "APPLICATION" are used.
48  */
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
53 
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
59 
60 /*
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|.
64  */
65 struct ossl_record_template_st {
66     unsigned char type;
67     unsigned int version;
68     const unsigned char *buf;
69     size_t buflen;
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).
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.
115      */
116 
117     /*
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.
121      */
122     int (*new_record_layer)(OSSL_LIB_CTX *libctx,
123                             const char *propq, int vers,
124                             int role, int direction,
125                             int level,
126                             uint16_t epoch,
127                             unsigned char *secret,
128                             size_t secretlen,
129                             unsigned char *key,
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,
137                             int mactype,
138                             const EVP_MD *md,
139                             COMP_METHOD *comp,
140                             const EVP_MD *kdfdigest,
141                             BIO *prev,
142                             BIO *transport,
143                             BIO *next,
144                             BIO_ADDR *local,
145                             BIO_ADDR *peer,
146                             const OSSL_PARAM *settings,
147                             const OSSL_PARAM *options,
148                             const OSSL_DISPATCH *fns,
149                             void *cbarg,
150                             void *rlarg,
151                             OSSL_RECORD_LAYER **ret);
152     int (*free)(OSSL_RECORD_LAYER *rl);
153 
154     /* Returns 1 if we have unprocessed data buffered or 0 otherwise */
155     int (*unprocessed_read_pending)(OSSL_RECORD_LAYER *rl);
156 
157     /*
158      * Returns 1 if we have processed data buffered that can be read or 0 otherwise
159      * - not necessarily app data
160      */
161     int (*processed_read_pending)(OSSL_RECORD_LAYER *rl);
162 
163     /*
164      * The amount of processed app data that is internally buffered and
165      * available to read
166      */
167     size_t (*app_data_pending)(OSSL_RECORD_LAYER *rl);
168 
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
173      * number of records. |type| is the type of the records that the caller
174      * wants to write, and |len| is the total amount of data that it wants
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|.
181      */
182     size_t (*get_max_records)(OSSL_RECORD_LAYER *rl, uint8_t type, size_t len,
183                               size_t maxfrag, size_t *preffrag);
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().
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      */
205     int (*write_records)(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE *templates,
206                          size_t numtempl);
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
211      * each retry more of the data may have been incrementally sent.
212      * Returns:
213      *  1 on success
214      *  0 on retry
215      * -1 on failure
216      */
217     int (*retry_write_records)(OSSL_RECORD_LAYER *rl);
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 all the bytes from record are released via one or
229      * more release_record calls.
230      *
231      * Internally the OSSL_RECORD_METHOD implementation may read/process
232      * multiple records in one go and buffer them.
233      */
234     int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion,
235                       uint8_t *type, const unsigned char **data, size_t *datalen,
236                       uint16_t *epoch, unsigned char *seq_num);
237     /*
238      * Release length bytes from a buffer associated with a record previously
239      * read with read_record. Once all the bytes from a record are released, the
240      * whole record and its associated buffer is released. Records are
241      * guaranteed to be released in the order that they are read.
242      */
243     int (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle, size_t length);
244 
245     /*
246      * In the event that a fatal error is returned from the functions above then
247      * get_alert_code() can be called to obtain a more details identifier for
248      * the error. In (D)TLS this is the alert description code.
249      */
250     int (*get_alert_code)(OSSL_RECORD_LAYER *rl);
251 
252     /*
253      * Update the transport BIO from the one originally set in the
254      * new_record_layer call
255      */
256     int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio);
257 
258     /* Called when protocol negotiation selects a protocol version to use */
259     int (*set_protocol_version)(OSSL_RECORD_LAYER *rl, int version);
260 
261     /*
262      * Whether we are allowed to receive unencrypted alerts, even if we might
263      * otherwise expect encrypted records. Ignored by protocol versions where
264      * this isn't relevant
265      */
266     void (*set_plain_alerts)(OSSL_RECORD_LAYER *rl, int allow);
267 
268     /*
269      * Called immediately after creation of the record layer if we are in a
270      * first handshake. Also called at the end of the first handshake
271      */
272     void (*set_first_handshake)(OSSL_RECORD_LAYER *rl, int first);
273 
274     /*
275      * Set the maximum number of pipelines that the record layer should process.
276      * The default is 1.
277      */
278     void (*set_max_pipelines)(OSSL_RECORD_LAYER *rl, size_t max_pipelines);
279 
280     /*
281      * Called to tell the record layer whether we are currently "in init" or
282      * not. Default at creation of the record layer is "yes".
283      */
284     void (*set_in_init)(OSSL_RECORD_LAYER *rl, int in_init);
285 
286     /*
287      * Get a short or long human readable description of the record layer state
288      */
289     void (*get_state)(OSSL_RECORD_LAYER *rl, const char **shortstr,
290                       const char **longstr);
291 
292     /*
293      * Set new options or modify ones that were originally specified in the
294      * new_record_layer call.
295      */
296     int (*set_options)(OSSL_RECORD_LAYER *rl, const OSSL_PARAM *options);
297 
298     const COMP_METHOD *(*get_compression)(OSSL_RECORD_LAYER *rl);
299 
300     /*
301      * Set the maximum fragment length to be used for the record layer. This
302      * will override any previous value supplied for the "max_frag_len"
303      * setting during construction of the record layer.
304      */
305     void (*set_max_frag_len)(OSSL_RECORD_LAYER *rl, size_t max_frag_len);
306 
307     /*
308      * The maximum expansion in bytes that the record layer might add while
309      * writing a record
310      */
311     size_t (*get_max_record_overhead)(OSSL_RECORD_LAYER *rl);
312 
313     /*
314      * Increment the record sequence number
315      */
316     int (*increment_sequence_ctr)(OSSL_RECORD_LAYER *rl);
317 
318     /*
319      * Allocate read or write buffers. Does nothing if already allocated.
320      * Assumes default buffer length and 1 pipeline.
321      */
322     int (*alloc_buffers)(OSSL_RECORD_LAYER *rl);
323 
324     /*
325      * Free read or write buffers. Fails if there is pending read or write
326      * data. Buffers are automatically reallocated on next read/write.
327      */
328     int (*free_buffers)(OSSL_RECORD_LAYER *rl);
329 };
330 
331 
332 /* Standard built-in record methods */
333 extern const OSSL_RECORD_METHOD ossl_tls_record_method;
334 # ifndef OPENSSL_NO_KTLS
335 extern const OSSL_RECORD_METHOD ossl_ktls_record_method;
336 # endif
337 extern const OSSL_RECORD_METHOD ossl_dtls_record_method;
338 
339 #endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */
340