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