X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fman3%2FSSL_CTX_use_psk_identity_hint.pod;h=e3802b74f0e757f649daa3183e839aac38ae6edc;hb=bf973d0697e61a44dc46d08b0421a08a8cb61887;hp=d41c0cce74a5120ab88471ca7dd29d5d1417774d;hpb=e105ae842f4a1ac7d710baefde34773d1a52af3c;p=openssl.git diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod index d41c0cce74..e3802b74f0 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 server application wishing to use TLSv1.3 PSKs should set a callback +using either SSL_CTX_set_psk_find_session_callback() or +SSL_set_psk_find_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,33 +65,27 @@ 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. - -=head1 NOTES +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. TLSv1.3 early data exchanges are +possible in PSK connections only with the B +callback, and are not possible with the B callback. A connection established via a TLSv1.3 PSK will appear as if session resumption has occurred so that L will return true. @@ -115,8 +123,19 @@ completely. The B callback should return 1 on success or 0 on failure. In the event of failure the connection setup fails. +=head1 NOTES + +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 SEE ALSO +L, L, L @@ -127,9 +146,9 @@ were added in OpenSSL 1.1.1. =head1 COPYRIGHT -Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2006-2020 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.