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