Document OCSP_SINGLERESP_new(3), OCSP_SINGLERESP_free(3),

OCSP_CERTSTATUS_new(3), OCSP_CERTSTATUS_free(3), OCSP_REVOKEDINFO_new(3),
and OCSP_REVOKEDINFO_free(3), all in <openssl/ocsp.h> and in OpenSSL
doc/man3/X509_dup.pod.  Note that the OpenSSL documentation specifies
the wrong header file.

Add some information about what these objects actually represent,
along with the pertinent STANDARDS reference.

1 files changed, 90 insertions, 3 deletions

diff --git a/lib/libcrypto/man/OCSP_resp_find_status.3 b/lib/libcrypto/man/OCSP_resp_find_status.3
index 99d52a109bf..eca0a2c15ff 100644
--- a/lib/libcrypto/man/OCSP_resp_find_status.3
+++ b/lib/libcrypto/man/OCSP_resp_find_status.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: OCSP_resp_find_status.3,v 1.2 2016/12/06 14:54:55 schwarze Exp $
+.\"	$OpenBSD: OCSP_resp_find_status.3,v 1.3 2016/12/12 20:10:04 schwarze Exp $
 .\"	OpenSSL c952780c Jun 21 07:03:34 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" 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.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2014 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,10 +65,16 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 6 2016 $
+.Dd $Mdocdate: December 12 2016 $
 .Dt OCSP_RESP_FIND_STATUS 3
 .Os
 .Sh NAME
+.Nm OCSP_SINGLERESP_new ,
+.Nm OCSP_SINGLERESP_free ,
+.Nm OCSP_CERTSTATUS_new ,
+.Nm OCSP_CERTSTATUS_free ,
+.Nm OCSP_REVOKEDINFO_new ,
+.Nm OCSP_REVOKEDINFO_free ,
 .Nm OCSP_resp_find_status ,
 .Nm OCSP_resp_count ,
 .Nm OCSP_resp_get0 ,
@@ -61,6 +84,18 @@
 .Nd OCSP response utility functions
 .Sh SYNOPSIS
 .In openssl/ocsp.h
+.Ft OCSP_SINGLERESP *
+.Fn OCSP_SINGLERESP_new void
+.Ft void
+.Fn OCSP_SINGLERESP_free "OCSP_SINGLERESP *single"
+.Ft OCSP_CERTSTATUS *
+.Fn OCSP_CERTSTATUS_new void
+.Ft void
+.Fn OCSP_CERTSTATUS_free "OCSP_CERTSTATUS *certstatus"
+.Ft OCSP_REVOKEDINFO *
+.Fn OCSP_REVOKEDINFO_new void
+.Ft void
+.Fn OCSP_REVOKEDINFO_free "OCSP_REVOKEDINFO *revokedinfo"
 .Ft int
 .Fo OCSP_resp_find_status
 .Fa "OCSP_BASICRESP *bs"
@@ -102,6 +137,42 @@
 .Fa "long maxsec"
 .Fc
 .Sh DESCRIPTION
+.Fn OCSP_SINGLERESP_new
+allocates and initializes an empty
+.Vt OCSP_SINGLERESP
+object, representing an ASN.1 SingleResponse structure defined in RFC 6960.
+Each such object can store the server's answer regarding the validity
+of one individual certificate.
+Such objects are used inside the
+.Vt OCSP_RESPDATA
+of
+.Vt OCSP_BASICRESP
+objects, which are described in
+.Xr OCSP_BASICRESP_new 3 .
+.Fn OCSP_SINGLERESP_free
+frees
+.Fa single .
+.Pp
+.Fn OCSP_CERTSTATUS_new
+allocates and initializes an empty
+.Vt OCSP_CERTSTATUS
+object, representing an ASN.1 CertStatus structure defined in RFC 6960.
+Such an object is used inside
+.Vt OCSP_SINGLERESP .
+.Fn OCSP_CERTSTATUS_free
+frees
+.Fa certstatus .
+.Pp
+.Fn OCSP_REVOKEDINFO_new
+allocates and initializes an empty
+.Vt OCSP_REVOKEDINFO
+object, representing an ASN.1 RevokedInfo structure defined in RFC 6960.
+Such an object is used inside
+.Vt OCSP_CERTSTATUS .
+.Fn OCSP_REVOKEDINFO_free
+frees
+.Fa revokedinfo .
+.Pp
 .Fn OCSP_resp_find_status
 searches
 .Fa bs
@@ -241,6 +312,19 @@ Any or all of these parameters can be set to
 .Dv NULL
 if their value is not required.
 .Sh RETURN VALUES
+.Fn OCSP_SINGLERESP_new ,
+.Fn OCSP_CERTSTATUS_new ,
+and
+.Fn OCSP_REVOKEDINFO_new
+return a pointer to an empty
+.Vt OCSP_SINGLERESP ,
+.Vt OCSP_CERTSTATUS ,
+or
+.Vt OCSP_REVOKEDINFO
+object, respectively, or
+.Dv NULL
+if an error occurred.
+.Pp
 .Fn OCSP_resp_find_status
 returns 1 if
 .Fa id
@@ -282,3 +366,6 @@ or -1 if an error occurred.
 .Xr OCSP_REQUEST_new 3 ,
 .Xr OCSP_response_status 3 ,
 .Xr OCSP_sendreq_new 3
+.Sh STANDARDS
+RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate
+Status Protocol, section 4.2: Response Syntax