From: Tomas Mraz Date: Thu, 12 May 2022 13:41:51 +0000 (+0200) Subject: Add OSSL_QUIC methods to headers and manual pages X-Git-Tag: openssl-3.2.0-alpha1~2569 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=770ea54b58769bae07e22a92e0c12ece9bdbc8e2;p=thirdparty%2Fopenssl.git Add OSSL_QUIC methods to headers and manual pages Reviewed-by: Matt Caswell Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/18307) --- diff --git a/Configurations/unix-Makefile.tmpl b/Configurations/unix-Makefile.tmpl index 110ba0687d8..d9dee171312 100644 --- a/Configurations/unix-Makefile.tmpl +++ b/Configurations/unix-Makefile.tmpl @@ -1257,6 +1257,7 @@ errors: include/openssl/tls1.h include/openssl/dtls1.h include/openssl/srtp.h + include/openssl/quic.h include/openssl/sslerr_legacy.h ); my @cryptoheaders_tmpl = qw( include/internal/dso.h diff --git a/doc/build.info b/doc/build.info index 01ae209e505..0977b03023c 100644 --- a/doc/build.info +++ b/doc/build.info @@ -1675,6 +1675,10 @@ DEPEND[html/man3/OSSL_PROVIDER.html]=man3/OSSL_PROVIDER.pod GENERATE[html/man3/OSSL_PROVIDER.html]=man3/OSSL_PROVIDER.pod DEPEND[man/man3/OSSL_PROVIDER.3]=man3/OSSL_PROVIDER.pod GENERATE[man/man3/OSSL_PROVIDER.3]=man3/OSSL_PROVIDER.pod +DEPEND[html/man3/OSSL_QUIC_client_method.html]=man3/OSSL_QUIC_client_method.pod +GENERATE[html/man3/OSSL_QUIC_client_method.html]=man3/OSSL_QUIC_client_method.pod +DEPEND[man/man3/OSSL_QUIC_client_method.3]=man3/OSSL_QUIC_client_method.pod +GENERATE[man/man3/OSSL_QUIC_client_method.3]=man3/OSSL_QUIC_client_method.pod DEPEND[html/man3/OSSL_SELF_TEST_new.html]=man3/OSSL_SELF_TEST_new.pod GENERATE[html/man3/OSSL_SELF_TEST_new.html]=man3/OSSL_SELF_TEST_new.pod DEPEND[man/man3/OSSL_SELF_TEST_new.3]=man3/OSSL_SELF_TEST_new.pod @@ -3154,6 +3158,7 @@ html/man3/OSSL_PARAM_allocate_from_text.html \ html/man3/OSSL_PARAM_dup.html \ html/man3/OSSL_PARAM_int.html \ html/man3/OSSL_PROVIDER.html \ +html/man3/OSSL_QUIC_client_method.html \ html/man3/OSSL_SELF_TEST_new.html \ html/man3/OSSL_SELF_TEST_set_callback.html \ html/man3/OSSL_STORE_INFO.html \ @@ -3750,6 +3755,7 @@ man/man3/OSSL_PARAM_allocate_from_text.3 \ man/man3/OSSL_PARAM_dup.3 \ man/man3/OSSL_PARAM_int.3 \ man/man3/OSSL_PROVIDER.3 \ +man/man3/OSSL_QUIC_client_method.3 \ man/man3/OSSL_SELF_TEST_new.3 \ man/man3/OSSL_SELF_TEST_set_callback.3 \ man/man3/OSSL_STORE_INFO.3 \ diff --git a/doc/man3/OSSL_QUIC_client_method.pod b/doc/man3/OSSL_QUIC_client_method.pod new file mode 100644 index 00000000000..862e36d035c --- /dev/null +++ b/doc/man3/OSSL_QUIC_client_method.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +OSSL_QUIC_client_method, OSSL_QUIC_client_thread_method, +OSSL_QUIC_server_method +- Provide SSL_METHOD objects for QUIC enabled functions + +=head1 SYNOPSIS + + #include + + const SSL_METHOD *OSSL_QUIC_client_method(void); + const SSL_METHOD *OSSL_QUIC_client_thread_method(void); + const SSL_METHOD *OSSL_QUIC_server_method(void); + +=head1 DESCRIPTION + +The OSSL_QUIC_client_method(), OSSL_QUIC_client_thread_method(), and +OSSL_QUIC_server_method() functions provide methods for the +L function to provide QUIC protocol support. + +The OSSL_QUIC_client_thread_method() uses threads to allow for a blocking +mode of operation and avoid the need to return control to the +OpenSSL library for processing time based events. +The OSSL_QUIC_client_method() does not use threads and depends on +nonblocking mode of operation and the application periodically calling SSL +functions. + +The OSSL_QUIC_server_method() is currently experimental and unsupported. +It is provided for testing purposes. It does not provide a QUIC server +implementation compliant with the QUIC specification. + +=head1 RETURN VALUES + +These functions return pointers to the constant method objects. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +OSSL_QUIC_client_method(), OSSL_QUIC_client_thread_method(), and +OSSL_QUIC_server_method() were added in OpenSSL 3.1. + +=head1 COPYRIGHT + +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 +L. + +=cut diff --git a/include/openssl/quic.h b/include/openssl/quic.h new file mode 100644 index 00000000000..781971ad66d --- /dev/null +++ b/include/openssl/quic.h @@ -0,0 +1,43 @@ +/* + * 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 + */ + +#ifndef OPENSSL_QUIC_H +# define OPENSSL_QUIC_H +# pragma once + +# include +# include + +# ifndef OPENSSL_NO_QUIC + +# ifdef __cplusplus +extern "C" { +# endif + +/* + * Method used for non-thread-assisted QUIC client operation. + */ +__owur const SSL_METHOD *OSSL_QUIC_client_method(void); +/* + * Method used for thread-assisted QUIC client operation. + */ +__owur const SSL_METHOD *OSSL_QUIC_client_thread_method(void); +/* + * This method does not implement full server operation, + * is used for testing, and is subject to change in later + * releases. + */ +__owur const SSL_METHOD *OSSL_QUIC_server_method(void); + +# ifdef __cplusplus +} +# endif + +# endif /* OPENSSL_NO_QUIC */ +#endif diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in index 0c062ded3ed..d2cad44b917 100644 --- a/include/openssl/ssl.h.in +++ b/include/openssl/ssl.h.in @@ -945,6 +945,7 @@ uint32_t SSL_get_recv_max_early_data(const SSL *s); # include /* This is mostly sslv3 with a few tweaks */ # include /* Datagram TLS */ # include /* Support for the use_srtp extension */ +# include #ifdef __cplusplus extern "C" { diff --git a/util/libssl.num b/util/libssl.num index c7afa8fdb0c..f38012075ca 100644 --- a/util/libssl.num +++ b/util/libssl.num @@ -521,3 +521,6 @@ SSL_set0_tmp_dh_pkey 521 3_0_0 EXIST::FUNCTION: SSL_CTX_set0_tmp_dh_pkey 522 3_0_0 EXIST::FUNCTION: SSL_group_to_name 523 3_0_0 EXIST::FUNCTION: SSL_client_hello_get_extension_order ? 3_1_0 EXIST::FUNCTION: +OSSL_QUIC_client_method ? 3_1_0 EXIST::FUNCTION:QUIC +OSSL_QUIC_client_thread_method ? 3_1_0 EXIST::FUNCTION:QUIC +OSSL_QUIC_server_method ? 3_1_0 EXIST::FUNCTION:QUIC