|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_psk_server_cb_func,
|
|
Packit |
c4476c |
SSL_psk_find_session_cb_func,
|
|
Packit |
c4476c |
SSL_CTX_use_psk_identity_hint,
|
|
Packit |
c4476c |
SSL_use_psk_identity_hint,
|
|
Packit |
c4476c |
SSL_CTX_set_psk_server_callback,
|
|
Packit |
c4476c |
SSL_set_psk_server_callback,
|
|
Packit |
c4476c |
SSL_CTX_set_psk_find_session_callback,
|
|
Packit |
c4476c |
SSL_set_psk_find_session_callback
|
|
Packit |
c4476c |
- set PSK identity hint to use
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/ssl.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl,
|
|
Packit |
c4476c |
const unsigned char *identity,
|
|
Packit |
c4476c |
size_t identity_len,
|
|
Packit |
c4476c |
SSL_SESSION **sess);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx,
|
|
Packit |
c4476c |
SSL_psk_find_session_cb_func cb);
|
|
Packit |
c4476c |
void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl,
|
|
Packit |
c4476c |
const char *identity,
|
|
Packit |
c4476c |
unsigned char *psk,
|
|
Packit |
c4476c |
unsigned int max_psk_len);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
|
|
Packit |
c4476c |
int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb);
|
|
Packit |
c4476c |
void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A server application wishing to use TLSv1.3 PSKs should set a callback
|
|
Packit |
c4476c |
using either SSL_CTX_set_psk_find_session_callback() or
|
|
Packit |
c4476c |
SSL_set_psk_find_session_callback() as appropriate.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The callback function is given a pointer to the SSL connection in B<ssl> and
|
|
Packit |
c4476c |
an identity in B<identity> of length B<identity_len>. The callback function
|
|
Packit |
c4476c |
should identify an SSL_SESSION object that provides the PSK details and store it
|
|
Packit |
c4476c |
in B<*sess>. The SSL_SESSION object should, as a minimum, set the master key,
|
|
Packit |
c4476c |
the ciphersuite and the protocol version. See
|
|
Packit |
c4476c |
L<SSL_CTX_set_psk_use_session_callback(3)> for details.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
It is also possible for the callback to succeed but not supply a PSK. In this
|
|
Packit |
c4476c |
case no PSK will be used but the handshake will continue. To do this the
|
|
Packit |
c4476c |
callback should return successfully and ensure that B<*sess> is
|
|
Packit |
c4476c |
NULL.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Identity hints are not relevant for TLSv1.3. A server application wishing to use
|
|
Packit |
c4476c |
PSK ciphersuites for TLSv1.2 and below may call SSL_CTX_use_psk_identity_hint()
|
|
Packit |
c4476c |
to set the given B<NUL>-terminated PSK identity hint B<hint> for SSL context
|
|
Packit |
c4476c |
object B<ctx>. SSL_use_psk_identity_hint() sets the given B<NUL>-terminated PSK
|
|
Packit |
c4476c |
identity hint B<hint> for the SSL connection object B<ssl>. If B<hint> is
|
|
Packit |
c4476c |
B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
In the case where PSK identity hint is B<NULL>, the server does not send the
|
|
Packit |
c4476c |
ServerKeyExchange message to the client.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A server application wishing to use PSKs for TLSv1.2 and below must provide a
|
|
Packit |
c4476c |
callback function which is called when the server receives the
|
|
Packit |
c4476c |
ClientKeyExchange message from the client. The purpose of the callback function
|
|
Packit |
c4476c |
is to validate the received PSK identity and to fetch the pre-shared key used
|
|
Packit |
c4476c |
during the connection setup phase. The callback is set using the functions
|
|
Packit |
c4476c |
SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback
|
|
Packit |
c4476c |
function is given the connection in parameter B<ssl>, B<NUL>-terminated PSK
|
|
Packit |
c4476c |
identity sent by the client in parameter B<identity>, and a buffer B<psk> of
|
|
Packit |
c4476c |
length B<max_psk_len> bytes where the pre-shared key is to be stored.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The callback for use in TLSv1.2 will also work in TLSv1.3 although it is
|
|
Packit |
c4476c |
recommended to use SSL_CTX_set_psk_find_session_callback()
|
|
Packit |
c4476c |
or SSL_set_psk_find_session_callback() for this purpose instead. If TLSv1.3 has
|
|
Packit |
c4476c |
been negotiated then OpenSSL will first check to see if a callback has been set
|
|
Packit |
c4476c |
via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback()
|
|
Packit |
c4476c |
and it will use that in preference. If no such callback is present then it will
|
|
Packit |
c4476c |
check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or
|
|
Packit |
c4476c |
SSL_set_psk_server_callback() and use that. In this case the handshake digest
|
|
Packit |
c4476c |
will default to SHA-256 for any returned PSK.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NOTES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A connection established via a TLSv1.3 PSK will appear as if session resumption
|
|
Packit |
c4476c |
has occurred so that L<SSL_session_reused(3)> will return true.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
B<SSL_CTX_use_psk_identity_hint()> and B<SSL_use_psk_identity_hint()> return
|
|
Packit |
c4476c |
1 on success, 0 otherwise.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Return values from the TLSv1.2 and below server callback are interpreted as
|
|
Packit |
c4476c |
follows:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item Z<>0
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
PSK identity was not found. An "unknown_psk_identity" alert message
|
|
Packit |
c4476c |
will be sent and the connection setup fails.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item E<gt>0
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
PSK identity was found and the server callback has provided the PSK
|
|
Packit |
c4476c |
successfully in parameter B<psk>. Return value is the length of
|
|
Packit |
c4476c |
B<psk> in bytes. It is an error to return a value greater than
|
|
Packit |
c4476c |
B<max_psk_len>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
If the PSK identity was not found but the callback instructs the
|
|
Packit |
c4476c |
protocol to continue anyway, the callback must provide some random
|
|
Packit |
c4476c |
data to B<psk> and return the length of the random data, so the
|
|
Packit |
c4476c |
connection will fail with decryption_error before it will be finished
|
|
Packit |
c4476c |
completely.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The B<SSL_psk_find_session_cb_func> callback should return 1 on success or 0 on
|
|
Packit |
c4476c |
failure. In the event of failure the connection setup fails.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NOTES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
There are no known security issues with sharing the same PSK between TLSv1.2 (or
|
|
Packit |
c4476c |
below) and TLSv1.3. However the RFC has this note of caution:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
"While there is no known way in which the same PSK might produce related output
|
|
Packit |
c4476c |
in both versions, only limited analysis has been done. Implementations can
|
|
Packit |
c4476c |
ensure safety from cross-protocol related output by not reusing PSKs between
|
|
Packit |
c4476c |
TLS 1.3 and TLS 1.2."
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<SSL_CTX_set_psk_use_session_callback(3)>,
|
|
Packit |
c4476c |
L<SSL_set_psk_use_session_callback(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 HISTORY
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_CTX_set_psk_find_session_callback() and SSL_set_psk_find_session_callback()
|
|
Packit |
c4476c |
were added in OpenSSL 1.1.1.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|