From 79a1f3e4bb62c10d9604718f6814bb8bdde4ffd6 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Thu, 7 Apr 2022 12:30:30 +0100 Subject: [PATCH] Add the recordmethod header from the draft design Reviewed-by: Hugo Landau Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/18132) --- ssl/record/recordmethod.h | 238 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 ssl/record/recordmethod.h diff --git a/ssl/record/recordmethod.h b/ssl/record/recordmethod.h new file mode 100644 index 0000000000..046ac90ff6 --- /dev/null +++ b/ssl/record/recordmethod.h @@ -0,0 +1,238 @@ +/* + * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. + * + * Licensed under the Apache License 2.0 (the "License"). You may not use + * this file except in compliance with the License. You can obtain a copy + * in the file LICENSE in the source distribution or at + * https://www.openssl.org/source/license.html + */ + +#include + +/* + * We use the term "record" here to refer to a packet of data. Records are + * typically protected via a cipher and MAC, or an AEAD cipher (although not + * always). This usage of the term record is consistent with the TLS concept. + * In QUIC the term "record" is not used but it is analogous to the QUIC term + * "packet". The interface in this file applies to all protocols that protect + * records/packets of data, i.e. (D)TLS and QUIC. The term record is used to + * refer to both contexts. + */ + + +/* + * Types of QUIC record layer; + * + * QUIC reuses the TLS handshake for agreeing secrets. An SSL object representing + * a QUIC connection will have an additional SSL object internally representing + * the TLS state of the QUIC handshake. This internal TLS is referred to as + * QUIC-TLS in this file. + * "Records" output from QUIC-TLS contains standard TLS handshake messages and + * are *not* encrypted directly but are instead wrapped up in plaintext + * CRYPTO frames. These CRYPTO frames could be collected together with other + * QUIC frames into a single QUIC packet. The QUIC record layer will then + * encrypt the whole packet. + * + * So we have: + * QUIC-TLS record layer: outputs plaintext CRYPTO frames containing TLS + * handshake messages only. + * QUIC record layer: outputs encrypted packets which may contain CRYPTO frames + * or any other type of QUIC frame. + */ + +/* + * An OSSL_RECORD_METHOD is a protcol specific method which provides the + * functions for reading and writing records for that protocol. Which + * OSSL_RECORD_METHOD to use for a given protocol is defined by the SSL_METHOD. + */ +typedef struct ossl_record_method_st OSSL_RECORD_METHOD; + +/* + * An OSSL_RECORD_LAYER is just an externally defined opaque pointer created by + * the method + */ +typedef struct ossl_record_layer_st OSSL_RECORD_LAYER; + + +#define OSSL_RECORD_ROLE_CLIENT 0 +#define OSSL_RECORD_ROLE_SERVER 1 + +#define OSSL_RECORD_DIRECTION_READ 0 +#define OSSL_RECORD_DIRECTION_WRITE 1 + +/* + * Protection level. For <= TLSv1.2 only "NONE" and "APPLICATION" are used. + */ +#define OSSL_RECORD_PROTECTION_LEVEL_NONE 0 +#define OSSL_RECORD_PROTECTION_LEVEL_EARLY 1 +#define OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE 2 +#define OSSL_RECORD_PROTECTION_LEVEL_APPLICATION 3 + + +/* + * Template for creating a record. A record consists of the |type| of data it + * will contain (e.g. alert, handshake, application data, etc) along with an + * array of buffers in |bufs| of size |numbufs|. There is a corresponding array + * of buffer lengths in |buflens|. Concatenating all of the buffer data together + * would give you the complete plaintext payload to be sent in a single record. + */ +struct ossl_record_template_st { + int type; + void **bufs; + size_t *buflens; + size_t numbufs; +}; + +typedef struct ossl_record_template_st OSSL_RECORD_TEMPLATE; + +/* + * Rather than a "method" approach, we could make this fetchable - Should we? + * There could be some complexity in finding suitable record layer implementations + * e.g. we need to find one that matches the negotiated protocol, cipher, + * extensions, etc. The selection_cb approach given above doesn't work so well + * if unknown third party providers with OSSL_RECORD_METHOD implementations are + * loaded. + */ + +/* + * If this becomes public API then we will need functions to create and + * free an OSSL_RECORD_METHOD, as well as functions to get/set the various + * function pointers....unless we make it fetchable. + */ +struct ossl_record_method_st { + /* + * Create a new OSSL_RECORD_LAYER object for handling the protocol version + * set by |vers|. |role| is 0 for client and 1 for server. |direction| + * indicates either read or write. |level| is the protection level as + * described above. |settings| are mandatory settings that will cause the + * new() call to fail if they are not understood (for example to require + * Encrypt-Then-Mac support). |options| are optional settings that will not + * cause the new() call to fail if they are not understood (for example + * whether to use "read ahead" or not). + * + * The BIO in |transport| is the BIO for the underlying transport layer. + * Where the direction is "read", then this BIO will only ever be used for + * reading data. Where the direction is "write", then this BIO will only + * every be used for writing data. + * + * An SSL object will always have at least 2 OSSL_RECORD_LAYER objects in + * force at any one time (one for reading and one for writing). In some + * protocols more than 2 might be used (e.g. in DTLS for retransmitting + * messages from an earlier epoch). + */ + + /* + * TODO: Will have to be something other than SSL_CIPHER if we make this + * fetchable + */ + OSSL_RECORD_LAYER *new(int vers, int role, int direction, int level, + unsigned char *secret, size_t secretlen, + SSL_CIPHER *c, BIO *transport, BIO_ADDR *local, + BIO_ADDR *peer, OSSL_PARAM *settings, + OSSL_PARAM *options); + void free(OSSL_RECORD_LAYER *rl); + + int reset(OSSL_RECORD_LAYER *rl); /* Is this needed? */ + + /* Returns 1 if we have unprocessed data buffered or 0 otherwise */ + int unprocessed_read_pending(OSSL_RECORD_LAYER *rl); + /* + * Returns 1 if we have processed data buffered that can be read or 0 otherwise + * - not necessarily app data + */ + int processed_read_pending(OSSL_RECORD_LAYER *rl); + + /* + * The amount of processed app data that is internally bufferred and + * available to read + */ + size_t app_data_pending(OSSL_RECORD_LAYER *rl); + + int write_pending(OSSL_RECORD_LAYER *rl); + + + /* + * Find out the maximum amount of plaintext data that the record layer is + * prepared to write in a single record. When calling write_records it is + * the caller's responsibility to ensure that no record template exceeds + * this maximum when calling write_records. + */ + size_t get_max_record_len(OSSL_RECORD_LAYER *rl); + + /* + * Find out the maximum number of records that the record layer is prepared + * to process in a single call to write_records. It is the caller's + * responsibility to ensure that no call to write_records exceeds this + * number of records. + */ + size_t get_max_records(OSSL_RECORD_LAYER *rl); + + /* + * Write |numtempl| records from the array of record templates pointed to + * by |templates|. Each record should be no longer than the value returned + * by get_max_record_len(), and there should be no more records than the + * value returned by get_max_records(). + * |allowance| is the maximum amount of "on-the-wire" data that is allowed + * to be sent at the moment (including all QUIC headers, but excluding any + * UDP/IP headers). After a successful or retry return |*sent| will + * be updated with the amount of data that has been sent so far. In the case + * of a retry this could be 0. + * Where possible the caller will attempt to ensure that all records are the + * same length, except the last record. This may not always be possible so + * the record method implementation should not rely on this being the case. + * In the event of a retry the caller should call retry_write_records() + * to try again. No more calls to write_records() should be attempted until + * retry_write_records() returns success. + * Buffers allocated for the record templates can be freed immediately after + * write_records() returns - even in the case a retry. + * The record templates represent the plaintext payload. The encrypted + * output is written to the |transport| BIO. + * Returns: + * 1 on success + * 0 on retry + * -1 on failure + */ + int write_records(OSSL_RECORD_LAYER *rl, OSSL_RECORD_TEMPLATE **templates, + size_t numtempl, size_t allowance, size_t *sent); + + /* + * Retry a previous call to write_records. The caller should continue to + * call this until the function returns with success or failure. After + * each retry more of the data may have been incrementally sent. |allowance| + * is the amount of "on-the-wire" data that is allowed to be sent at the + * moment. After a successful or retry return |*sent| will + * be updated with the amount of data that has been sent by this call to + * retry_write_records(). + * Returns: + * 1 on success + * 0 on retry + * -1 on failure + */ + int retry_write_records(OSSL_RECORD_LAYER *rl, size_t allowance, + size_t *sent); + + /* + * Read a record and return the record layer version and record type in + * the |rversion| and |type| parameters. |*data| is set to point to a + * record layer buffer containing the record payload data and |*datalen| + * is filled in with the length of that data. The |epoch| and |seq_num| + * values are only used if DTLS has been negotiated. In that case they are + * filled in with the epoch and sequence number from the record. + * An opaque record layer handle for the record is returned in |*rechandle| + * which is used in a subsequent call to |release_record|. The buffer must + * remain available until release_record is called. + * + * Internally the the OSSL_RECORD_METHOD the implementation may read/process + * multiple records in one go and buffer them. + */ + int read_record(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion, + int *type, unsigned char **data, size_t *datalen, + uint16_t *epoch, unsigned char *seq_num); + /* + * Release a buffer associated with a record previously read with + * read_record. Records are guaranteed to be released in the order that they + * are read. + */ + void release_record(OSSL_RECORD_LAYER *rl, void *rechandle); + +};