compatible.
A client application wishing to use PSK ciphersuites for TLSv1.2 and below must
-provide a callback function which is called when the client is sending the
-ClientKeyExchange message to the server.
+provide a callback function. This function will be called when the client is
+sending the ClientKeyExchange message to the server.
The purpose of the callback function is to select the PSK identity and
the pre-shared key to use during the connection setup phase.
using either SSL_CTX_set_psk_use_session_callback() or
SSL_set_psk_use_session_callback() as appropriate.
-The callback function is given a reference to the SSL connection in B<ssl>.
+The callback function is given a pointer to the SSL connection in B<ssl>.
The first time the callback is called for a connection the B<md> parameter is
NULL. In some circumstances the callback will be called a second time. In that
The memory pointed to by B<*id> remains owned by the application and should
be freed by it as required at any point after the handshake is complete.
-Additionally the callback should store a reference to an SSL_SESSION object in
+Additionally the callback should store a pointer to an SSL_SESSION object in
B<*sess>. This is used as the basis for the PSK, and should, at a minimum, have
the following fields set:
Only the handshake digest associated with the ciphersuite is relevant for the
PSK (the server may go on to negotiate any ciphersuite which is compatible with
-the digest). The application can use any TLSv1.3 ciphersuite. Where B<md> is
-non-NULL the handshake digest for the ciphersuite should be the same.
+the digest). The application can use any TLSv1.3 ciphersuite. If B<md> is
+not NULL the handshake digest for the ciphersuite should be the same.
The ciphersuite can be set via a call to <SSL_SESSION_set_cipher(3)>. The
handshake digest of an SSL_CIPHER object can be checked using
<SSL_CIPHER_get_handshake_digest(3)>.
=item The protocol version
-This can be set via a call to L<SSL_SESSION_set_protocol_version> and should be
-TLS1_3_VERSION.
+This can be set via a call to L<SSL_SESSION_set_protocol_version(3)> and should
+be TLS1_3_VERSION.
=back
+Additionally the maximum early data value should be set via a call to
+L<SSL_SESSION_set_max_early_data(3)> if the PSK will be used for sending early
+data.
+
Alternatively an SSL_SESSION created from a previous non-PSK handshake may also
be used as the basis for a PSK.
=head1 RETURN VALUES
-Return values from the SSL_psk_client_cb_func callback are interpreted as
+Return values from the B<SSL_psk_client_cb_func> callback are interpreted as
follows:
On success (callback found a PSK identity and a pre-shared key to use)
The SSL_psk_use_session_cb_func callback should return 1 on success or 0 on
failure. In the event of failure the connection setup fails.
+=head1 SEE ALSO
+
+L<SSL_CTX_set_psk_find_session_callback(3)>,
+L<SSL_set_psk_find_session_callback(3)>
+
+=head1 HISTORY
+
+SSL_CTX_set_psk_use_session_callback() and SSL_set_psk_use_session_callback()
+were added in OpenSSL 1.1.1.
+
=head1 COPYRIGHT
Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.