.Dd $Mdocdate: October 12 2014 $
.Dt SSL_CTX_USE_PSK_IDENTITY_HINT 3
.Os
.Sh NAME
.Nm SSL_CTX_use_psk_identity_hint ,
.Nm SSL_use_psk_identity_hint ,
.Nm  SSL_CTX_set_psk_server_callback ,
.Nm SSL_set_psk_server_callback
.Nd set PSK identity hint to use
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft int
.Fn SSL_CTX_use_psk_identity_hint "SSL_CTX *ctx" "const char *hint"
.Ft int
.Fn SSL_use_psk_identity_hint "SSL *ssl" "const char *hint"
.Ft void
.Fo SSL_CTX_set_psk_server_callback
.Fa "SSL_CTX *ctx"
.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)"
.Fc
.Ft void
.Fo SSL_set_psk_server_callback
.Fa "SSL *ssl"
.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)"
.Fc
.Sh DESCRIPTION
.Fn SSL_CTX_use_psk_identity_hint
sets the given
.Dv NULL Ns
-terminated PSK identity hint
.Fa hint
to SSL context object
.Fa ctx .
.Fn SSL_use_psk_identity_hint
sets the given
.Dv NULL Ns
-terminated
PSK identity hint
.Fa hint
to SSL connection object
.Fa ssl .
If
.Fa hint
is
.Dv NULL
the current hint from
.Fa ctx
or
.Fa ssl
is deleted.
.Pp
In the case where PSK identity hint is
.Dv NULL ,
the server does not send the
.Em ServerKeyExchange
message to the client.
.Pp
A server application must provide a callback function which is called when the
server receives the
.Em 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
.Fn SSL_CTX_set_psk_server_callback
or
.Fn SSL_set_psk_server_callback .
The callback function is given the connection in parameter
.Fa ssl ,
.Dv NULL Ns
-terminated PSK identity sent by the client in parameter
.Fa identity ,
and a buffer
.Fa psk
of length
.Fa max_psk_len
bytes where the pre-shared key is to be stored.
.Sh RETURN VALUES
.Fn SSL_CTX_use_psk_identity_hint
and
.Fn SSL_use_psk_identity_hint
return 1 on success, 0 otherwise.
.Pp
Return values from the server callback are interpreted as follows:
.Bl -tag -width Ds
.It >0
PSK identity was found and the server callback has provided the PSK
successfully in parameter
.Fa psk .
Return value is the length of
.Fa psk
in bytes.
It is an error to return a value greater than
.Fa max_psk_len .
.Pp
If the PSK identity was not found but the callback instructs the protocol to
continue anyway, the callback must provide some random data to
.Fa psk
and return the length of the random data, so the connection will fail with
.Dq decryption_error
before it will be finished completely.
.It 0
PSK identity was not found.
An
.Dq unknown_psk_identity
alert message will be sent and the connection setup fails.
.El