mirror of https://github.com/openssl/openssl.git
Add documentation for the new third party QUIC stack API
Reviewed-by: Tim Hudson <tjh@openssl.org> Reviewed-by: Neil Horman <nhorman@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/26683)
This commit is contained in:
Matt Caswell
parent
3cf15554f2
commit
e6bb7eaee0
|
|
@ -2783,6 +2783,10 @@ DEPEND[html/man3/SSL_set_incoming_stream_policy.html]=man3/SSL_set_incoming_stre
|
|||
GENERATE[html/man3/SSL_set_incoming_stream_policy.html]=man3/SSL_set_incoming_stream_policy.pod
|
||||
DEPEND[man/man3/SSL_set_incoming_stream_policy.3]=man3/SSL_set_incoming_stream_policy.pod
|
||||
GENERATE[man/man3/SSL_set_incoming_stream_policy.3]=man3/SSL_set_incoming_stream_policy.pod
|
||||
DEPEND[html/man3/SSL_set_quic_tls_cbs.html]=man3/SSL_set_quic_tls_cbs.pod
|
||||
GENERATE[html/man3/SSL_set_quic_tls_cbs.html]=man3/SSL_set_quic_tls_cbs.pod
|
||||
DEPEND[man/man3/SSL_set_quic_tls_cbs.3]=man3/SSL_set_quic_tls_cbs.pod
|
||||
GENERATE[man/man3/SSL_set_quic_tls_cbs.3]=man3/SSL_set_quic_tls_cbs.pod
|
||||
DEPEND[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod
|
||||
GENERATE[html/man3/SSL_set_retry_verify.html]=man3/SSL_set_retry_verify.pod
|
||||
DEPEND[man/man3/SSL_set_retry_verify.3]=man3/SSL_set_retry_verify.pod
|
||||
|
|
@ -3707,6 +3711,7 @@ html/man3/SSL_set_connect_state.html \
|
|||
html/man3/SSL_set_default_stream_mode.html \
|
||||
html/man3/SSL_set_fd.html \
|
||||
html/man3/SSL_set_incoming_stream_policy.html \
|
||||
html/man3/SSL_set_quic_tls_cbs.html \
|
||||
html/man3/SSL_set_retry_verify.html \
|
||||
html/man3/SSL_set_session.html \
|
||||
html/man3/SSL_set_session_secret_cb.html \
|
||||
|
|
@ -4372,6 +4377,7 @@ man/man3/SSL_set_connect_state.3 \
|
|||
man/man3/SSL_set_default_stream_mode.3 \
|
||||
man/man3/SSL_set_fd.3 \
|
||||
man/man3/SSL_set_incoming_stream_policy.3 \
|
||||
man/man3/SSL_set_quic_tls_cbs.3 \
|
||||
man/man3/SSL_set_retry_verify.3 \
|
||||
man/man3/SSL_set_session.3 \
|
||||
man/man3/SSL_set_session_secret_cb.3 \
|
||||
|
|
|
|||
|
|
@ -74,8 +74,8 @@ typedef struct quic_tls_args_st {
|
|||
size_t *bytes_read, void *arg);
|
||||
void *crypto_recv_cb_arg;
|
||||
|
||||
/* Called when a traffic secret is available for a given encryption level. */
|
||||
int (*yield_secret_cb)(uint32_t enc_level, int direction /* 0=RX, 1=TX */,
|
||||
/* Called when a traffic secret is available for a given TLS protection level. */
|
||||
int (*yield_secret_cb)(uint32_t prot_level, int direction /* 0=RX, 1=TX */,
|
||||
uint32_t suite_id, EVP_MD *md,
|
||||
const unsigned char *secret, size_t secret_len,
|
||||
void *arg);
|
||||
|
|
|
|||
|
|
@ -0,0 +1,178 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn,
|
||||
OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn,
|
||||
OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn,
|
||||
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn,
|
||||
OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn,
|
||||
OSSL_FUNC_SSL_QUIC_TLS_alert_fn,
|
||||
SSL_set_quic_tls_cbs,
|
||||
SSL_set_quic_tls_transport_params
|
||||
- Use the OpenSSL TLS implementation for a third party QUIC implementation
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ssl.h>
|
||||
|
||||
/* QUIC TLS callbacks available via an OSSL_DISPATCH table */
|
||||
|
||||
/* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND */
|
||||
typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn)(SSL *s,
|
||||
const unsigned char *buf,
|
||||
size_t buf_len,
|
||||
size_t *consumed,
|
||||
void *arg);
|
||||
|
||||
/* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD */
|
||||
typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn)(SSL *s,
|
||||
const unsigned char **buf,
|
||||
size_t *bytes_read,
|
||||
void *arg);
|
||||
|
||||
/* Function id: OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD */
|
||||
typedef int (*OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn)(SSL *,
|
||||
size_t bytes_read,
|
||||
void *arg);
|
||||
|
||||
/* Function id: OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET */
|
||||
typedef int (*OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn)(SSL *s,
|
||||
uint32_t prot_level,
|
||||
int direction,
|
||||
const unsigned char *secret,
|
||||
size_t secret_len,
|
||||
void *arg);
|
||||
|
||||
/* Function id: OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS */
|
||||
typedef int (*OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn)(SSL *s,
|
||||
const unsigned char *params,
|
||||
size_t params_len,
|
||||
void *arg);
|
||||
|
||||
/* Function id: OSSL_FUNC_SSL_QUIC_TLS_ALERT */
|
||||
typedef int (*OSSL_FUNC_SSL_QUIC_TLS_alert_fn)(SSL *s,
|
||||
unsigned char alert_code,
|
||||
void *arg);
|
||||
|
||||
int SSL_set_quic_tls_cbs(SSL *s, const OSSL_DISPATCH *qtdis, void *arg);
|
||||
int SSL_set_quic_tls_transport_params(SSL *s,
|
||||
const unsigned char *params,
|
||||
size_t params_len);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
SSL_set_quic_tls_cbs() can be used to replace the standard TLS record layer with
|
||||
a custom record layer for use by a third party QUIC implementation. For the
|
||||
given SSL object I<s>, a set of callbacks are supplied in an B<OSSL_DISPATCH>
|
||||
table via I<qtdis>. The I<arg> parameter will be passed as an argument when the
|
||||
various callbacks are called.
|
||||
|
||||
An B<OSSL_DISPATCH> table should consist of an array of B<OSSL_DISPATCH> entries
|
||||
where each entry is a function id, and a function pointer. The array should be
|
||||
terminated with an empty entry (i.e. a 0 function id, and a NULL function
|
||||
pointer).
|
||||
|
||||
Calling the SSL_set_quic_tls_cbs() function will switch off the
|
||||
B<SSL_OP_ENABLE_MIDDLEBOX_COMPAT> option (if set). See L<SSL_set_options(3)>.
|
||||
Additionally the minimum TLS protocol version will be set to TLS1_3_VERSION. It
|
||||
is an error to call this function with anything other than a TLS connection SSL
|
||||
object.
|
||||
|
||||
The OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn callback (function id
|
||||
B<OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND>) is called when CRYPTO frame data should
|
||||
be sent to the peer. The data to be sent is supplied in the buffer I<buf> which
|
||||
is of length I<buf_len>. The callback may choose to consume less data than was
|
||||
supplied in the buffer. On successful completion of the callback the I<consumed>
|
||||
parameter should be populated with the amount of data that the callback
|
||||
consumed. This should be less than or equal to the value in I<buf_len>. CRYPTO
|
||||
data should be sent using the most recent write encryption level set via the
|
||||
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (if it has been called).
|
||||
|
||||
The OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn callback (function id
|
||||
B<OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD>) is used to receive CRYPTO frame data
|
||||
from the peer. When OpenSSL wants to read data from the peer this callback is
|
||||
called. The callback should populate I<*buf> with a pointer to a buffer
|
||||
containing CRYPTO data that has been received from the peer. The size of the
|
||||
buffer should be populated in I<*bytes_read>. The buffer should remain valid
|
||||
until OpenSSL calls the OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback.
|
||||
CRYPTO frame data is assumed to have been decrypted using the most recent read
|
||||
protection level set via the yield_secret_cb callback (if it has been called).
|
||||
|
||||
The OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn callback (function id
|
||||
B<OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD>) is called when data previously
|
||||
read via OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn is no longer required. The
|
||||
I<bytes_read> argument is always equal to the size of the buffer previously
|
||||
provided in the crypto_receive_rcd_cb callback. Only one record at a time will
|
||||
ever be read by OpenSSL.
|
||||
|
||||
The OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn callback (function id
|
||||
B<OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET>) is called when a new secret has been
|
||||
established. The I<prot_level> argument identies the TLS protection level and
|
||||
will be one of B<OSSL_RECORD_PROTECTION_LEVEL_NONE>,
|
||||
B<OSSL_RECORD_PROTECTION_LEVEL_EARLY>, B<OSSL_RECORD_PROTECTION_LEVEL_HANDSHAKE>
|
||||
or B<OSSL_RECORD_PROTECTION_LEVEL_APPLICATION>. The I<direction> will either be
|
||||
0 (for the read secret) or 1 (for the write secret). The secret itself will
|
||||
be in the buffer pointed to by I<secret> and the buffer will be of length
|
||||
I<secret_len>.
|
||||
|
||||
The OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn callback (function id
|
||||
B<OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS>) is called when transport
|
||||
parameters have been received from the peer. The parameters are held in the
|
||||
I<params> buffer which is of length I<params_len>.
|
||||
|
||||
The OSSL_FUNC_SSL_QUIC_TLS_alert_fn callback (function id
|
||||
B<OSSL_FUNC_SSL_QUIC_TLS_ALERT>) is called when OpenSSL is attempting to send an
|
||||
alert to the peer. The code for the alert is supplied in I<alert_code>.
|
||||
|
||||
The SSL_set_quic_tls_transport_params() function is used to set the transport
|
||||
parameters to be sent by this endpoint. The parameters are in the I<params>
|
||||
buffer which should be of length I<params_len>. The buffer containing the
|
||||
parameters should remain valid until after the parameters have been sent. This
|
||||
function must have been called by the time the transport parameters need to be
|
||||
sent. For a client this will be before the connection has been initiated. For a
|
||||
server this might typically occur during the got_transport_params_cb.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
These functions return 1 on success and 0 on failure.
|
||||
|
||||
All of the callbacks should also return 1 on success and 0 on failure. A
|
||||
failure response is fatal to the connection.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
A call to SSL_set_quic_tls_cbs() might look something like the following, given
|
||||
suitable definitions of the various callback functions:
|
||||
|
||||
const OSSL_DISPATCH qtdis[] = {
|
||||
{OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_SEND, (void (*)(void))crypto_send_cb},
|
||||
{OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RECV_RCD,
|
||||
(void (*)(void))crypto_recv_rcd_cb},
|
||||
{OSSL_FUNC_SSL_QUIC_TLS_CRYPTO_RELEASE_RCD,
|
||||
(void (*)(void))crypto_release_rcd_cb},
|
||||
{OSSL_FUNC_SSL_QUIC_TLS_YIELD_SECRET,
|
||||
(void (*)(void))yield_secret_cb},
|
||||
{OSSL_FUNC_SSL_QUIC_TLS_GOT_TRANSPORT_PARAMS,
|
||||
(void (*)(void))got_transport_params_cb},
|
||||
{OSSL_FUNC_SSL_QUIC_TLS_ALERT, (void (*)(void))alert_cb},
|
||||
{0, NULL}
|
||||
};
|
||||
|
||||
if (!SSL_set_quic_tls_cbs(ssl, qtdis, NULL))
|
||||
goto err;
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
These functions were added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2024 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
|
||||
L<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
|
|
@ -70,6 +70,12 @@ OSSL_ENCODER_CTX datatype
|
|||
OSSL_ENCODER_CONSTRUCT datatype
|
||||
OSSL_ENCODER_CLEANUP datatype
|
||||
OSSL_ENCODER_INSTANCE datatype
|
||||
OSSL_FUNC_SSL_QUIC_TLS_crypto_send_fn datatype
|
||||
OSSL_FUNC_SSL_QUIC_TLS_crypto_recv_rcd_fn datatype
|
||||
OSSL_FUNC_SSL_QUIC_TLS_crypto_release_rcd_fn datatype
|
||||
OSSL_FUNC_SSL_QUIC_TLS_yield_secret_fn datatype
|
||||
OSSL_FUNC_SSL_QUIC_TLS_got_transport_params_fn datatype
|
||||
OSSL_FUNC_SSL_QUIC_TLS_alert_fn datatype
|
||||
OSSL_HTTP_bio_cb_t datatype
|
||||
OSSL_HTTP_REQ_CTX datatype
|
||||
OSSL_IETF_ATTR_SYNTAX datatype
|
||||
|
|
|
|||
Loading…
Reference in New Issue