ssl/record/recordmethod.h

   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 a
  63  * buffer of payload data in |buf| of length |buflen|.
  64  */
  65 struct ossl_record_template_st {
  66     int 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 *key,
 128                             size_t keylen,
 129                             unsigned char *iv,
 130                             size_t ivlen,
 131                             unsigned char *mackey,
 132                             size_t mackeylen,
 133                             const EVP_CIPHER *ciph,
 134                             size_t taglen,
 135                             int mactype,
 136                             const EVP_MD *md,
 137                             COMP_METHOD *comp,
 138                             BIO *prev,
 139                             BIO *transport,
 140                             BIO *next,
 141                             BIO_ADDR *local,
 142                             BIO_ADDR *peer,
 143                             const OSSL_PARAM *settings,
 144                             const OSSL_PARAM *options,
 145                             const OSSL_DISPATCH *fns,
 146                             void *cbarg,
 147                             OSSL_RECORD_LAYER **ret);
 148     int (*free)(OSSL_RECORD_LAYER *rl);
 149
 150     int (*reset)(OSSL_RECORD_LAYER *rl); /* Is this needed? */
 151
 152     /* Returns 1 if we have unprocessed data buffered or 0 otherwise */
 153     int (*unprocessed_read_pending)(OSSL_RECORD_LAYER *rl);
 154
 155     /*
 156      * Returns 1 if we have processed data buffered that can be read or 0 otherwise
 157      * - not necessarily app data
 158      */
 159     int (*processed_read_pending)(OSSL_RECORD_LAYER *rl);
 160
 161     /*
 162      * The amount of processed app data that is internally bufferred and
 163      * available to read
 164      */
 165     size_t (*app_data_pending)(OSSL_RECORD_LAYER *rl);
 166
 167     /*
 168      * Find out the maximum number of records that the record layer is prepared
 169      * to process in a single call to write_records. It is the caller's
 170      * responsibility to ensure that no call to write_records exceeds this
 171      * number of records. |type| is the type of the records that the caller
 172      * wants to write, and |len| is the total amount of data that it wants
 173      * to send. |maxfrag| is the maximum allowed fragment size based on user
 174      * configuration, or TLS parameter negotiation. |*preffrag| contains on
 175      * entry the default fragment size that will actually be used based on user
 176      * configuration. This will always be less than or equal to |maxfrag|. On
 177      * exit the record layer may update this to an alternative fragment size to
 178      * be used. This must always be less than or equal to |maxfrag|.
 179      */
 180     size_t (*get_max_records)(OSSL_RECORD_LAYER *rl, int type, size_t len,
 181                               size_t maxfrag, size_t *preffrag);
 182
 183     /*
 184      * Write |numtempl| records from the array of record templates pointed to
 185      * by |templates|. Each record should be no longer than the value returned
 186      * by get_max_record_len(), and there should be no more records than the
 187      * value returned by get_max_records().
 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      */
 203     int (*write_records)(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE *templates,
 204                          size_t numtempl);
 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.
 210      * Returns:
 211      *  1 on success
 212      *  0 on retry
 213      * -1 on failure
 214      */
 215     int (*retry_write_records)(OSSL_RECORD_LAYER *rl);
 216
 217     /*
 218      * Read a record and return the record layer version and record type in
 219      * the |rversion| and |type| parameters. |*data| is set to point to a
 220      * record layer buffer containing the record payload data and |*datalen|
 221      * is filled in with the length of that data. The |epoch| and |seq_num|
 222      * values are only used if DTLS has been negotiated. In that case they are
 223      * filled in with the epoch and sequence number from the record.
 224      * An opaque record layer handle for the record is returned in |*rechandle|
 225      * which is used in a subsequent call to |release_record|. The buffer must
 226      * remain available until release_record is called.
 227      *
 228      * Internally the the OSSL_RECORD_METHOD the implementation may read/process
 229      * multiple records in one go and buffer them.
 230      */
 231     int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion,
 232                       int *type, unsigned char **data, size_t *datalen,
 233                       uint16_t *epoch, unsigned char *seq_num);
 234     /*
 235      * Release a buffer associated with a record previously read with
 236      * read_record. Records are guaranteed to be released in the order that they
 237      * are read.
 238      */
 239     int (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle);
 240
 241     /*
 242      * In the event that a fatal error is returned from the functions above then
 243      * get_alert_code() can be called to obtain a more details identifier for
 244      * the error. In (D)TLS this is the alert description code.
 245      */
 246     int (*get_alert_code)(OSSL_RECORD_LAYER *rl);
 247
 248     /*
 249      * Update the transport BIO from the one originally set in the
 250      * new_record_layer call
 251      */
 252     int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio);
 253
 254     /* Called when protocol negotiation selects a protocol version to use */
 255     int (*set_protocol_version)(OSSL_RECORD_LAYER *rl, int version);
 256
 257     /*
 258      * Whether we are allowed to receive unencrypted alerts, even if we might
 259      * otherwise expect encrypted records. Ignored by protocol versions where
 260      * this isn't relevant
 261      */
 262     void (*set_plain_alerts)(OSSL_RECORD_LAYER *rl, int allow);
 263
 264     /*
 265      * Called immediately after creation of the record layer if we are in a
 266      * first handshake. Also called at the end of the first handshake
 267      */
 268     void (*set_first_handshake)(OSSL_RECORD_LAYER *rl, int first);
 269
 270     /*
 271      * Set the maximum number of pipelines that the record layer should process.
 272      * The default is 1.
 273      */
 274     void (*set_max_pipelines)(OSSL_RECORD_LAYER *rl, size_t max_pipelines);
 275
 276     /*
 277      * Called to tell the record layer whether we are currently "in init" or
 278      * not. Default at creation of the record layer is "yes".
 279      */
 280     void (*set_in_init)(OSSL_RECORD_LAYER *rl, int in_init);
 281
 282     /*
 283      * Get a short or long human readable description of the record layer state
 284      */
 285     void (*get_state)(OSSL_RECORD_LAYER *rl, const char **shortstr,
 286                       const char **longstr);
 287
 288     /*
 289      * Set new options or modify ones that were originally specified in the
 290      * new_record_layer call.
 291      */
 292     int (*set_options)(OSSL_RECORD_LAYER *rl, const OSSL_PARAM *options);
 293
 294     const COMP_METHOD *(*get_compression)(OSSL_RECORD_LAYER *rl);
 295
 296     /*
 297      * Set the maximum fragment length to be used for the record layer. This
 298      * will override any previous value supplied for the "max_frag_len"
 299      * setting during construction of the record layer.
 300      */
 301     void (*set_max_frag_len)(OSSL_RECORD_LAYER *rl, size_t max_frag_len);
 302
 303     /*
 304      * The maximum expansion in bytes that the record layer might add while
 305      * writing a record
 306      */
 307     size_t (*get_max_record_overhead)(OSSL_RECORD_LAYER *rl);
 308
 309     /*
 310      * Increment the record sequence number
 311      */
 312     int (*increment_sequence_ctr)(OSSL_RECORD_LAYER *rl);
 313
 314     /*
 315      * Allocate read or write buffers. Does nothing if already allocated.
 316      * Assumes default buffer length and 1 pipeline.
 317      */
 318     int (*alloc_buffers)(OSSL_RECORD_LAYER *rl);
 319
 320     /*
 321      * Free read or write buffers. Fails if there is pending read or write
 322      * data. Buffers are automatically reallocated on next read/write.
 323      */
 324     int (*free_buffers)(OSSL_RECORD_LAYER *rl);
 325 };
 326
 327
 328 /* Standard built-in record methods */
 329 extern const OSSL_RECORD_METHOD ossl_tls_record_method;
 330 # ifndef OPENSSL_NO_KTLS
 331 extern const OSSL_RECORD_METHOD ossl_ktls_record_method;
 332 # endif
 333 extern const OSSL_RECORD_METHOD ossl_dtls_record_method;
 334
 335 #endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */