1.\" $OpenBSD: OCSP_response_status.3,v 1.7 2019/06/06 01:06:58 schwarze Exp $ 2.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 3.\" selective merge up to: OpenSSL e23ac625 Jan 24 12:27:19 2018 -0500 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2014, 2016, 2018 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: June 6 2019 $ 70.Dt OCSP_RESPONSE_STATUS 3 71.Os 72.Sh NAME 73.Nm OCSP_RESPONSE_new , 74.Nm OCSP_RESPONSE_free , 75.Nm OCSP_RESPBYTES_new , 76.Nm OCSP_RESPBYTES_free , 77.Nm OCSP_BASICRESP_new , 78.Nm OCSP_BASICRESP_free , 79.Nm OCSP_RESPDATA_new , 80.Nm OCSP_RESPDATA_free , 81.Nm OCSP_RESPID_new , 82.Nm OCSP_RESPID_free , 83.Nm OCSP_response_create , 84.Nm OCSP_response_status , 85.Nm OCSP_response_get1_basic , 86.Nm OCSP_basic_sign 87.Nd OCSP response functions 88.Sh SYNOPSIS 89.In openssl/ocsp.h 90.Ft OCSP_RESPONSE * 91.Fn OCSP_RESPONSE_new void 92.Ft void 93.Fn OCSP_RESPONSE_free "OCSP_RESPONSE *resp" 94.Ft OCSP_RESPBYTES * 95.Fn OCSP_RESPBYTES_new void 96.Ft void 97.Fn OCSP_RESPBYTES_free "OCSP_RESPBYTES *respbytes" 98.Ft OCSP_BASICRESP * 99.Fn OCSP_BASICRESP_new void 100.Ft void 101.Fn OCSP_BASICRESP_free "OCSP_BASICRESP *bs" 102.Ft OCSP_RESPDATA * 103.Fn OCSP_RESPDATA_new void 104.Ft void 105.Fn OCSP_RESPDATA_free "OCSP_RESPDATA *respdata" 106.Ft OCSP_RESPID * 107.Fn OCSP_RESPID_new void 108.Ft void 109.Fn OCSP_RESPID_free "OCSP_RESPID *respid" 110.Ft OCSP_RESPONSE * 111.Fo OCSP_response_create 112.Fa "int status" 113.Fa "OCSP_BASICRESP *bs" 114.Fc 115.Ft int 116.Fo OCSP_response_status 117.Fa "OCSP_RESPONSE *resp" 118.Fc 119.Ft OCSP_BASICRESP * 120.Fo OCSP_response_get1_basic 121.Fa "OCSP_RESPONSE *resp" 122.Fc 123.Ft int 124.Fo OCSP_basic_sign 125.Fa "OCSP_BASICRESP *bs" 126.Fa "X509 *signer" 127.Fa "EVP_PKEY *key" 128.Fa "const EVP_MD *dgst" 129.Fa "STACK_OF(X509) *certs" 130.Fa "unsigned long flags" 131.Fc 132.Sh DESCRIPTION 133.Fn OCSP_RESPONSE_new 134allocates and initializes an empty 135.Vt OCSP_RESPONSE 136object, representing an ASN.1 137.Vt OCSPResponse 138structure defined in RFC 6960. 139.Fn OCSP_RESPONSE_free 140frees 141.Fa resp . 142.Pp 143.Fn OCSP_RESPBYTES_new 144allocates and initializes an empty 145.Vt OCSP_RESPBYTES 146object, representing an ASN.1 147.Vt ResponseBytes 148structure defined in RFC 6960. 149Such an object is used inside 150.Vt OCSP_RESPONSE . 151.Fn OCSP_RESPBYTES_free 152frees 153.Fa respbytes . 154.Pp 155.Fn OCSP_BASICRESP_new 156allocates and initializes an empty 157.Vt OCSP_BASICRESP 158object, representing an ASN.1 159.Vt BasicOCSPResponse 160structure defined in RFC 6960. 161.Vt OCSP_RESPBYTES 162contains the DER-encoded form of an 163.Vt OCSP_BASICRESP 164object. 165.Fn OCSP_BASICRESP_free 166frees 167.Fa bs . 168.Pp 169.Fn OCSP_RESPDATA_new 170allocates and initializes an empty 171.Vt OCSP_RESPDATA 172object, representing an ASN.1 173.Vt ResponseData 174structure defined in RFC 6960. 175Such an object is used inside 176.Vt OCSP_BASICRESP . 177.Fn OCSP_RESPDATA_free 178frees 179.Fa respdata . 180.Pp 181.Fn OCSP_RESPID_new 182allocates and initializes an empty 183.Vt OCSP_RESPID 184object, representing an ASN.1 185.Vt ResponderID 186structure defined in RFC 6960. 187Such an object is used inside 188.Vt OCSP_RESPDATA . 189.Fn OCSP_RESPID_free 190frees 191.Fa respid . 192.Pp 193.Fn OCSP_response_create 194creates an 195.Vt OCSP_RESPONSE 196object for 197.Fa status 198and optionally including the basic response 199.Fa bs . 200.Pp 201.Fn OCSP_response_status 202returns the OCSP response status of 203.Fa resp . 204It returns one of the values 205.Dv OCSP_RESPONSE_STATUS_SUCCESSFUL , 206.Dv OCSP_RESPONSE_STATUS_MALFORMEDREQUEST , 207.Dv OCSP_RESPONSE_STATUS_INTERNALERROR , 208.Dv OCSP_RESPONSE_STATUS_TRYLATER , 209.Dv OCSP_RESPONSE_STATUS_SIGREQUIRED , 210or 211.Dv OCSP_RESPONSE_STATUS_UNAUTHORIZED . 212.Pp 213.Fn OCSP_response_get1_basic 214decodes and returns the 215.Vt OCSP_BASICRESP 216object contained in 217.Fa resp . 218It is only called if the status of a response is 219.Dv OCSP_RESPONSE_STATUS_SUCCESSFUL . 220.Pp 221.Fn OCSP_basic_sign 222signs the OCSP response 223.Fa bs 224using the certificate 225.Fa signer , 226the private key 227.Fa key , 228the digest 229.Fa dgst , 230and the additional certificates 231.Fa certs . 232If the 233.Fa flags 234option 235.Dv OCSP_NOCERTS 236is set, then no certificates will be included in the request. 237If the 238.Fa flags 239option 240.Dv OCSP_RESPID_KEY 241is set, then the responder is identified by key ID 242rather than by name. 243.Sh RETURN VALUES 244.Fn OCSP_RESPONSE_new 245and 246.Fn OCSP_response_create 247return a pointer to an 248.Vt OCSP_RESPONSE 249object or 250.Dv NULL 251if an error occurred. 252.Pp 253.Fn OCSP_BASICRESP_new 254and 255.Fn OCSP_response_get1_basic 256return a pointer to an 257.Vt OCSP_BASICRESP 258object or 259.Dv NULL 260if an error occurred. 261.Pp 262.Fn OCSP_RESPBYTES_new , 263.Fn OCSP_RESPDATA_new , 264and 265.Fn OCSP_RESPID_new 266return a pointer to an empty 267.Vt OCSP_RESPBYTES , 268.Vt OCSP_RESPDATA , 269or 270.Vt OCSP_RESPID 271object, respectively, or 272.Dv NULL 273if an error occurred. 274.Pp 275.Fn OCSP_response_status 276returns a status value. 277.Pp 278.Fn OCSP_basic_sign 279return 1 on success or 0 on failure. 280.Sh SEE ALSO 281.Xr EVP_DigestInit 3 , 282.Xr OCSP_cert_to_id 3 , 283.Xr OCSP_request_add1_nonce 3 , 284.Xr OCSP_REQUEST_new 3 , 285.Xr OCSP_resp_find_status 3 , 286.Xr OCSP_sendreq_new 3 287.Sh STANDARDS 288RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate 289Status Protocol, section 4.2: Response Syntax 290.Sh HISTORY 291These functions first appeared in OpenSSL 0.9.7 292and have been available since 293.Ox 3.2 . 294