X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FSSL_CTX_use_psk_identity_hint.pod;h=2335dc40614ae4c35e6ad80ca04e3118de26efc3;hp=d41c0cce74a5120ab88471ca7dd29d5d1417774d;hb=485d336137f2afa62e378bc39dcfa37dcfb222da;hpb=e105ae842f4a1ac7d710baefde34773d1a52af3c diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod index d41c0cce74..2335dc4061 100644 --- a/doc/man3/SSL_CTX_use_psk_identity_hint.pod +++ b/doc/man3/SSL_CTX_use_psk_identity_hint.pod @@ -16,52 +16,30 @@ 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); - 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. + typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl, + const char *identity, + unsigned char *psk, + unsigned int max_psk_len); -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-terminated PSK identity hint B for SSL context -object B. SSL_use_psk_identity_hint() sets the given B-terminated PSK -identity hint B for the SSL connection object B. If B is -B the current hint from B or B is deleted. + int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); + int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); -In the case where PSK identity hint is B, the server does not send the -ServerKeyExchange message to the client. + 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); -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 -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. +=head1 DESCRIPTION -A client application wishing to use TLSv1.3 PSKs must set a different callback +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. @@ -77,7 +55,35 @@ 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 +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-terminated PSK identity hint B for SSL context +object B. SSL_use_psk_identity_hint() sets the given B-terminated PSK +identity hint B for the SSL connection object B. If B is +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 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. + +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. A connection established via a TLSv1.3 PSK will appear as if session resumption has occurred so that L will return true. @@ -115,6 +121,16 @@ 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, @@ -127,9 +143,9 @@ 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.