From 82b7f378b6907ab315a6e50322d2a0a8794a0aa9 Mon Sep 17 00:00:00 2001
From: bentley <>
Date: Sun, 12 Oct 2014 09:33:04 +0000
Subject: Convert libssl manpages from pod to mdoc(7).

libcrypto has not been started yet.

ok schwarze@ miod@
---
 src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 | 107 +++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3

(limited to 'src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3')

diff --git a/src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 b/src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3
new file mode 100644
index 0000000000..4d4e8a6173
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3
@@ -0,0 +1,107 @@
+.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
-- 
cgit v1.2.3-55-g6feb