move manual pages from doc/ to man/ for consistency with other

libraries, in particular considering that there are unrelated
files in doc/; requested by jsing@ and beck@

1 files changed, 110 insertions, 0 deletions

diff --git a/src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3 b/src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3
new file mode 100644
index 0000000000..7d5d6b1dfd
--- /dev/null
+++ b/src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3
@@ -0,0 +1,110 @@
+.\"
+.\"     $OpenBSD: SSL_CTX_use_psk_identity_hint.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
+.\"
+.Dd $Mdocdate: November 5 2016 $
+.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