New manual pages SSL_get_certificate(3), SSL_get_state(3), and

SSL_num_renegotiations(3) written from scratch.  These functions
are listed in ssl(3) and <openssl/ssl.h>, so they are clearly public.

5 files changed, 286 insertions, 4 deletions

diff --git a/lib/libssl/man/Makefile b/lib/libssl/man/Makefile
index f58f568de75..d1d7bf3cc6b 100644
--- a/lib/libssl/man/Makefile
+++ b/lib/libssl/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.50 2016/12/07 20:11:55 schwarze Exp $
+# $OpenBSD: Makefile,v 1.51 2016/12/10 13:54:32 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -60,6 +60,7 @@ MAN =	BIO_f_ssl.3 \
 	SSL_dup_CA_list.3 \
 	SSL_free.3 \
 	SSL_get_SSL_CTX.3 \
+	SSL_get_certificate.3 \
 	SSL_get_ciphers.3 \
 	SSL_get_client_CA_list.3 \
 	SSL_get_current_cipher.3 \
@@ -72,11 +73,13 @@ MAN =	BIO_f_ssl.3 \
 	SSL_get_peer_certificate.3 \
 	SSL_get_rbio.3 \
 	SSL_get_session.3 \
+	SSL_get_state.3 \
 	SSL_get_verify_result.3 \
 	SSL_get_version.3 \
 	SSL_library_init.3 \
 	SSL_load_client_CA_file.3 \
 	SSL_new.3 \
+	SSL_num_renegotiations.3 \
 	SSL_pending.3 \
 	SSL_read.3 \
 	SSL_renegotiate.3 \
diff --git a/lib/libssl/man/SSL_get_certificate.3 b/lib/libssl/man/SSL_get_certificate.3
new file mode 100644
index 00000000000..35650c75b17
--- /dev/null
+++ b/lib/libssl/man/SSL_get_certificate.3
@@ -0,0 +1,61 @@
+.\"	$OpenBSD: SSL_get_certificate.3,v 1.1 2016/12/10 13:54:32 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 10 2016 $
+.Dt SSL_GET_CERTIFICATE 3
+.Os
+.Sh NAME
+.Nm SSL_get_certificate ,
+.Nm SSL_get_privatekey
+.Nd get SSL certificate and private key
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft X509 *
+.Fo SSL_get_certificate
+.Fa "const SSL *ssl"
+.Fc
+.Ft EVP_PKEY *
+.Fo SSL_get_privatekey
+.Fa "SSL *ssl"
+.Fc
+.Sh DESCRIPTION
+These functions retrieve certificate and key data from an
+.Vt SSL
+object.
+They return internal pointers that must not be freed by the application
+program.
+.Sh RETURN VALUES
+.Fn SSL_get_certificate
+returns the active X.509 certificate currently used by
+.Fa ssl
+or
+.Dv NULL
+if none is active.
+.Pp
+.Fn SSL_get_privatekey
+returns the active private key currently used by
+.Fa ssl
+or
+.Dv NULL
+if none is active.
+.Sh SEE ALSO
+.Xr SSL_check_private_key 3 ,
+.Xr SSL_use_certificate 3
+.Sh HISTORY
+.Fn SSL_get_certificate
+and
+.Fn SSL_get_privatekey
+are available in all versions of OpenSSL.
diff --git a/lib/libssl/man/SSL_get_state.3 b/lib/libssl/man/SSL_get_state.3
new file mode 100644
index 00000000000..d835b52291e
--- /dev/null
+++ b/lib/libssl/man/SSL_get_state.3
@@ -0,0 +1,146 @@
+.\"	$OpenBSD: SSL_get_state.3,v 1.1 2016/12/10 13:54:32 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 10 2016 $
+.Dt SSL_GET_STATE 3
+.Os
+.Sh NAME
+.Nm SSL_get_state ,
+.Nm SSL_state ,
+.Nm SSL_in_accept_init ,
+.Nm SSL_in_before ,
+.Nm SSL_in_connect_init ,
+.Nm SSL_in_init ,
+.Nm SSL_is_init_finished
+.Nd inspect the state of the SSL state machine
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft int
+.Fo SSL_get_state
+.Fa "const SSL *ssl"
+.Fc
+.Ft int
+.Fo SSL_state
+.Fa "const SSL *ssl"
+.Fc
+.Ft int
+.Fo SSL_in_accept_init
+.Fa "const SSL *ssl"
+.Fc
+.Ft int
+.Fo SSL_in_before
+.Fa "const SSL *ssl"
+.Fc
+.Ft int
+.Fo SSL_in_connect_init
+.Fa "const SSL *ssl"
+.Fc
+.Ft int
+.Fo SSL_in_init
+.Fa "const SSL *ssl"
+.Fc
+.Ft int
+.Fo SSL_is_init_finished
+.Fa "const SSL *ssl"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_get_state
+returns an encoded representation of the current state of the SSL
+state machine.
+.Fn SSL_state
+is a deprecated alias for
+.Fn SSL_get_state .
+.Pp
+The following bits may be set:
+.Bl -tag -width Ds
+.It Dv SSL_ST_ACCEPT
+This bit is set by
+.Xr SSL_accept 3
+and by
+.Xr SSL_set_accept_state 3 .
+It indicates that
+.Fa ssl
+is set up for server mode and no client initiated the TLS handshake yet.
+The function
+.Fn SSL_in_accept_init
+returns non-zero if this bit is set or 0 otherwise.
+.It Dv SSL_ST_BEFORE
+This bit is set by the
+.Xr SSL_accept 3 ,
+.Xr SSL_connect 3 ,
+.Xr SSL_set_accept_state 3 ,
+and
+.Xr SSL_set_connect_state 3
+functions.
+It indicates that the TLS handshake was not initiated yet.
+The function
+.Fn SSL_in_before
+returns non-zero if this bit is set or 0 otherwise.
+.It Dv SSL_ST_CONNECT
+This bit is set by
+.Xr SSL_connect 3
+and by
+.Xr SSL_set_connect_state 3 .
+It indicates that
+.Fa ssl
+is set up for client mode and no TLS handshake was initiated yet.
+The function
+.Fn SSL_in_connect_init
+returns non-zero if this bit is set or 0 otherwise.
+.El
+.Pp
+The following masks can be used:
+.Bl -tag -width Ds
+.It Dv SSL_ST_INIT
+Set if
+.Dv SSL_ST_ACCEPT
+or
+.Dv SSL_ST_CONNECT
+is set.
+The function
+.Fn SSL_in_init
+returns a non-zero value if one of these is set or 0 otherwise.
+.It Dv SSL_ST_MASK
+This mask includes all bits except
+.Dv SSL_ST_ACCEPT ,
+.Dv SSL_ST_BEFORE ,
+and
+.Dv SSL_ST_CONNECT .
+.It Dv SSL_ST_OK
+The state is set to this value when a connection is established.
+The function
+.Fn SSL_is_init_finished
+returns a non-zero value if the state equals this constant, or 0 otherwise.
+.It Dv SSL_ST_RENEGOTIATE
+The program is about to renegotiate, for example when entering
+.Xr SSL_read 3
+or
+.Xr SSL_write 3
+right after
+.Xr SSL_renegotiate 3
+was called.
+.El
+.Pp
+The meaning of other bits is protocol-dependent.
+Application programs usually do not need to inspect any of those
+other bits.
+.Pp
+All these functions may be implemented as macros.
+.Sh SEE ALSO
+.Xr SSL_renegotiate 3 ,
+.Xr SSL_set_connect_state 3
+.Sh HISTORY
+These functions are available in all versions of OpenSSL.
diff --git a/lib/libssl/man/SSL_num_renegotiations.3 b/lib/libssl/man/SSL_num_renegotiations.3
new file mode 100644
index 00000000000..d1986a674c6
--- /dev/null
+++ b/lib/libssl/man/SSL_num_renegotiations.3
@@ -0,0 +1,71 @@
+.\"	$OpenBSD: SSL_num_renegotiations.3,v 1.1 2016/12/10 13:54:32 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 10 2016 $
+.Dt SSL_NUM_RENEGOTIATIONS 3
+.Os
+.Sh NAME
+.Nm SSL_num_renegotiations ,
+.Nm SSL_clear_num_renegotiations ,
+.Nm SSL_total_renegotiations
+.Nd renegotiation counters
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft long
+.Fo SSL_num_renegotiations
+.Fa "SSL *ssl"
+.Fc
+.Ft long
+.Fo SSL_clear_num_renegotiations
+.Fa "SSL *ssl"
+.Fc
+.Ft long
+.Fo SSL_total_renegotiations
+.Fa "SSL *ssl"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_num_renegotiations
+reports the number of renegotiations initiated in
+.Fa ssl
+since
+.Xr SSL_new 3 ,
+.Xr SSL_clear 3 ,
+or
+.Xr SSL_clear_num_renegotiations 3
+was last called on that object.
+.Pp
+.Fn SSL_clear_num_renegotiations
+does the same and additionally resets the renegotiation counter to 0.
+.Pp
+.Fn SSL_total_renegotiations
+reports the number of renegotiations initiated in
+.Fa ssl
+since
+.Xr SSL_new 3
+or
+.Xr SSL_clear 3
+was last called on that object.
+.Pp
+These functions are implemented as macros.
+.Sh RETURN VALUES
+All these functions return a number of renegotiations.
+.Sh SEE ALSO
+.Xr BIO_set_ssl_renegotiate_bytes 3 ,
+.Xr SSL_read 3 ,
+.Xr SSL_renegotiate 3 ,
+.Xr SSL_write 3
+.Sh HISTORY
+These functions are available in all versions of OpenSSL.
diff --git a/lib/libssl/man/SSL_renegotiate.3 b/lib/libssl/man/SSL_renegotiate.3
index c07a1e2c2a3..f5b59bae958 100644
--- a/lib/libssl/man/SSL_renegotiate.3
+++ b/lib/libssl/man/SSL_renegotiate.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: SSL_renegotiate.3,v 1.1 2016/12/07 20:11:55 schwarze Exp $
+.\"	$OpenBSD: SSL_renegotiate.3,v 1.2 2016/12/10 13:54:32 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: December 7 2016 $
+.Dd $Mdocdate: December 10 2016 $
 .Dt SSL_RENEGOTIATE 3
 .Os
 .Sh NAME
@@ -38,7 +38,7 @@ and
 .Xr SSL_write 3
 whenever the renegotiation byte count set by
 .Xr BIO_set_ssl_renegotiate_bytes 3
-or the timeout set by 
+or the timeout set by
 .Xr BIO_set_ssl_renegotiate_timeout 3
 are exceeded.
 .Sh RETURN VALUES
@@ -49,6 +49,7 @@ is set, in which case it may return 0.
 The API provides no function to set that flag;
 it can only be set by manipulating internal data structures.
 .Sh SEE ALSO
+.Xr SSL_num_renegotiations 3 ,
 .Xr SSL_read 3 ,
 .Xr SSL_write 3
 .Sh HISTORY