X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fman3%2FSSL_CTX_set_psk_client_callback.pod;h=5a48e13129e45185f048a37e372eb533d33b5549;hb=e17e1df77e651e557ad8fc67e2bea0bbcf98f153;hp=6a37e7df3d8b0220fe9ee2743df874f9702d14c4;hpb=93a048a1d8f1f6307aea0c1e7854a40b2daf236f;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 6a37e7df3d..5a48e13129 100644 --- a/doc/man3/SSL_CTX_set_psk_client_callback.pod +++ b/doc/man3/SSL_CTX_set_psk_client_callback.pod @@ -38,8 +38,8 @@ 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. +provide a 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. @@ -57,7 +57,7 @@ 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 callback function is given a pointer 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 @@ -71,7 +71,7 @@ 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 +Additionally the callback should store a pointer 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: @@ -85,19 +85,23 @@ This can be set via a call to L. 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 digest). The application can use any TLSv1.3 ciphersuite. If B is +not 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. +This can be set via a call to L and should +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. @@ -106,7 +110,7 @@ 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 +this the callback should return successfully and ensure that B<*sess> is NULL. The contents of B<*id> and B<*idlen> will be ignored. =head1 NOTES @@ -118,7 +122,7 @@ has occurred so that L will return true. =head1 RETURN VALUES -Return values from the SSL_psk_client_cb_func callback are interpreted as +Return values from the B callback are interpreted as follows: On success (callback found a PSK identity and a pre-shared key to use)