From ad66f778ac030fef08a6451194211724a877f664 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 12 Dec 2016 18:45:29 +0000 Subject: Document OCSP_RESPONSE_new(3), OCSP_RESPONSE_free(3), OCSP_RESPBYTES_new(3), OCSP_RESPBYTES_free(3), OCSP_BASICRESP_new(3), OCSP_BASICRESP_free(3), OCSP_RESPDATA_new(3), OCSP_RESPDATA_free(3), OCSP_RESPID_new(3), and OCSP_RESPID_free(3), all in 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. Sort functions into a logical order and apply minor wording tweaks. --- src/lib/libcrypto/man/OCSP_response_status.3 | 180 +++++++++++++++++++++------ 1 file changed, 144 insertions(+), 36 deletions(-) diff --git a/src/lib/libcrypto/man/OCSP_response_status.3 b/src/lib/libcrypto/man/OCSP_response_status.3 index b81c2102da..33a9dfb1a2 100644 --- a/src/lib/libcrypto/man/OCSP_response_status.3 +++ b/src/lib/libcrypto/man/OCSP_response_status.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: OCSP_response_status.3,v 1.2 2016/12/06 14:54:55 schwarze Exp $ +.\" $OpenBSD: OCSP_response_status.3,v 1.3 2016/12/12 18:45:29 schwarze Exp $ .\" OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 Ingo Schwarze +.\" +.\" 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 . .\" Copyright (c) 2014, 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,39 +65,122 @@ .\" 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_RESPONSE_STATUS 3 .Os .Sh NAME -.Nm OCSP_response_status , -.Nm OCSP_response_get1_basic , +.Nm OCSP_RESPONSE_new , +.Nm OCSP_RESPONSE_free , +.Nm OCSP_RESPBYTES_new , +.Nm OCSP_RESPBYTES_free , +.Nm OCSP_BASICRESP_new , +.Nm OCSP_BASICRESP_free , +.Nm OCSP_RESPDATA_new , +.Nm OCSP_RESPDATA_free , +.Nm OCSP_RESPID_new , +.Nm OCSP_RESPID_free , .Nm OCSP_response_create , -.Nm OCSP_RESPONSE_free +.Nm OCSP_response_status , +.Nm OCSP_response_get1_basic .Nd OCSP response functions .Sh SYNOPSIS .In openssl/ocsp.h -.Ft int -.Fo OCSP_response_status -.Fa "OCSP_RESPONSE *resp" -.Fc +.Ft OCSP_RESPONSE * +.Fn OCSP_RESPONSE_new void +.Ft void +.Fn OCSP_RESPONSE_free "OCSP_RESPONSE *resp" +.Ft OCSP_RESPBYTES * +.Fn OCSP_RESPBYTES_new void +.Ft void +.Fn OCSP_RESPBYTES_free "OCSP_RESPBYTES *respbytes" .Ft OCSP_BASICRESP * -.Fo OCSP_response_get1_basic -.Fa "OCSP_RESPONSE *resp" -.Fc +.Fn OCSP_BASICRESP_new void +.Ft void +.Fn OCSP_BASICRESP_free "OCSP_BASICRESP *bs" +.Ft OCSP_RESPDATA * +.Fn OCSP_RESPDATA_new void +.Ft void +.Fn OCSP_RESPDATA_free "OCSP_RESPDATA *respdata" +.Ft OCSP_RESPID * +.Fn OCSP_RESPID_new void +.Ft void +.Fn OCSP_RESPID_free "OCSP_RESPID *respid" .Ft OCSP_RESPONSE * .Fo OCSP_response_create .Fa "int status" .Fa "OCSP_BASICRESP *bs" .Fc -.Ft void -.Fo OCSP_RESPONSE_free +.Ft int +.Fo OCSP_response_status +.Fa "OCSP_RESPONSE *resp" +.Fc +.Ft OCSP_BASICRESP * +.Fo OCSP_response_get1_basic .Fa "OCSP_RESPONSE *resp" .Fc .Sh DESCRIPTION +.Fn OCSP_RESPONSE_new +allocates and initializes an empty +.Vt OCSP_RESPONSE +object, representing an ASN.1 OCSPResponse structure defined in RFC 6960. +.Fn OCSP_RESPONSE_free +frees +.Fa resp . +.Pp +.Fn OCSP_RESPBYTES_new +allocates and initializes an empty +.Vt OCSP_RESPBYTES +object, representing an ASN.1 ResponseBytes structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_RESPONSE . +.Fn OCSP_RESPBYTES_free +frees +.Fa respbytes . +.Pp +.Fn OCSP_BASICRESP_new +allocates and initializes an empty +.Vt OCSP_BASICRESP +object, representing an ASN.1 BasicOCSPResponse structure defined in RFC 6960. +.Vt OCSP_RESPBYTES +contains the DER-encoded form of an +.Vt OCSP_BASICRESP +object. +.Fn OCSP_BASICRESP_free +frees +.Fa bs . +.Pp +.Fn OCSP_RESPDATA_new +allocates and initializes an empty +.Vt OCSP_RESPDATA +object, representing an ASN.1 ResponseData structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_BASICRESP . +.Fn OCSP_RESPDATA_free +frees +.Fa respdata . +.Pp +.Fn OCSP_RESPID_new +allocates and initializes an empty +.Vt OCSP_RESPID +object, representing an ASN.1 ResponderID structure defined in RFC 6960. +Such an object is used inside +.Vt OCSP_RESPDATA . +.Fn OCSP_RESPID_free +frees +.Fa respid . +.Pp +.Fn OCSP_response_create +creates an +.Vt OCSP_RESPONSE +object for +.Fa status +and optionally including the basic response +.Fa bs . +.Pp .Fn OCSP_response_status returns the OCSP response status of .Fa resp . -It returns one of the values: +It returns one of the values .Dv OCSP_RESPONSE_STATUS_SUCCESSFUL , .Dv OCSP_RESPONSE_STATUS_MALFORMEDREQUEST , .Dv OCSP_RESPONSE_STATUS_INTERNALERROR , @@ -92,42 +192,50 @@ or .Fn OCSP_response_get1_basic decodes and returns the .Vt OCSP_BASICRESP -structure contained in +object contained in .Fa resp . It is only called if the status of a response is .Dv OCSP_RESPONSE_STATUS_SUCCESSFUL . -.Pp +.Sh RETURN VALUES +.Fn OCSP_RESPONSE_new +and .Fn OCSP_response_create -creates and returns an +return a pointer to an .Vt OCSP_RESPONSE -structure for -.Fa status -and optionally including basic response -.Fa bs . -.Pp -.Fn OCSP_RESPONSE_free -frees up OCSP response -.Fa resp . -.Sh RETURN VALUES -.Fn OCSP_response_status -returns a status value. +object or +.Dv NULL +if an error occurred. .Pp +.Fn OCSP_BASICRESP_new +and .Fn OCSP_response_get1_basic -returns an +return a pointer to an .Vt OCSP_BASICRESP -structure pointer or +object or .Dv NULL if an error occurred. .Pp -.Fn OCSP_response_create -returns an -.Vt OCSP_RESPONSE -structure pointer or +.Fn OCSP_RESPBYTES_new , +.Fn OCSP_RESPDATA_new , +and +.Fn OCSP_RESPID_new +return a pointer to an empty +.Vt OCSP_RESPBYTES , +.Vt OCSP_RESPDATA , +or +.Vt OCSP_RESPID +object, respectively, or .Dv NULL if an error occurred. +.Pp +.Fn OCSP_response_status +returns a status value. .Sh SEE ALSO .Xr OCSP_cert_to_id 3 , .Xr OCSP_request_add1_nonce 3 , .Xr OCSP_REQUEST_new 3 , .Xr OCSP_resp_find_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 -- cgit v1.2.3-55-g6feb