mirror of
https://github.com/opnsense/src.git
synced 2026-06-09 08:43:19 -04:00
b077aed33b
Migrate to OpenSSL 3.0 in advance of FreeBSD 14.0. OpenSSL 1.1.1 (the version we were previously using) will be EOL as of 2023-09-11. Most of the base system has already been updated for a seamless switch to OpenSSL 3.0. For many components we've added `-DOPENSSL_API_COMPAT=0x10100000L` to CFLAGS to specify the API version, which avoids deprecation warnings from OpenSSL 3.0. Changes have also been made to avoid OpenSSL APIs that were already deprecated in OpenSSL 1.1.1. The process of updating to contemporary APIs can continue after this merge. Additional changes are still required for libarchive and Kerberos- related libraries or tools; workarounds will immediately follow this commit. Fixes are in progress in the upstream projects and will be incorporated when those are next updated. There are some performance regressions in benchmarks (certain tests in `openssl speed`) and in some OpenSSL consumers in ports (e.g. haproxy). Investigation will continue for these. Netflix's testing showed no functional regression and a rather small, albeit statistically significant, increase in CPU consumption with OpenSSL 3.0. Thanks to ngie@ and des@ for updating base system components, to antoine@ and bofh@ for ports exp-runs and port fixes/workarounds, and to Netflix and everyone who tested prior to commit or contributed to this update in other ways. PR: 271615 PR: 271656 [exp-run] Relnotes: Yes Sponsored by: The FreeBSD Foundation
104 lines
4.1 KiB
Text
104 lines
4.1 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
SSL_get_client_random,
|
|
SSL_get_server_random,
|
|
SSL_SESSION_get_master_key,
|
|
SSL_SESSION_set1_master_key
|
|
- get internal TLS/SSL random values and get/set master key
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
size_t SSL_get_client_random(const SSL *ssl, unsigned char *out, size_t outlen);
|
|
size_t SSL_get_server_random(const SSL *ssl, unsigned char *out, size_t outlen);
|
|
size_t SSL_SESSION_get_master_key(const SSL_SESSION *session,
|
|
unsigned char *out, size_t outlen);
|
|
int SSL_SESSION_set1_master_key(SSL_SESSION *sess, const unsigned char *in,
|
|
size_t len);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
SSL_get_client_random() extracts the random value sent from the client
|
|
to the server during the initial SSL/TLS handshake. It copies as many
|
|
bytes as it can of this value into the buffer provided in B<out>,
|
|
which must have at least B<outlen> bytes available. It returns the
|
|
total number of bytes that were actually copied. If B<outlen> is
|
|
zero, SSL_get_client_random() copies nothing, and returns the
|
|
total size of the client_random value.
|
|
|
|
SSL_get_server_random() behaves the same, but extracts the random value
|
|
sent from the server to the client during the initial SSL/TLS handshake.
|
|
|
|
SSL_SESSION_get_master_key() behaves the same, but extracts the master
|
|
secret used to guarantee the security of the SSL/TLS session. This one
|
|
can be dangerous if misused; see NOTES below.
|
|
|
|
SSL_SESSION_set1_master_key() sets the master key value associated with the
|
|
SSL_SESSION B<sess>. For example, this could be used to set up a session based
|
|
PSK (see L<SSL_CTX_set_psk_use_session_callback(3)>). The master key of length
|
|
B<len> should be provided at B<in>. The supplied master key is copied by the
|
|
function, so the caller is responsible for freeing and cleaning any memory
|
|
associated with B<in>. The caller must ensure that the length of the key is
|
|
suitable for the ciphersuite associated with the SSL_SESSION.
|
|
|
|
=head1 NOTES
|
|
|
|
You probably shouldn't use these functions.
|
|
|
|
These functions expose internal values from the TLS handshake, for
|
|
use in low-level protocols. You probably should not use them, unless
|
|
you are implementing something that needs access to the internal protocol
|
|
details.
|
|
|
|
Despite the names of SSL_get_client_random() and SSL_get_server_random(), they
|
|
ARE NOT random number generators. Instead, they return the mostly-random values that
|
|
were already generated and used in the TLS protocol. Using them
|
|
in place of RAND_bytes() would be grossly foolish.
|
|
|
|
The security of your TLS session depends on keeping the master key secret:
|
|
do not expose it, or any information about it, to anybody.
|
|
If you need to calculate another secret value that depends on the master
|
|
secret, you should probably use SSL_export_keying_material() instead, and
|
|
forget that you ever saw these functions.
|
|
|
|
In current versions of the TLS protocols, the length of client_random
|
|
(and also server_random) is always SSL3_RANDOM_SIZE bytes. Support for
|
|
other outlen arguments to the SSL_get_*_random() functions is provided
|
|
in case of the unlikely event that a future version or variant of TLS
|
|
uses some other length there.
|
|
|
|
Finally, though the "client_random" and "server_random" values are called
|
|
"random", many TLS implementations will generate four bytes of those
|
|
values based on their view of the current time.
|
|
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
SSL_SESSION_set1_master_key() returns 1 on success or 0 on failure.
|
|
|
|
For the other functions, if B<outlen> is greater than 0 then these functions
|
|
return the number of bytes actually copied, which will be less than or equal to
|
|
B<outlen>. If B<outlen> is 0 then these functions return the maximum number
|
|
of bytes they would copy -- that is, the length of the underlying field.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<ssl(7)>,
|
|
L<RAND_bytes(3)>,
|
|
L<SSL_export_keying_material(3)>,
|
|
L<SSL_CTX_set_psk_use_session_callback(3)>
|
|
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2015-2017 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
|