340 lines
14 KiB
C
340 lines
14 KiB
C
/*
|
|
* Copyright 2022-2023 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
|
|
*/
|
|
|
|
#ifndef OSSL_INTERNAL_RECORDMETHOD_H
|
|
# define OSSL_INTERNAL_RECORDMETHOD_H
|
|
# pragma once
|
|
|
|
# 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.
|
|
*/
|
|
|
|
/*
|
|
* An OSSL_RECORD_METHOD is a protocol 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
|
|
|
|
# define OSSL_RECORD_RETURN_SUCCESS 1
|
|
# define OSSL_RECORD_RETURN_RETRY 0
|
|
# define OSSL_RECORD_RETURN_NON_FATAL_ERR -1
|
|
# define OSSL_RECORD_RETURN_FATAL -2
|
|
# define OSSL_RECORD_RETURN_EOF -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 a
|
|
* buffer of payload data in |buf| of length |buflen|.
|
|
*/
|
|
struct ossl_record_template_st {
|
|
unsigned char type;
|
|
unsigned int version;
|
|
const unsigned char *buf;
|
|
size_t buflen;
|
|
};
|
|
|
|
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).
|
|
*
|
|
* The created OSSL_RECORD_LAYER object is stored in *ret on success (or
|
|
* NULL otherwise). The return value will be one of
|
|
* OSSL_RECORD_RETURN_SUCCESS, OSSL_RECORD_RETURN_FATAL or
|
|
* OSSL_RECORD_RETURN_NON_FATAL. A non-fatal return means that creation of
|
|
* the record layer has failed because it is unsuitable, but an alternative
|
|
* record layer can be tried instead.
|
|
*/
|
|
|
|
/*
|
|
* If we eventually make this fetchable then we will need to use something
|
|
* other than EVP_CIPHER. Also mactype would not be a NID, but a string. For
|
|
* now though, this works.
|
|
*/
|
|
int (*new_record_layer)(OSSL_LIB_CTX *libctx,
|
|
const char *propq, int vers,
|
|
int role, int direction,
|
|
int level,
|
|
uint16_t epoch,
|
|
unsigned char *secret,
|
|
size_t secretlen,
|
|
unsigned char *key,
|
|
size_t keylen,
|
|
unsigned char *iv,
|
|
size_t ivlen,
|
|
unsigned char *mackey,
|
|
size_t mackeylen,
|
|
const EVP_CIPHER *ciph,
|
|
size_t taglen,
|
|
int mactype,
|
|
const EVP_MD *md,
|
|
COMP_METHOD *comp,
|
|
const EVP_MD *kdfdigest,
|
|
BIO *prev,
|
|
BIO *transport,
|
|
BIO *next,
|
|
BIO_ADDR *local,
|
|
BIO_ADDR *peer,
|
|
const OSSL_PARAM *settings,
|
|
const OSSL_PARAM *options,
|
|
const OSSL_DISPATCH *fns,
|
|
void *cbarg,
|
|
void *rlarg,
|
|
OSSL_RECORD_LAYER **ret);
|
|
int (*free)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/* 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 buffered and
|
|
* available to read
|
|
*/
|
|
size_t (*app_data_pending)(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. |type| is the type of the records that the caller
|
|
* wants to write, and |len| is the total amount of data that it wants
|
|
* to send. |maxfrag| is the maximum allowed fragment size based on user
|
|
* configuration, or TLS parameter negotiation. |*preffrag| contains on
|
|
* entry the default fragment size that will actually be used based on user
|
|
* configuration. This will always be less than or equal to |maxfrag|. On
|
|
* exit the record layer may update this to an alternative fragment size to
|
|
* be used. This must always be less than or equal to |maxfrag|.
|
|
*/
|
|
size_t (*get_max_records)(OSSL_RECORD_LAYER *rl, uint8_t type, size_t len,
|
|
size_t maxfrag, size_t *preffrag);
|
|
|
|
/*
|
|
* 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().
|
|
* 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);
|
|
|
|
/*
|
|
* 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.
|
|
* Returns:
|
|
* 1 on success
|
|
* 0 on retry
|
|
* -1 on failure
|
|
*/
|
|
int (*retry_write_records)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/*
|
|
* 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 all the bytes from record are released via one or
|
|
* more release_record calls.
|
|
*
|
|
* Internally the OSSL_RECORD_METHOD implementation may read/process
|
|
* multiple records in one go and buffer them.
|
|
*/
|
|
int (*read_record)(OSSL_RECORD_LAYER *rl, void **rechandle, int *rversion,
|
|
uint8_t *type, const unsigned char **data, size_t *datalen,
|
|
uint16_t *epoch, unsigned char *seq_num);
|
|
/*
|
|
* Release length bytes from a buffer associated with a record previously
|
|
* read with read_record. Once all the bytes from a record are released, the
|
|
* whole record and its associated buffer is released. Records are
|
|
* guaranteed to be released in the order that they are read.
|
|
*/
|
|
int (*release_record)(OSSL_RECORD_LAYER *rl, void *rechandle, size_t length);
|
|
|
|
/*
|
|
* In the event that a fatal error is returned from the functions above then
|
|
* get_alert_code() can be called to obtain a more details identifier for
|
|
* the error. In (D)TLS this is the alert description code.
|
|
*/
|
|
int (*get_alert_code)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/*
|
|
* Update the transport BIO from the one originally set in the
|
|
* new_record_layer call
|
|
*/
|
|
int (*set1_bio)(OSSL_RECORD_LAYER *rl, BIO *bio);
|
|
|
|
/* Called when protocol negotiation selects a protocol version to use */
|
|
int (*set_protocol_version)(OSSL_RECORD_LAYER *rl, int version);
|
|
|
|
/*
|
|
* Whether we are allowed to receive unencrypted alerts, even if we might
|
|
* otherwise expect encrypted records. Ignored by protocol versions where
|
|
* this isn't relevant
|
|
*/
|
|
void (*set_plain_alerts)(OSSL_RECORD_LAYER *rl, int allow);
|
|
|
|
/*
|
|
* Called immediately after creation of the record layer if we are in a
|
|
* first handshake. Also called at the end of the first handshake
|
|
*/
|
|
void (*set_first_handshake)(OSSL_RECORD_LAYER *rl, int first);
|
|
|
|
/*
|
|
* Set the maximum number of pipelines that the record layer should process.
|
|
* The default is 1.
|
|
*/
|
|
void (*set_max_pipelines)(OSSL_RECORD_LAYER *rl, size_t max_pipelines);
|
|
|
|
/*
|
|
* Called to tell the record layer whether we are currently "in init" or
|
|
* not. Default at creation of the record layer is "yes".
|
|
*/
|
|
void (*set_in_init)(OSSL_RECORD_LAYER *rl, int in_init);
|
|
|
|
/*
|
|
* Get a short or long human readable description of the record layer state
|
|
*/
|
|
void (*get_state)(OSSL_RECORD_LAYER *rl, const char **shortstr,
|
|
const char **longstr);
|
|
|
|
/*
|
|
* Set new options or modify ones that were originally specified in the
|
|
* new_record_layer call.
|
|
*/
|
|
int (*set_options)(OSSL_RECORD_LAYER *rl, const OSSL_PARAM *options);
|
|
|
|
const COMP_METHOD *(*get_compression)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/*
|
|
* Set the maximum fragment length to be used for the record layer. This
|
|
* will override any previous value supplied for the "max_frag_len"
|
|
* setting during construction of the record layer.
|
|
*/
|
|
void (*set_max_frag_len)(OSSL_RECORD_LAYER *rl, size_t max_frag_len);
|
|
|
|
/*
|
|
* The maximum expansion in bytes that the record layer might add while
|
|
* writing a record
|
|
*/
|
|
size_t (*get_max_record_overhead)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/*
|
|
* Increment the record sequence number
|
|
*/
|
|
int (*increment_sequence_ctr)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/*
|
|
* Allocate read or write buffers. Does nothing if already allocated.
|
|
* Assumes default buffer length and 1 pipeline.
|
|
*/
|
|
int (*alloc_buffers)(OSSL_RECORD_LAYER *rl);
|
|
|
|
/*
|
|
* Free read or write buffers. Fails if there is pending read or write
|
|
* data. Buffers are automatically reallocated on next read/write.
|
|
*/
|
|
int (*free_buffers)(OSSL_RECORD_LAYER *rl);
|
|
};
|
|
|
|
|
|
/* Standard built-in record methods */
|
|
extern const OSSL_RECORD_METHOD ossl_tls_record_method;
|
|
# ifndef OPENSSL_NO_KTLS
|
|
extern const OSSL_RECORD_METHOD ossl_ktls_record_method;
|
|
# endif
|
|
extern const OSSL_RECORD_METHOD ossl_dtls_record_method;
|
|
|
|
#endif /* !defined(OSSL_INTERNAL_RECORDMETHOD_H) */
|