From: Matt Caswell Date: Thu, 8 Mar 2018 08:20:23 +0000 (+0000) Subject: Update documentation for the new PSK behaviour X-Git-Tag: OpenSSL_1_1_1-pre3~149 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=4a192c77b7bf794a9283a8e7fb4f7bee0d7bff56;p=oweals%2Fopenssl.git Update documentation for the new PSK behaviour Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/5554) --- diff --git a/doc/man3/SSL_CTX_set_psk_client_callback.pod b/doc/man3/SSL_CTX_set_psk_client_callback.pod index e771072f47..5350d797ef 100644 --- a/doc/man3/SSL_CTX_set_psk_client_callback.pod +++ b/doc/man3/SSL_CTX_set_psk_client_callback.pod @@ -14,48 +14,33 @@ SSL_set_psk_use_session_callback #include - 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, 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 -TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not -compatible. + 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); -A client application wishing to use PSK ciphersuites for TLSv1.2 and below must -provide a callback function. This function will be called when the client is -sending the ClientKeyExchange message to the server. + 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); -The purpose of the callback function is to select the PSK identity and -the pre-shared key to use during the connection setup phase. -The callback is set using functions SSL_CTX_set_psk_client_callback() -or SSL_set_psk_client_callback(). The callback function is given the -connection in parameter B, a B-terminated PSK identity hint -sent by the server in parameter B, a buffer B of -length B bytes where the resulting -B-terminated identity is to be stored, and a buffer B of -length B bytes where the resulting pre-shared key is to -be stored. +=head1 DESCRIPTION -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. +A client application wishing to use TLSv1.3 PSKs should use either +SSL_CTX_set_psk_use_session_callback() or SSL_set_psk_use_session_callback() as +appropriate. These functions cannot be used for TLSv1.2 and below PSKs. The callback function is given a pointer to the SSL connection in B. @@ -113,6 +98,33 @@ 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 B<*sess> is NULL. The contents of B<*id> and B<*idlen> will be ignored. +A client application wishing to use PSK ciphersuites for TLSv1.2 and below must +provide a different 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. + +The callback is set using functions SSL_CTX_set_psk_client_callback() +or SSL_set_psk_client_callback(). The callback function is given the +connection in parameter B, a B-terminated PSK identity hint +sent by the server in parameter B, a buffer B of +length B bytes where the resulting +B-terminated identity is to be stored, and a buffer B of +length B bytes where the resulting pre-shared key is to +be stored. + +The callback for use in TLSv1.2 will also work in TLSv1.3 although it is +recommended to use SSL_CTX_set_psk_use_session_callback() +or SSL_set_psk_use_session_callback() for this purpose instead. If TLSv1.3 has +been negotiated then OpenSSL will first check to see if a callback has been set +via SSL_CTX_set_psk_use_session_callback() or SSL_set_psk_use_session_callback() +and it will use that in preference. If no such callback is present then it will +check to see if a callback has been set via SSL_CTX_set_psk_client_callback() or +SSL_set_psk_client_callback() and use that. In this case the B value will +always be NULL and the handshake digest will default to SHA-256 for any returned +PSK. + =head1 NOTES Note that parameter B given to the callback may be B. diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod index d41c0cce74..2f4773d0cd 100644 --- a/doc/man3/SSL_CTX_use_psk_identity_hint.pod +++ b/doc/man3/SSL_CTX_use_psk_identity_hint.pod @@ -16,30 +16,44 @@ SSL_set_psk_find_session_callback #include - 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); + + 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); + + typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl, + const char *identity, + unsigned char *psk, + unsigned int max_psk_len); + 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, 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 -TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not -compatible. +A client application wishing to use TLSv1.3 PSKs should set a 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 pointer to the SSL connection in B and +an identity in B of length B. 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 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. 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() @@ -51,31 +65,25 @@ B the current hint from B or B is deleted. In the case where PSK identity hint is B, the server does not send the ServerKeyExchange message to the client. -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 the functions +A server application wishing to use PSKs 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 the functions SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback function is given the connection in parameter B, B-terminated PSK identity sent by the client in parameter B, and a buffer B of length B 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 pointer to the SSL connection in B and -an identity in B of length B. 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 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. +The callback for use in TLSv1.2 will also work in TLSv1.3 although it is +recommended to use SSL_CTX_set_psk_find_session_callback() +or SSL_set_psk_find_session_callback() for this purpose instead. If TLSv1.3 has +been negotiated then OpenSSL will first check to see if a callback has been set +via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback() +and it will use that in preference. If no such callback is present then it will +check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or +SSL_set_psk_server_callback() and use that. In this case the handshake digest +will default to SHA-256 for any returned PSK. =head1 NOTES