mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
11653dcd6e
Also, rename the "new" function pointer to "new_record_layer" to avoid a C++ reserved name Reviewed-by: Hugo Landau <hlandau@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/18132)
240 lines
10 KiB
C
240 lines
10 KiB
C
/*
|
|
* 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 <openssl/ssl.h>
|
|
|
|
/*
|
|
* 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_record_layer)(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);
|
|
|
|
};
|