From 93a048a1d8f1f6307aea0c1e7854a40b2daf236f Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 16 Jun 2017 16:27:33 +0100 Subject: [PATCH] Document SSL_set_psk_use_session_callback() and SSL_CTX equivalent Reviewed-by: Rich Salz (Merged from https://github.com/openssl/openssl/pull/3670) --- doc/man3/SSL_CTX_set_psk_client_callback.pod | 102 ++++++++++++++++--- doc/man3/SSL_CTX_use_psk_identity_hint.pod | 95 +++++++++++------ util/private.num | 2 + 3 files changed, 154 insertions(+), 45 deletions(-) diff --git a/doc/man3/SSL_CTX_set_psk_client_callback.pod b/doc/man3/SSL_CTX_set_psk_client_callback.pod index 9a1595964b..6a37e7df3d 100644 --- a/doc/man3/SSL_CTX_set_psk_client_callback.pod +++ b/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 + 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-terminated identity is to be stored, and a buffer B of length B 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. + +The first time the callback is called for a connection the B 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. 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. + +=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 is +non-NULL the handshake digest for the ciphersuite should be the same. +The ciphersuite can be set via a call to . The +handshake digest of an SSL_CIPHER object can be checked using +. + +=item The protocol version + +This can be set via a call to L 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 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. + =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 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 diff --git a/doc/man3/SSL_CTX_use_psk_identity_hint.pod b/doc/man3/SSL_CTX_use_psk_identity_hint.pod index 41384ac626..937518089d 100644 --- a/doc/man3/SSL_CTX_use_psk_identity_hint.pod +++ b/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 + 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-terminated PSK -identity hint B to SSL context object -B. SSL_use_psk_identity_hint() sets the given B-terminated -PSK identity hint B to SSL connection object B. If B -is B the current hint from B or B 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-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. +In the case where PSK identity hint is B, 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, 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. - +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 reference 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 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 diff --git a/util/private.num b/util/private.num index 9488f00a66..10fa954dcf 100644 --- a/util/private.num +++ b/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 -- 2.34.1