Document SSL_set_psk_use_session_callback() and SSL_CTX equivalent

Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3670)

doc/man3/SSL_CTX_set_psk_client_callback.pod

@@ -2,33 +2,44 @@
 
 =head1 NAME
 
-SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client callback
+SSL_psk_client_cb_func,
+SSL_psk_use_session_cb_func,
+SSL_CTX_set_psk_client_callback,
+SSL_set_psk_client_callback,
+SSL_CTX_set_psk_use_session_callback,
+SSL_set_psk_use_session_callback
+- set PSK client callback
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
+ typedef unsigned int (*SSL_psk_client_cb_func)(SSL *ssl,
+                                                const char *hint,
+                                                char *identity,
+                                                unsigned int max_identity_len,
+                                                unsigned char *psk,
+                                                unsigned int max_psk_len);
  typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md,
                                             const unsigned char **id,
                                             size_t *idlen,
                                             SSL_SESSION **sess);
 
- void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx,
-     unsigned int (*callback)(SSL *ssl, const char *hint,
-                              char *identity, unsigned int max_identity_len,
-                              unsigned char *psk, unsigned int max_psk_len));
- void SSL_set_psk_client_callback(SSL *ssl,
-     unsigned int (*callback)(SSL *ssl, const char *hint,
-                              char *identity, unsigned int max_identity_len,
-                              unsigned char *psk, unsigned int max_psk_len));
+ void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, SSL_psk_client_cb_func cb);
+ void SSL_set_psk_client_callback(SSL *ssl, SSL_psk_client_cb_func cb);
 
  void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx,
                                            SSL_psk_use_session_cb_func cb);
+ void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb);
 
 =head1 DESCRIPTION
 
-A client application must provide a callback function which is called
-when the client is sending the ClientKeyExchange message to the server.
+TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not
+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.
 
 The purpose of the callback function is to select the PSK identity and
 the pre-shared key to use during the connection setup phase.
@@ -42,23 +53,86 @@ B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
 length B<max_psk_len> bytes where the resulting pre-shared key is to
 be stored.
 
+A client application wishing to use TLSv1.3 PSKs must set a different callback
+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 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
+case the server will have specified a ciphersuite to use already and the PSK
+must be compatible with the digest for that ciphersuite. The digest will be
+given in B<md>. The PSK returned by the callback is allowed to be different
+between the first and second time it is called.
+
+On successful completion the callback must store a pointer to an identifier for
+the PSK in B<*id>. The identifier length in bytes should be stored in B<*idlen>.
+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
+B<*sess>. This is used as the basis for the PSK, and should, at a minimum, have
+the following fields set:
+
+=over 4
+
+=item The master key
+
+This can be set via a call to L<SSL_SESSION_set1_master_key(3)>.
+
+=item A ciphersuite
+
+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 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.
+
+=back
+
+Alternatively an SSL_SESSION created from a previous non-PSK handshake may also
+be used as the basis for a PSK.
+
+Ownership of the SSL_SESSION object is passed to the OpenSSL library and so it
+should not be freed by the application.
+
+It is also possible for the callback to succeed but not supply a PSK. In this
+case no PSK will be sent to the server but the handshake will continue. To do
+this the callback should return successfully and ensure that the B<*sess> is
+NULL. The contents of B<*id> and B<*idlen> will be ignored.
+
 =head1 NOTES
 
 Note that parameter B<hint> given to the callback may be B<NULL>.
 
+A connection established via a TLSv1.3 PSK will appear as if session resumption
+has occurred so that L<SSL_session_reused(3)> will return true.
+
 =head1 RETURN VALUES
 
-Return values from the client callback are interpreted as follows:
+Return values from the 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 length (> 0) of B<psk> in bytes is returned.
 
-Otherwise or on errors callback should return 0. In this case
+Otherwise or on errors the callback should return 0. In this case
 the connection setup fails.
 
+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 COPYRIGHT
 
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man3/SSL_CTX_use_psk_identity_hint.pod

@@ -2,58 +2,88 @@
 
 =head1 NAME
 
-SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint,
-SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK
-identity hint to use
+SSL_psk_server_cb_func,
+SSL_psk_find_session_cb_func,
+SSL_CTX_use_psk_identity_hint,
+SSL_use_psk_identity_hint,
+SSL_CTX_set_psk_server_callback,
+SSL_set_psk_server_callback,
+SSL_CTX_set_psk_find_session_callback,
+SSL_set_psk_find_session_callback
+- set PSK identity hint to use
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
+ typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl,
+                                                const char *identity,
+                                                unsigned char *psk,
+                                                unsigned int max_psk_len);
+
+ typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl,
+                                             const unsigned char *identity,
+                                             size_t identity_len,
+                                             SSL_SESSION **sess);
+
  int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
  int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
 
- void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx,
-                                      unsigned int (*callback)(SSL *ssl,
-                                                               const char *identity,
-                                                               unsigned char *psk,
-                                                               int max_psk_len));
- void SSL_set_psk_server_callback(SSL *ssl,
-                                  unsigned int (*callback)(SSL *ssl,
-                                                           const char *identity,
-                                                           unsigned char *psk,
-                                                           int max_psk_len));
+ void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb);
+ void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb);
 
+ void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx,
+                                            SSL_psk_find_session_cb_func cb);
+ void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb);
 
 =head1 DESCRIPTION
 
-SSL_CTX_use_psk_identity_hint() sets the given B<NULL>-terminated PSK
-identity hint B<hint> to SSL context object
-B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated
-PSK identity hint B<hint> to SSL connection object B<ssl>. If B<hint>
-is B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
+TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not
+compatible.
+
+Identity hints are not relevant for TLSv1.3. A server application wishing to use
+PSK ciphersuites for TLSv1.2 and below may call SSL_CTX_use_psk_identity_hint()
+to set the given B<NULL>-terminated PSK identity hint B<hint> for SSL context
+object B<ctx>. SSL_use_psk_identity_hint() sets the given B<NULL>-terminated PSK
+identity hint B<hint> for the SSL connection object B<ssl>. If B<hint> is
+B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
 
-In the case where PSK identity hint is B<NULL>, the server
-does not send the ServerKeyExchange message to the client.
+In the case where PSK identity hint is B<NULL>, the server does not send the
+ServerKeyExchange message to the client.
 
-A server application must provide a callback function which is called
-when the server receives the ClientKeyExchange message from the
+A server application for TLSv1.2 and below must provide a callback function
+which is called when the server receives the ClientKeyExchange message from the
 client. The purpose of the callback function is to validate the
 received PSK identity and to fetch the pre-shared key used during the
-connection setup phase. The callback is set using functions
-SSL_CTX_set_psk_server_callback() or
-SSL_set_psk_server_callback(). The callback function is given the
-connection in parameter B<ssl>, B<NULL>-terminated PSK identity sent
-by the client in parameter B<identity>, and a buffer B<psk> of length
-B<max_psk_len> bytes where the pre-shared key is to be stored.
-
+connection setup phase. The callback is set using the functions
+SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback
+function is given the connection in parameter B<ssl>, B<NULL>-terminated PSK
+identity sent by the client in parameter B<identity>, and a buffer B<psk> of
+length B<max_psk_len> bytes where the pre-shared key is to be stored.
+
+A client application wishing to use TLSv1.3 PSKs must set a different callback
+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> and
+an identity in B<identity> of length B<identity_len>. The callback function
+should identify an SSL_SESSION object that provides the PSK details and store it
+in B<*sess>. The SSL_SESSION object should, as a minimum, set the master key,
+the ciphersuite and the protocol version. See
+L<SSL_CTX_set_psk_use_session_callback(3)> for details.
+
+It is also possible for the callback to succeed but not supply a PSK. In this
+case no PSK will be used but the handshake will continue. To do this the
+callback should return successfully and ensure that B<*sess> is
+NULL.
 
 =head1 RETURN VALUES
 
 SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return
 1 on success, 0 otherwise.
 
-Return values from the server callback are interpreted as follows:
+Return values from the TLSv1.2 and below server callback are interpreted as
+follows:
 
 =over 4
 
@@ -77,9 +107,12 @@ completely.
 
 =back
 
+The SSL_psk_find_session_cb_func callback should return 1 on success or 0 on
+failure. In the event of failure the connection setup fails.
+
 =head1 COPYRIGHT
 
-Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

util/private.num

@@ -22,6 +22,8 @@ GEN_SESSION_CB                          datatype
 OPENSSL_Applink                         external
 SSL_CTX_keylog_cb_func                  datatype
 SSL_early_cb_fn                         datatype
+SSL_psk_client_cb_func                  datatype
+SSL_psk_use_session_cb_func             datatype
 SSL_verify_cb                           datatype
 UI                                      datatype
 UI_METHOD                               datatype