1 files changed, 154 insertions, 0 deletions
diff --git a/src/lib/libtls/man/tls_conn_version.3 b/src/lib/libtls/man/tls_conn_version.3
new file mode 100644
index 0000000000..89fb4019c8
--- /dev/null
+++ b/src/lib/libtls/man/tls_conn_version.3
@@ -0,0 +1,154 @@
+.\" $OpenBSD: tls_conn_version.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $
+.\"
+.\" Copyright (c) 2014 Ted Unangst <tedu@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: January 25 2017 $
+.Dt TLS_INIT 3
+.Os
+.Sh NAME
+.Nm tls_conn_version ,
+.Nm tls_conn_cipher ,
+.Nm tls_conn_alpn_selected ,
+.Nm tls_conn_servername ,
+.Nm tls_peer_cert_provided ,
+.Nm tls_peer_cert_contains_name ,
+.Nm tls_peer_cert_issuer ,
+.Nm tls_peer_cert_subject ,
+.Nm tls_peer_cert_hash ,
+.Nm tls_peer_cert_notbefore ,
+.Nm tls_peer_cert_notafter
+.Nd inspect an established TLS connection
+.Sh SYNOPSIS
+.In tls.h
+.Ft const char *
+.Fn tls_conn_version "struct tls *ctx"
+.Ft const char *
+.Fn tls_conn_cipher "struct tls *ctx"
+.Ft const char *
+.Fn tls_conn_alpn_selected "struct tls *ctx"
+.Ft const char *
+.Fn tls_conn_servername "struct tls *ctx"
+.Ft int
+.Fn tls_peer_cert_provided "struct tls *ctx"
+.Ft int
+.Fo tls_peer_cert_contains_name
+.Fa "struct tls *ctx"
+.Fa "const char *name"
+.Fc
+.Ft const char *
+.Fn tls_peer_cert_issuer "struct tls *ctx"
+.Ft const char *
+.Fn tls_peer_cert_subject "struct tls *ctx"
+.Ft const char *
+.Fn tls_peer_cert_hash "struct tls *ctx"
+.Ft time_t
+.Fn tls_peer_cert_notbefore "struct tls *ctx"
+.Ft time_t
+.Fn tls_peer_cert_notafter "struct tls *ctx"
+.Sh DESCRIPTION
+These functions return information about a TLS connection and will only
+succeed after the handshake is complete (the connection information applies
+to both clients and servers, unless noted otherwise):
+.Pp
+.Fn tls_conn_version
+returns a string corresponding to a TLS version negotiated with the peer
+connected to
+.Ar ctx .
+.Pp
+.Fn tls_conn_cipher
+returns a string corresponding to the cipher suite negotiated with the peer
+connected to
+.Ar ctx .
+.Pp
+.Fn tls_conn_alpn_selected
+returns a string that specifies the ALPN protocol selected for use with the peer
+connected to
+.Ar ctx .
+If no protocol was selected then NULL is returned.
+.Pp
+.Fn tls_conn_servername
+returns a string corresponding to the servername that the client connected to
+.Ar ctx
+requested by sending a TLS Server Name Indication extension (server only).
+.Pp
+.Fn tls_peer_cert_provided
+checks if the peer of
+.Ar ctx
+has provided a certificate.
+.Pp
+.Fn tls_peer_cert_contains_name
+checks if the peer of a TLS
+.Ar ctx
+has provided a certificate that contains a
+SAN or CN that matches
+.Ar name .
+.Pp
+.Fn tls_peer_cert_subject
+returns a string
+corresponding to the subject of the peer certificate from
+.Ar ctx .
+.Pp
+.Fn tls_peer_cert_issuer
+returns a string
+corresponding to the issuer of the peer certificate from
+.Ar ctx .
+.Pp
+.Fn tls_peer_cert_hash
+returns a string
+corresponding to a hash of the raw peer certificate from
+.Ar ctx
+prefixed by a hash name followed by a colon.
+The hash currently used is SHA256, though this
+could change in the future.
+The hash string for a certificate in file
+.Ar mycert.crt
+can be generated using the commands:
+.Bd -literal -offset indent
+h=$(openssl x509 -outform der -in mycert.crt | sha256)
+printf "SHA256:${h}\\n"
+.Ed
+.Pp
+.Fn tls_peer_cert_notbefore
+returns the time corresponding to the start of the validity period of
+the peer certificate from
+.Ar ctx .
+.Pp
+.Fn tls_peer_cert_notafter
+returns the time corresponding to the end of the validity period of
+the peer certificate from
+.Ar ctx .
+.Pp
+POINTER TO
+.Xr tls_ocsp_process_response 3
+.Sh RETURN VALUES
+The
+.Fn tls_peer_cert_provided
+and
+.Fn tls_peer_cert_contains_name
+functions return 1 if the check succeeds or 0 if it does not.
+.Pp
+.Fn tls_peer_cert_notbefore
+and
+.Fn tls_peer_cert_notafter
+return a time in epoch-seconds on success or -1 on error.
+.Pp
+The functions that return a pointer return
+.Dv NULL
+on error or an out of memory condition.
+.Sh SEE ALSO
+.Xr tls_configure 3 ,
+.Xr tls_handshake 3 ,
+.Xr tls_init 3 ,
+.Xr tls_ocsp_process_response 3

diff --git a/src/lib/libtls/man/tls_conn_version.3 b/src/lib/libtls/man/tls_conn_version.3 new file mode 100644 index 0000000000..89fb4019c8 --- /dev/null +++ b/src/lib/libtls/man/tls_conn_version.3
@@ -0,0 +1,154 @@
	1	.\" $OpenBSD: tls_conn_version.3,v 1.1 2017/01/25 23:53:18 schwarze Exp $
	2	.\"
	3	.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
	4	.\"
	5	.\" Permission to use, copy, modify, and distribute this software for any
	6	.\" purpose with or without fee is hereby granted, provided that the above
	7	.\" copyright notice and this permission notice appear in all copies.
	8	.\"
	9	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	10	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	11	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
	12	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	13	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	14	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
	15	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	16	.\"
	17	.Dd $Mdocdate: January 25 2017 $
	18	.Dt TLS_INIT 3
	19	.Os
	20	.Sh NAME
	21	.Nm tls_conn_version ,
	22	.Nm tls_conn_cipher ,
	23	.Nm tls_conn_alpn_selected ,
	24	.Nm tls_conn_servername ,
	25	.Nm tls_peer_cert_provided ,
	26	.Nm tls_peer_cert_contains_name ,
	27	.Nm tls_peer_cert_issuer ,
	28	.Nm tls_peer_cert_subject ,
	29	.Nm tls_peer_cert_hash ,
	30	.Nm tls_peer_cert_notbefore ,
	31	.Nm tls_peer_cert_notafter
	32	.Nd inspect an established TLS connection
	33	.Sh SYNOPSIS
	34	.In tls.h
	35	.Ft const char *
	36	.Fn tls_conn_version "struct tls *ctx"
	37	.Ft const char *
	38	.Fn tls_conn_cipher "struct tls *ctx"
	39	.Ft const char *
	40	.Fn tls_conn_alpn_selected "struct tls *ctx"
	41	.Ft const char *
	42	.Fn tls_conn_servername "struct tls *ctx"
	43	.Ft int
	44	.Fn tls_peer_cert_provided "struct tls *ctx"
	45	.Ft int
	46	.Fo tls_peer_cert_contains_name
	47	.Fa "struct tls *ctx"
	48	.Fa "const char *name"
	49	.Fc
	50	.Ft const char *
	51	.Fn tls_peer_cert_issuer "struct tls *ctx"
	52	.Ft const char *
	53	.Fn tls_peer_cert_subject "struct tls *ctx"
	54	.Ft const char *
	55	.Fn tls_peer_cert_hash "struct tls *ctx"
	56	.Ft time_t
	57	.Fn tls_peer_cert_notbefore "struct tls *ctx"
	58	.Ft time_t
	59	.Fn tls_peer_cert_notafter "struct tls *ctx"
	60	.Sh DESCRIPTION
	61	These functions return information about a TLS connection and will only
	62	succeed after the handshake is complete (the connection information applies
	63	to both clients and servers, unless noted otherwise):
	64	.Pp
	65	.Fn tls_conn_version
	66	returns a string corresponding to a TLS version negotiated with the peer
	67	connected to
	68	.Ar ctx .
	69	.Pp
	70	.Fn tls_conn_cipher
	71	returns a string corresponding to the cipher suite negotiated with the peer
	72	connected to
	73	.Ar ctx .
	74	.Pp
	75	.Fn tls_conn_alpn_selected
	76	returns a string that specifies the ALPN protocol selected for use with the peer
	77	connected to
	78	.Ar ctx .
	79	If no protocol was selected then NULL is returned.
	80	.Pp
	81	.Fn tls_conn_servername
	82	returns a string corresponding to the servername that the client connected to
	83	.Ar ctx
	84	requested by sending a TLS Server Name Indication extension (server only).
	85	.Pp
	86	.Fn tls_peer_cert_provided
	87	checks if the peer of
	88	.Ar ctx
	89	has provided a certificate.
	90	.Pp
	91	.Fn tls_peer_cert_contains_name
	92	checks if the peer of a TLS
	93	.Ar ctx
	94	has provided a certificate that contains a
	95	SAN or CN that matches
	96	.Ar name .
	97	.Pp
	98	.Fn tls_peer_cert_subject
	99	returns a string
	100	corresponding to the subject of the peer certificate from
	101	.Ar ctx .
	102	.Pp
	103	.Fn tls_peer_cert_issuer
	104	returns a string
	105	corresponding to the issuer of the peer certificate from
	106	.Ar ctx .
	107	.Pp
	108	.Fn tls_peer_cert_hash
	109	returns a string
	110	corresponding to a hash of the raw peer certificate from
	111	.Ar ctx
	112	prefixed by a hash name followed by a colon.
	113	The hash currently used is SHA256, though this
	114	could change in the future.
	115	The hash string for a certificate in file
	116	.Ar mycert.crt
	117	can be generated using the commands:
	118	.Bd -literal -offset indent
	119	h=$(openssl x509 -outform der -in mycert.crt \| sha256)
	120	printf "SHA256:${h}\\n"
	121	.Ed
	122	.Pp
	123	.Fn tls_peer_cert_notbefore
	124	returns the time corresponding to the start of the validity period of
	125	the peer certificate from
	126	.Ar ctx .
	127	.Pp
	128	.Fn tls_peer_cert_notafter
	129	returns the time corresponding to the end of the validity period of
	130	the peer certificate from
	131	.Ar ctx .
	132	.Pp
	133	POINTER TO
	134	.Xr tls_ocsp_process_response 3
	135	.Sh RETURN VALUES
	136	The
	137	.Fn tls_peer_cert_provided
	138	and
	139	.Fn tls_peer_cert_contains_name
	140	functions return 1 if the check succeeds or 0 if it does not.
	141	.Pp
	142	.Fn tls_peer_cert_notbefore
	143	and
	144	.Fn tls_peer_cert_notafter
	145	return a time in epoch-seconds on success or -1 on error.
	146	.Pp
	147	The functions that return a pointer return
	148	.Dv NULL
	149	on error or an out of memory condition.
	150	.Sh SEE ALSO
	151	.Xr tls_configure 3 ,
	152	.Xr tls_handshake 3 ,
	153	.Xr tls_init 3 ,
	154	.Xr tls_ocsp_process_response 3