1 files changed, 154 insertions, 0 deletions
diff --git a/src/lib/libtls/man/tls_ocsp_process_response.3 b/src/lib/libtls/man/tls_ocsp_process_response.3
new file mode 100644
index 0000000000..78dc0ee42c
--- /dev/null
+++ b/src/lib/libtls/man/tls_ocsp_process_response.3
@@ -0,0 +1,154 @@
+.\" $OpenBSD: tls_ocsp_process_response.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_OCSP_PROCESS_RESPONSE 3
+.Os
+.Sh NAME
+.Nm tls_ocsp_process_response ,
+.Nm tls_peer_ocsp_cert_status ,
+.Nm tls_peer_ocsp_crl_reason ,
+.Nm tls_peer_ocsp_next_update ,
+.Nm tls_peer_ocsp_response_status ,
+.Nm tls_peer_ocsp_result_msg ,
+.Nm tls_peer_ocsp_revocation_time ,
+.Nm tls_peer_ocsp_this_update ,
+.Nm tls_peer_ocsp_url
+.Nd inspect an OCSP response
+.Sh SYNOPSIS
+.In tls.h
+.Ft int
+.Fo tls_ocsp_process_response
+.Fa "struct tls *ctx"
+.Fa "const unsigned char *response"
+.Fa "size_t size"
+.Fc
+.Ft int
+.Fn tls_peer_ocsp_cert_status "struct tls *ctx"
+.Ft int
+.Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
+.Ft time_t
+.Fn tls_peer_ocsp_next_update "struct tls *ctx"
+.Ft int
+.Fn tls_peer_ocsp_response_status "struct tls *ctx"
+.Ft const char *
+.Fn tls_peer_ocsp_result_msg "struct tls *ctx"
+.Ft time_t
+.Fn tls_peer_ocsp_revocation_time "struct tls *ctx"
+.Ft time_t
+.Fn tls_peer_ocsp_this_update "struct tls *ctx"
+.Ft const char *
+.Fn tls_peer_ocsp_url "struct tls *ctx"
+.Sh DESCRIPTION
+.Fn tls_ocsp_process_response
+processes a raw OCSP response in
+.Ar response
+of size
+.Ar size
+to check the revocation status of the peer certificate from
+.Ar ctx .
+A successful return code of 0 indicates that the certificate
+has not been revoked.
+.Pp
+.Fn tls_peer_ocsp_url
+returns the URL for OCSP validation of the peer certificate from
+.Ar ctx .
+.Pp
+The following functions return information about the peer certificate from
+.Ar ctx
+that was obtained by validating a stapled OCSP response during the handshake,
+or via a previous call to
+.Fn tls_ocsp_process_response .
+.Pp
+.Fn tls_peer_ocsp_cert_status
+returns the OCSP certificate status code as per RFC 6960 section 2.2.
+.Pp
+.Fn tls_peer_ocsp_crl_reason
+returns the OCSP certificate revocation reason status code as per RFC 5280
+section 5.3.1.
+.Pp
+.Fn tls_peer_ocsp_next_update
+returns the OCSP next update time.
+.Pp
+.Fn tls_peer_ocsp_response_status
+returns the OCSP response status as per RFC 6960 section 2.3.
+.Pp
+.\" XXX Fn tls_peer_ocsp_result_msg does what?
+.Fn tls_peer_ocsp_revocation_time
+returns the OCSP revocation time.
+.Pp
+.Fn tls_peer_ocsp_this_update
+returns the OCSP this update time.
+.Sh RETURN VALUES
+.Fn tls_ocsp_process_response
+returns 0 on success or -1 on error.
+.Pp
+The
+.Fn tls_peer_ocsp_response_status
+function returns one of
+.Dv TLS_OCSP_RESPONSE_SUCCESSFUL ,
+.Dv TLS_OCSP_RESPONSE_MALFORMED ,
+.Dv TLS_OCSP_RESPONSE_INTERNALERROR ,
+.Dv TLS_OCSP_RESPONSE_TRYLATER ,
+.Dv TLS_OCSP_RESPONSE_SIGREQUIRED ,
+or
+.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED
+on success or -1 on error.
+.Pp
+The
+.Fn tls_peer_ocsp_cert_status
+function returns one of
+.Dv TLS_OCSP_CERT_GOOD ,
+.Dv TLS_OCSP_CERT_REVOKED ,
+or
+.Dv TLS_OCSP_CERT_UNKNOWN
+on success, and -1 on error.
+.Pp
+The
+.Fn tls_peer_ocsp_crl_reason
+function returns one of
+.Dv TLS_CRL_REASON_UNSPECIFIED ,
+.Dv TLS_CRL_REASON_KEY_COMPROMISE ,
+.Dv TLS_CRL_REASON_CA_COMPROMISE ,
+.Dv TLS_CRL_REASON_AFFILIATION_CHANGED ,
+.Dv TLS_CRL_REASON_SUPERSEDED ,
+.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION ,
+.Dv TLS_CRL_REASON_CERTIFICATE_HOLD ,
+.Dv TLS_CRL_REASON_REMOVE_FROM_CRL ,
+.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN ,
+or
+.Dv  TLS_CRL_REASON_AA_COMPROMISE
+on success or -1 on error.
+.Pp
+.Fn tls_peer_ocsp_next_update ,
+.Fn tls_peer_ocsp_revocation_time ,
+and
+.Fn tls_peer_ocsp_this_update
+return a time in epoch-seconds on success or -1 on error.
+.Pp
+.Fn tls_peer_ocsp_result_msg
+and
+.Fn tls_peer_ocsp_url
+return
+.Dv NULL
+on error or an out of memory condition.
+.Sh SEE ALSO
+.Xr tls_client 3 ,
+.Xr tls_config_ocsp_require_stapling 3 ,
+.Xr tls_conn_version 3 ,
+.Xr tls_connect 3 ,
+.Xr tls_handshake 3 ,
+.Xr tls_init 3

diff --git a/src/lib/libtls/man/tls_ocsp_process_response.3 b/src/lib/libtls/man/tls_ocsp_process_response.3 new file mode 100644 index 0000000000..78dc0ee42c --- /dev/null +++ b/src/lib/libtls/man/tls_ocsp_process_response.3
@@ -0,0 +1,154 @@
	1	.\" $OpenBSD: tls_ocsp_process_response.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_OCSP_PROCESS_RESPONSE 3
	19	.Os
	20	.Sh NAME
	21	.Nm tls_ocsp_process_response ,
	22	.Nm tls_peer_ocsp_cert_status ,
	23	.Nm tls_peer_ocsp_crl_reason ,
	24	.Nm tls_peer_ocsp_next_update ,
	25	.Nm tls_peer_ocsp_response_status ,
	26	.Nm tls_peer_ocsp_result_msg ,
	27	.Nm tls_peer_ocsp_revocation_time ,
	28	.Nm tls_peer_ocsp_this_update ,
	29	.Nm tls_peer_ocsp_url
	30	.Nd inspect an OCSP response
	31	.Sh SYNOPSIS
	32	.In tls.h
	33	.Ft int
	34	.Fo tls_ocsp_process_response
	35	.Fa "struct tls *ctx"
	36	.Fa "const unsigned char *response"
	37	.Fa "size_t size"
	38	.Fc
	39	.Ft int
	40	.Fn tls_peer_ocsp_cert_status "struct tls *ctx"
	41	.Ft int
	42	.Fn tls_peer_ocsp_crl_reason "struct tls *ctx"
	43	.Ft time_t
	44	.Fn tls_peer_ocsp_next_update "struct tls *ctx"
	45	.Ft int
	46	.Fn tls_peer_ocsp_response_status "struct tls *ctx"
	47	.Ft const char *
	48	.Fn tls_peer_ocsp_result_msg "struct tls *ctx"
	49	.Ft time_t
	50	.Fn tls_peer_ocsp_revocation_time "struct tls *ctx"
	51	.Ft time_t
	52	.Fn tls_peer_ocsp_this_update "struct tls *ctx"
	53	.Ft const char *
	54	.Fn tls_peer_ocsp_url "struct tls *ctx"
	55	.Sh DESCRIPTION
	56	.Fn tls_ocsp_process_response
	57	processes a raw OCSP response in
	58	.Ar response
	59	of size
	60	.Ar size
	61	to check the revocation status of the peer certificate from
	62	.Ar ctx .
	63	A successful return code of 0 indicates that the certificate
	64	has not been revoked.
	65	.Pp
	66	.Fn tls_peer_ocsp_url
	67	returns the URL for OCSP validation of the peer certificate from
	68	.Ar ctx .
	69	.Pp
	70	The following functions return information about the peer certificate from
	71	.Ar ctx
	72	that was obtained by validating a stapled OCSP response during the handshake,
	73	or via a previous call to
	74	.Fn tls_ocsp_process_response .
	75	.Pp
	76	.Fn tls_peer_ocsp_cert_status
	77	returns the OCSP certificate status code as per RFC 6960 section 2.2.
	78	.Pp
	79	.Fn tls_peer_ocsp_crl_reason
	80	returns the OCSP certificate revocation reason status code as per RFC 5280
	81	section 5.3.1.
	82	.Pp
	83	.Fn tls_peer_ocsp_next_update
	84	returns the OCSP next update time.
	85	.Pp
	86	.Fn tls_peer_ocsp_response_status
	87	returns the OCSP response status as per RFC 6960 section 2.3.
	88	.Pp
	89	.\" XXX Fn tls_peer_ocsp_result_msg does what?
	90	.Fn tls_peer_ocsp_revocation_time
	91	returns the OCSP revocation time.
	92	.Pp
	93	.Fn tls_peer_ocsp_this_update
	94	returns the OCSP this update time.
	95	.Sh RETURN VALUES
	96	.Fn tls_ocsp_process_response
	97	returns 0 on success or -1 on error.
	98	.Pp
	99	The
	100	.Fn tls_peer_ocsp_response_status
	101	function returns one of
	102	.Dv TLS_OCSP_RESPONSE_SUCCESSFUL ,
	103	.Dv TLS_OCSP_RESPONSE_MALFORMED ,
	104	.Dv TLS_OCSP_RESPONSE_INTERNALERROR ,
	105	.Dv TLS_OCSP_RESPONSE_TRYLATER ,
	106	.Dv TLS_OCSP_RESPONSE_SIGREQUIRED ,
	107	or
	108	.Dv TLS_OCSP_RESPONSE_UNAUTHORIZED
	109	on success or -1 on error.
	110	.Pp
	111	The
	112	.Fn tls_peer_ocsp_cert_status
	113	function returns one of
	114	.Dv TLS_OCSP_CERT_GOOD ,
	115	.Dv TLS_OCSP_CERT_REVOKED ,
	116	or
	117	.Dv TLS_OCSP_CERT_UNKNOWN
	118	on success, and -1 on error.
	119	.Pp
	120	The
	121	.Fn tls_peer_ocsp_crl_reason
	122	function returns one of
	123	.Dv TLS_CRL_REASON_UNSPECIFIED ,
	124	.Dv TLS_CRL_REASON_KEY_COMPROMISE ,
	125	.Dv TLS_CRL_REASON_CA_COMPROMISE ,
	126	.Dv TLS_CRL_REASON_AFFILIATION_CHANGED ,
	127	.Dv TLS_CRL_REASON_SUPERSEDED ,
	128	.Dv TLS_CRL_REASON_CESSATION_OF_OPERATION ,
	129	.Dv TLS_CRL_REASON_CERTIFICATE_HOLD ,
	130	.Dv TLS_CRL_REASON_REMOVE_FROM_CRL ,
	131	.Dv TLS_CRL_REASON_PRIVILEGE_WITHDRAWN ,
	132	or
	133	.Dv TLS_CRL_REASON_AA_COMPROMISE
	134	on success or -1 on error.
	135	.Pp
	136	.Fn tls_peer_ocsp_next_update ,
	137	.Fn tls_peer_ocsp_revocation_time ,
	138	and
	139	.Fn tls_peer_ocsp_this_update
	140	return a time in epoch-seconds on success or -1 on error.
	141	.Pp
	142	.Fn tls_peer_ocsp_result_msg
	143	and
	144	.Fn tls_peer_ocsp_url
	145	return
	146	.Dv NULL
	147	on error or an out of memory condition.
	148	.Sh SEE ALSO
	149	.Xr tls_client 3 ,
	150	.Xr tls_config_ocsp_require_stapling 3 ,
	151	.Xr tls_conn_version 3 ,
	152	.Xr tls_connect 3 ,
	153	.Xr tls_handshake 3 ,
	154	.Xr tls_init 3