X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;f=doc%2Fman3%2FSSL_CTX_set_psk_client_callback.pod;h=e4b8147e4567a404be09e0177025e111601f270e;hb=ed57f7f93508776b898e4c23b65d67f3479edaf1;hp=919b6af2926bdb43b3c53890770acb59565a6dd7;hpb=72257204bd2a88773461150765dfd0e0a428ee86;p=openssl.git diff --git a/doc/man3/SSL_CTX_set_psk_client_callback.pod b/doc/man3/SSL_CTX_set_psk_client_callback.pod index 919b6af292..e4b8147e45 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. @@ -98,6 +83,10 @@ be TLS1_3_VERSION. =back +Additionally the maximum early data value should be set via a call to +L 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. @@ -109,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. @@ -116,6 +132,14 @@ Note that parameter B given to the callback may be B. A connection established via a TLSv1.3 PSK will appear as if session resumption has occurred so that L will return true. +There are no known security issues with sharing the same PSK between TLSv1.2 (or +below) and TLSv1.3. However the RFC has this note of caution: + +"While there is no known way in which the same PSK might produce related output +in both versions, only limited analysis has been done. Implementations can +ensure safety from cross-protocol related output by not reusing PSKs between +TLS 1.3 and TLS 1.2." + =head1 RETURN VALUES Return values from the B callback are interpreted as @@ -130,11 +154,21 @@ 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 SEE ALSO + +L, +L + +=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. +Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +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.