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 #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 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 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 an 63 * array of buffers in |bufs| of size |numbufs|. There is a corresponding array 64 * of buffer lengths in |buflens|. Concatenating all of the buffer data together 65 * would give you the complete plaintext payload to be sent in a single record. 66 */ 67 struct ossl_record_template_st { 68 int type; 69 void **bufs; 70 size_t *buflens; 71 size_t numbufs; 72 }; 73 74 typedef struct ossl_record_template_st OSSL_RECORD_TEMPLATE; 75 76 /* 77 * Rather than a "method" approach, we could make this fetchable - Should we? 78 * There could be some complexity in finding suitable record layer implementations 79 * e.g. we need to find one that matches the negotiated protocol, cipher, 80 * extensions, etc. The selection_cb approach given above doesn't work so well 81 * if unknown third party providers with OSSL_RECORD_METHOD implementations are 82 * loaded. 83 */ 84 85 /* 86 * If this becomes public API then we will need functions to create and 87 * free an OSSL_RECORD_METHOD, as well as functions to get/set the various 88 * function pointers....unless we make it fetchable. 89 */ 90 struct ossl_record_method_st { 91 /* 92 * Create a new OSSL_RECORD_LAYER object for handling the protocol version 93 * set by |vers|. |role| is 0 for client and 1 for server. |direction| 94 * indicates either read or write. |level| is the protection level as 95 * described above. |settings| are mandatory settings that will cause the 96 * new() call to fail if they are not understood (for example to require 97 * Encrypt-Then-Mac support). |options| are optional settings that will not 98 * cause the new() call to fail if they are not understood (for example 99 * whether to use "read ahead" or not). 100 * 101 * The BIO in |transport| is the BIO for the underlying transport layer. 102 * Where the direction is "read", then this BIO will only ever be used for 103 * reading data. Where the direction is "write", then this BIO will only 104 * every be used for writing data. 105 * 106 * An SSL object will always have at least 2 OSSL_RECORD_LAYER objects in 107 * force at any one time (one for reading and one for writing). In some 108 * protocols more than 2 might be used (e.g. in DTLS for retransmitting 109 * messages from an earlier epoch). 110 * 111 * The created OSSL_RECORD_LAYER object is stored in *ret on success (or 112 * NULL otherwise). The return value will be one of 113 * OSSL_RECORD_RETURN_SUCCESS, OSSL_RECORD_RETURN_FATAL or 114 * OSSL_RECORD_RETURN_NON_FATAL. A non-fatal return means that creation of 115 * the record layer has failed because it is unsuitable, but an alternative 116 * record layer can be tried instead. 117 */ 118 119 /* 120 * If we eventually make this fetchable then we will need to use something 121 * other than EVP_CIPHER. Also mactype would not be a NID, but a string. For 122 * now though, this works. 123 */ 124 int (*new_record_layer)(OSSL_LIB_CTX *libctx, 125 const char *propq, int vers, 126 int role, int direction, 127 int level, 128 uint16_t epoch, 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 const SSL_COMP *comp, 140 BIO *prev, 141 BIO *transport, 142 BIO *next, 143 BIO_ADDR *local, 144 BIO_ADDR *peer, 145 const OSSL_PARAM *settings, 146 const OSSL_PARAM *options, 147 const OSSL_DISPATCH *fns, 148 void *cbarg, 149 OSSL_RECORD_LAYER **ret); 150 int (*free)(OSSL_RECORD_LAYER *rl); 151 152 int (*reset)(OSSL_RECORD_LAYER *rl); /* Is this needed? */ 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 bufferred and 165 * available to read 166 */ 167 size_t (*app_data_pending)(OSSL_RECORD_LAYER *rl); 168 169 int (*write_pending)(OSSL_RECORD_LAYER *rl); 170 171 /* 172 * Find out the maximum amount of plaintext data that the record layer is 173 * prepared to write in a single record. When calling write_records it is 174 * the caller's responsibility to ensure that no record template exceeds 175 * this maximum when calling write_records. 176 */ 177 size_t (*get_max_record_len)(OSSL_RECORD_LAYER *rl); 178 179 /* 180 * Find out the maximum number of records that the record layer is prepared 181 * to process in a single call to write_records. It is the caller's 182 * responsibility to ensure that no call to write_records exceeds this 183 * number of records. 184 */ 185 size_t (*get_max_records)(OSSL_RECORD_LAYER *rl); 186 187 /* 188 * Write |numtempl| records from the array of record templates pointed to 189 * by |templates|. Each record should be no longer than the value returned 190 * by get_max_record_len(), and there should be no more records than the 191 * value returned by get_max_records(). 192 * |allowance| is the maximum amount of "on-the-wire" data that is allowed 193 * to be sent at the moment (including all QUIC headers, but excluding any 194 * UDP/IP headers). After a successful or retry return |*sent| will 195 * be updated with the amount of data that has been sent so far. In the case 196 * of a retry this could be 0. 197 * Where possible the caller will attempt to ensure that all records are the 198 * same length, except the last record. This may not always be possible so 199 * the record method implementation should not rely on this being the case. 200 * In the event of a retry the caller should call retry_write_records() 201 * to try again. No more calls to write_records() should be attempted until 202 * retry_write_records() returns success. 203 * Buffers allocated for the record templates can be freed immediately after 204 * write_records() returns - even in the case a retry. 205 * The record templates represent the plaintext payload. The encrypted 206 * output is written to the |transport| BIO. 207 * Returns: 208 * 1 on success 209 * 0 on retry 210 * -1 on failure 211 */ 212 int (*write_records)(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE **templates, 213 size_t numtempl, size_t allowance, size_t *sent); 214 215 /* 216 * Retry a previous call to write_records. The caller should continue to 217 * call this until the function returns with success or failure. After 218 * each retry more of the data may have been incrementally sent. |allowance| 219 * is the amount of "on-the-wire" data that is allowed to be sent at the 220 * moment. After a successful or retry return |*sent| will 221 * be updated with the amount of data that has been sent by this call to 222 * retry_write_records(). 223 * Returns: 224 * 1 on success 225 * 0 on retry 226 * -1 on failure 227 */ 228 int (*retry_write_records)(OSSL_RECORD_LAYER *rl, size_t allowance, 229 size_t *sent); 230 231 /* 232 * Read a record and return the record layer version and record type in 233 * the |rversion| and |type| parameters. |*data| is set to point to a 234 * record layer buffer containing the record payload data and |*datalen| 235 * is filled in with the length of that data. The |epoch| and |seq_num| 236 * values are only used if DTLS has been negotiated. In that case they are 237 * filled in with the epoch and sequence number from the record. 238 * An opaque record layer handle for the record is returned in |*rechandle| 239 * which is used in a subsequent call to |release_record|. The buffer must 240 * remain available until release_record is called. 241 * 242 * Internally the the OSSL_RECORD_METHOD the implementation may read/process 243 * multiple records in one go and buffer them. 244 */ 245 int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion, 246 int *type, unsigned char **data, size_t *datalen, 247 uint16_t *epoch, unsigned char *seq_num); 248 /* 249 * Release a buffer associated with a record previously read with 250 * read_record. Records are guaranteed to be released in the order that they 251 * are read. 252 */ 253 int (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle); 254 255 /* 256 * In the event that a fatal error is returned from the functions above then 257 * get_alert_code() can be called to obtain a more details identifier for 258 * the error. In (D)TLS this is the alert description code. 259 */ 260 int (*get_alert_code)(OSSL_RECORD_LAYER *rl); 261 262 /* 263 * Update the transport BIO from the one originally set in the 264 * new_record_layer call 265 */ 266 int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio); 267 268 /* Called when protocol negotiation selects a protocol version to use */ 269 int (*set_protocol_version)(OSSL_RECORD_LAYER *rl, int version); 270 271 /* 272 * Whether we are allowed to receive unencrypted alerts, even if we might 273 * otherwise expect encrypted records. Ignored by protocol versions where 274 * this isn't relevant 275 */ 276 void (*set_plain_alerts)(OSSL_RECORD_LAYER *rl, int allow); 277 278 /* 279 * Called immediately after creation of the record layer if we are in a 280 * first handshake. Also called at the end of the first handshake 281 */ 282 void (*set_first_handshake)(OSSL_RECORD_LAYER *rl, int first); 283 284 /* 285 * Set the maximum number of pipelines that the record layer should process. 286 * The default is 1. 287 */ 288 void (*set_max_pipelines)(OSSL_RECORD_LAYER *rl, size_t max_pipelines); 289 290 /* 291 * Called to tell the record layer whether we are currently "in init" or 292 * not. Default at creation of the record layer is "yes". 293 */ 294 void (*set_in_init)(OSSL_RECORD_LAYER *rl, int in_init); 295 296 /* 297 * Get a short or long human readable description of the record layer state 298 */ 299 void (*get_state)(OSSL_RECORD_LAYER *rl, const char **shortstr, 300 const char **longstr); 301 302 /* 303 * Set new options or modify ones that were originaly specified in the 304 * new_record_layer call. 305 */ 306 int (*set_options)(OSSL_RECORD_LAYER *rl, const OSSL_PARAM *options); 307 }; 308 309 310 /* Standard built-in record methods */ 311 extern const OSSL_RECORD_METHOD ossl_tls_record_method; 312 # ifndef OPENSSL_NO_KTLS 313 extern const OSSL_RECORD_METHOD ossl_ktls_record_method; 314 # endif 315 extern const OSSL_RECORD_METHOD ossl_dtls_record_method; 316 317 #endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */ 318
