import tlsext documentation from OpenSSL

3 files changed, 464 insertions, 1 deletions

diff --git a/lib/libssl/man/Makefile b/lib/libssl/man/Makefile
index 57332ab32fd..c2176f10229 100644
--- a/lib/libssl/man/Makefile
+++ b/lib/libssl/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.43 2016/12/01 19:40:05 schwarze Exp $
+# $OpenBSD: Makefile,v 1.44 2016/12/01 21:12:49 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -39,6 +39,8 @@ MAN =	BIO_f_ssl.3 \
 	SSL_CTX_set_session_id_context.3 \
 	SSL_CTX_set_ssl_version.3 \
 	SSL_CTX_set_timeout.3 \
+	SSL_CTX_set_tlsext_status_cb.3 \
+	SSL_CTX_set_tlsext_ticket_key_cb.3 \
 	SSL_CTX_set_tmp_dh_callback.3 \
 	SSL_CTX_set_tmp_rsa_callback.3 \
 	SSL_CTX_set_verify.3 \
diff --git a/lib/libssl/man/SSL_CTX_set_tlsext_status_cb.3 b/lib/libssl/man/SSL_CTX_set_tlsext_status_cb.3
new file mode 100644
index 00000000000..7fdd816cc3c
--- /dev/null
+++ b/lib/libssl/man/SSL_CTX_set_tlsext_status_cb.3
@@ -0,0 +1,166 @@
+.\"	$OpenBSD: SSL_CTX_set_tlsext_status_cb.3,v 1.1 2016/12/01 21:12:49 schwarze Exp $
+.\"	OpenSSL 43c34894 Nov 30 16:04:51 2015 +0000
+.\"
+.\" This file was written by Matt Caswell <matt@openssl.org>.
+.\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 1 2016 $
+.Dt SSL_CTX_SET_TLSEXT_STATUS_CB 3
+.Os
+.Sh NAME
+.Nm SSL_CTX_set_tlsext_status_cb ,
+.Nm SSL_CTX_set_tlsext_status_arg ,
+.Nm SSL_set_tlsext_status_type ,
+.Nm SSL_get_tlsext_status_ocsp_resp ,
+.Nm SSL_set_tlsext_status_ocsp_resp
+.Nd OCSP Certificate Status Request functions
+.Sh SYNOPSIS
+.In openssl/tls1.h
+.Ft long
+.Fo SSL_CTX_set_tlsext_status_cb
+.Fa "SSL_CTX *ctx"
+.Fa "int (*callback)(SSL *, void *)"
+.Fc
+.Ft long
+.Fo SSL_CTX_set_tlsext_status_arg
+.Fa "SSL_CTX *ctx"
+.Fa "void *arg"
+.Fc
+.Ft long
+.Fo SSL_set_tlsext_status_type
+.Fa "SSL *s"
+.Fa "int type"
+.Fc
+.Ft long
+.Fo SSL_get_tlsext_status_ocsp_resp
+.Fa ssl
+.Fa "unsigned char **resp"
+.Fc
+.Ft long
+.Fo SSL_set_tlsext_status_ocsp_resp
+.Fa ssl
+.Fa "unsigned char *resp"
+.Fa "int len"
+.Fc
+.Sh DESCRIPTION
+A client application may request that a server send back an OCSP status
+response (also known as OCSP stapling).
+To do so the client should call the
+.Fn SSL_set_tlsext_status_type
+function on an individual
+.Vt SSL
+object prior to the start of the handshake.
+Currently the only supported type is
+.Dv TLSEXT_STATUSTYPE_ocsp .
+This value should be passed in the
+.Fa type
+argument.
+.Pp
+The client should additionally provide a callback function to decide
+what to do with the returned OCSP response by calling
+.Fn SSL_CTX_set_tlsext_status_cb .
+The callback function should determine whether the returned OCSP
+response is acceptable or not.
+The callback will be passed as an argument the value previously set via
+a call to
+.Fn SSL_CTX_set_tlsext_status_arg .
+Note that the callback will not be called in the event of a handshake
+where session resumption occurs (because there are no Certificates
+exchanged in such a handshake).
+.Pp
+The response returned by the server can be obtained via a call to
+.Fn SSL_get_tlsext_status_ocsp_resp .
+The value
+.Pf * Fa resp
+will be updated to point to the OCSP response data and the return value
+will be the length of that data.
+If the server has not provided any response data, then
+.Pf * Fa resp
+will be
+.Dv NULL
+and the return value from
+.Fn SSL_get_tlsext_status_ocsp_resp
+will be -1.
+.Pp
+A server application must also call the
+.Fn SSL_CTX_set_tlsext_status_cb
+function if it wants to be able to provide clients with OCSP Certificate
+Status responses.
+Typically the server callback would obtain the server certificate that
+is being sent back to the client via a call to
+.Xr SSL_get_certificate 3 ,
+obtain the OCSP response to be sent back, and then set that response
+data by calling
+.Fn SSL_set_tlsext_status_ocsp_resp .
+A pointer to the response data should be provided in the
+.Fa resp
+argument, and the length of that data should be in the
+.Fa len
+argument.
+.Sh RETURN VALUES
+The callback when used on the client side should return a negative
+value on error, 0 if the response is not acceptable (in which case
+the handshake will fail), or a positive value if it is acceptable.
+.Pp
+The callback when used on the server side should return with either
+.Dv SSL_TLSEXT_ERR_OK
+(meaning that the OCSP response that has been set should be returned),
+.Dv SSL_TLSEXT_ERR_NOACK
+(meaning that an OCSP response should not be returned), or
+.Dv SSL_TLSEXT_ERR_ALERT_FATAL
+(meaning that a fatal error has occurred).
+.Pp
+.Fn SSL_CTX_set_tlsext_status_cb ,
+.Fn SSL_CTX_set_tlsext_status_arg ,
+.Fn SSL_set_tlsext_status_type ,
+and
+.Fn SSL_set_tlsext_status_ocsp_resp
+return 0 on error or 1 on success.
+.Pp
+.Fn SSL_get_tlsext_status_ocsp_resp
+returns the length of the OCSP response data or -1 if there is no OCSP
+response data.
diff --git a/lib/libssl/man/SSL_CTX_set_tlsext_ticket_key_cb.3 b/lib/libssl/man/SSL_CTX_set_tlsext_ticket_key_cb.3
new file mode 100644
index 00000000000..5009f298580
--- /dev/null
+++ b/lib/libssl/man/SSL_CTX_set_tlsext_ticket_key_cb.3
@@ -0,0 +1,295 @@
+.\"	$OpenBSD: SSL_CTX_set_tlsext_ticket_key_cb.3,v 1.1 2016/12/01 21:12:49 schwarze Exp $
+.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
+.\"
+.\" This file was written by Rich Salz <rsalz@akamai.com>
+.\" Copyright (c) 2014, 2015, 2016 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 1 2016 $
+.Dt SSL_CTX_SET_TLSEXT_TICKET_KEY_CB 3
+.Os
+.Sh NAME
+.Nm SSL_CTX_set_tlsext_ticket_key_cb
+.Nd set a callback for session ticket processing
+.Sh SYNOPSIS
+.In openssl/tls1.h
+.Ft long
+.Fo SSL_CTX_set_tlsext_ticket_key_cb
+.Fa "SSL_CTX sslctx"
+.Fa "int (*cb)(SSL *s, unsigned char key_name[16],\
+ unsigned char iv[EVP_MAX_IV_LENGTH],\
+ EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_CTX_set_tlsext_ticket_key_cb
+sets a callback function
+.Fa cb
+for handling session tickets for the ssl context
+.Fa sslctx .
+Session tickets, defined in RFC5077, provide an enhanced session
+resumption capability where the server implementation is not required to
+maintain per session state.
+.Pp
+The callback function
+.Fa cb
+will be called for every client instigated TLS session when session
+ticket extension is presented in the TLS hello message.
+It is the responsibility of this function to create or retrieve the
+cryptographic parameters and to maintain their state.
+.Pp
+The OpenSSL library uses the callback function to help implement a
+common TLS ticket construction state according to RFC5077 Section 4 such
+that per session state is unnecessary and a small set of cryptographic
+variables needs to be maintained by the callback function
+implementation.
+.Pp
+In order to reuse a session, a TLS client must send the a session ticket
+extension to the server.
+The client can only send exactly one session ticket.
+The server, through the callback function, either agrees to reuse the
+session ticket information or it starts a full TLS handshake to create a
+new session ticket.
+.Pp
+Before the callback function is started,
+.Fa ctx
+and
+.Fa hctx
+have been initialised with
+.Xr EVP_CIPHER_CTX_init 3
+and
+.Xr HMAC_CTX_init 3 ,
+respectively.
+.Pp
+For new sessions tickets, when the client doesn't present a session
+ticket, or an attempted retrieval of the ticket failed, or a renew
+option was indicated, the callback function will be called with
+.Fa enc
+equal to 1.
+The OpenSSL library expects that the function will set an arbitrary
+.Fa key_name ,
+initialize
+.Fa iv ,
+and set the cipher context
+.Fa ctx
+and the hash context
+.Fa hctx .
+.Pp
+The
+.Fa key_name
+is 16 characters long and is used as a key identifier.
+.Pp
+The
+.Fa iv
+length is the length of the IV of the corresponding cipher.
+The maximum IV length is
+.Dv EVP_MAX_IV_LENGTH
+bytes defined in
+.In opsenssl/evp.h .
+.Pp
+The initialization vector
+.Fa iv
+should be a random value.
+The cipher context
+.Fa ctx
+should use the initialisation vector
+.Fa iv .
+The cipher context can be set using
+.Xr EVP_EncryptInit_ex 3 .
+The hmac context can be set using
+.Xr HMAC_Init_ex 3 .
+.Pp
+When the client presents a session ticket, the callback function
+with be called with
+.Fa enc
+set to 0 indicating that the
+.Fa cb
+function should retrieve a set of parameters.
+In this case
+.Fa key_name
+and
+.Fa iv
+have already been parsed out of the session ticket.
+The OpenSSL library expects that the
+.Em key_name
+will be used to retrieve a cryptographic parameters and that the
+cryptographic context
+.Fa ctx
+will be set with the retrieved parameters and the initialization vector
+.Fa iv
+using a function like
+.Xr EVP_DecryptInit_ex 3 .
+The
+.Fa hctx
+needs to be set using
+.Xr HMAC_Init_ex 3 .
+.Pp
+If the
+.Fa key_name
+is still valid but a renewal of the ticket is required, the callback
+function should return 2.
+The library will call the callback again with an argument of
+.Fa enc
+equal to 1 to set the new ticket.
+.Pp
+The return value of the
+.Fa cb
+function is used by OpenSSL to determine what further processing will
+occur.
+The following return values have meaning:
+.Bl -tag -width Ds
+.It 2
+This indicates that the
+.Fa ctx
+and
+.Fa hctx
+have been set and the session can continue on those parameters.
+Additionally it indicates that the session ticket is in a renewal period
+and should be replaced.
+The OpenSSL library will call
+.Fa cb
+again with an
+.Fa enc
+argument of 1 to set the new ticket (see RFC5077 3.3 paragraph 2).
+.It 1
+This indicates that the
+.Fa ctx
+and
+.Fa hctx
+have been set and the session can continue on those parameters.
+.It 0
+This indicates that it was not possible to set/retrieve a session ticket
+and the SSL/TLS session will continue by negotiating a set of
+cryptographic parameters or using the alternate SSL/TLS resumption
+mechanism, session ids.
+.Pp
+If called with
+.Fa enc
+equal to 0, the library will call the
+.Fa cb
+again to get a new set of parameters.
+.It less than 0
+This indicates an error.
+.El
+.Pp
+Session resumption shortcuts the TLS so that the client certificate
+negotiation don't occur.
+It makes up for this by storing client certificate and all other
+negotiated state information encrypted within the ticket.
+In a resumed session the applications will have all this state
+information available exactly as if a full negotiation had occurred.
+.Pp
+If an attacker can obtain the key used to encrypt a session ticket, they
+can obtain the master secret for any ticket using that key and decrypt
+any traffic using that session: even if the ciphersuite supports forward
+secrecy.
+As a result applications may wish to use multiple keys and avoid using
+long term keys stored in files.
+.Pp
+Applications can use longer keys to maintain a consistent level of
+security.
+For example if a ciphersuite uses 256 bit ciphers but only a 128 bit
+ticket key the overall security is only 128 bits because breaking the
+ticket key will enable an attacker to obtain the session keys.
+.Sh RETURN VALUES
+This function returns 0 to indicate that the callback function was set.
+.Sh EXAMPLES
+Reference Implementation:
+.Bd -literal
+SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
+\&....
+static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
+    unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
+{
+	if (enc) { /* create new session */
+		if (RAND_bytes(iv, EVP_MAX_IV_LENGTH))
+			return -1; /* insufficient random */
+
+		key = currentkey(); /* something you need to implement */
+		if (!key) {
+			/* current key doesn't exist or isn't valid */
+			key = createkey();
+			    /* something that you need to implement.
+			     * createkey needs to initialise a name,
+			     * an aes_key, a hmac_key, and optionally
+			     * an expire time. */
+			if (!key) /* key couldn't be created */
+				return 0;
+		}
+		memcpy(key_name, key->name, 16);
+
+		EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL,
+		    key->aes_key, iv);
+		HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+
+		return 1;
+
+	} else { /* retrieve session */
+		key = findkey(name);
+
+		if  (!key || key->expire < now())
+			return 0;
+
+		HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+		EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL,
+		    key->aes_key, iv );
+
+		if (key->expire < (now() - RENEW_TIME))
+		    /* this session will get a new ticket
+		     * even though the current is still valid */
+		    return 2;
+
+		return 1;
+	}
+}
+.Ed
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_CTX_add_session 3 ,
+.Xr SSL_CTX_sess_number 3 ,
+.Xr SSL_CTX_sess_set_get_cb 3 ,
+.Xr SSL_CTX_set_session_id_context 3 ,
+.Xr SSL_session_reused 3 ,
+.Xr SSL_set_session 3