1.\" $OpenBSD: OCSP_response_status.3,v 1.8 2019/08/27 09:40:29 schwarze Exp $ 2.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 3.\" selective merge up to: OpenSSL 6738bf14 Feb 13 12:51:29 2018 +0000 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2016, 2019 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: August 27 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_status_str , 86.Nm OCSP_response_get1_basic , 87.Nm OCSP_basic_sign 88.Nd OCSP response functions 89.Sh SYNOPSIS 90.In openssl/ocsp.h 91.Ft OCSP_RESPONSE * 92.Fn OCSP_RESPONSE_new void 93.Ft void 94.Fn OCSP_RESPONSE_free "OCSP_RESPONSE *resp" 95.Ft OCSP_RESPBYTES * 96.Fn OCSP_RESPBYTES_new void 97.Ft void 98.Fn OCSP_RESPBYTES_free "OCSP_RESPBYTES *respbytes" 99.Ft OCSP_BASICRESP * 100.Fn OCSP_BASICRESP_new void 101.Ft void 102.Fn OCSP_BASICRESP_free "OCSP_BASICRESP *bs" 103.Ft OCSP_RESPDATA * 104.Fn OCSP_RESPDATA_new void 105.Ft void 106.Fn OCSP_RESPDATA_free "OCSP_RESPDATA *respdata" 107.Ft OCSP_RESPID * 108.Fn OCSP_RESPID_new void 109.Ft void 110.Fn OCSP_RESPID_free "OCSP_RESPID *respid" 111.Ft OCSP_RESPONSE * 112.Fo OCSP_response_create 113.Fa "int status" 114.Fa "OCSP_BASICRESP *bs" 115.Fc 116.Ft int 117.Fo OCSP_response_status 118.Fa "OCSP_RESPONSE *resp" 119.Fc 120.Ft const char * 121.Fo OCSP_response_status_str 122.Fa "long code" 123.Fc 124.Ft OCSP_BASICRESP * 125.Fo OCSP_response_get1_basic 126.Fa "OCSP_RESPONSE *resp" 127.Fc 128.Ft int 129.Fo OCSP_basic_sign 130.Fa "OCSP_BASICRESP *bs" 131.Fa "X509 *signer" 132.Fa "EVP_PKEY *key" 133.Fa "const EVP_MD *dgst" 134.Fa "STACK_OF(X509) *certs" 135.Fa "unsigned long flags" 136.Fc 137.Sh DESCRIPTION 138.Fn OCSP_RESPONSE_new 139allocates and initializes an empty 140.Vt OCSP_RESPONSE 141object, representing an ASN.1 142.Vt OCSPResponse 143structure defined in RFC 6960. 144.Fn OCSP_RESPONSE_free 145frees 146.Fa resp . 147.Pp 148.Fn OCSP_RESPBYTES_new 149allocates and initializes an empty 150.Vt OCSP_RESPBYTES 151object, representing an ASN.1 152.Vt ResponseBytes 153structure defined in RFC 6960. 154Such an object is used inside 155.Vt OCSP_RESPONSE . 156.Fn OCSP_RESPBYTES_free 157frees 158.Fa respbytes . 159.Pp 160.Fn OCSP_BASICRESP_new 161allocates and initializes an empty 162.Vt OCSP_BASICRESP 163object, representing an ASN.1 164.Vt BasicOCSPResponse 165structure defined in RFC 6960. 166.Vt OCSP_RESPBYTES 167contains the DER-encoded form of an 168.Vt OCSP_BASICRESP 169object. 170.Fn OCSP_BASICRESP_free 171frees 172.Fa bs . 173.Pp 174.Fn OCSP_RESPDATA_new 175allocates and initializes an empty 176.Vt OCSP_RESPDATA 177object, representing an ASN.1 178.Vt ResponseData 179structure defined in RFC 6960. 180Such an object is used inside 181.Vt OCSP_BASICRESP . 182.Fn OCSP_RESPDATA_free 183frees 184.Fa respdata . 185.Pp 186.Fn OCSP_RESPID_new 187allocates and initializes an empty 188.Vt OCSP_RESPID 189object, representing an ASN.1 190.Vt ResponderID 191structure defined in RFC 6960. 192Such an object is used inside 193.Vt OCSP_RESPDATA . 194.Fn OCSP_RESPID_free 195frees 196.Fa respid . 197.Pp 198.Fn OCSP_response_create 199creates an 200.Vt OCSP_RESPONSE 201object for 202.Fa status 203and optionally including the basic response 204.Fa bs . 205.Pp 206.Fn OCSP_response_status 207returns the OCSP response status of 208.Fa resp . 209It returns one of the values 210.Dv OCSP_RESPONSE_STATUS_SUCCESSFUL , 211.Dv OCSP_RESPONSE_STATUS_MALFORMEDREQUEST , 212.Dv OCSP_RESPONSE_STATUS_INTERNALERROR , 213.Dv OCSP_RESPONSE_STATUS_TRYLATER , 214.Dv OCSP_RESPONSE_STATUS_SIGREQUIRED , 215or 216.Dv OCSP_RESPONSE_STATUS_UNAUTHORIZED . 217.Pp 218.Fn OCSP_response_status_str 219converts one of the 220.Fa status 221codes returned by 222.Fn OCSP_response_status 223to a string consisting of one word. 224.Pp 225.Fn OCSP_response_get1_basic 226decodes and returns the 227.Vt OCSP_BASICRESP 228object contained in 229.Fa resp . 230It is only called if the status of a response is 231.Dv OCSP_RESPONSE_STATUS_SUCCESSFUL . 232.Pp 233.Fn OCSP_basic_sign 234signs the OCSP response 235.Fa bs 236using the certificate 237.Fa signer , 238the private key 239.Fa key , 240the digest 241.Fa dgst , 242and the additional certificates 243.Fa certs . 244If the 245.Fa flags 246option 247.Dv OCSP_NOCERTS 248is set, then no certificates will be included in the request. 249If the 250.Fa flags 251option 252.Dv OCSP_RESPID_KEY 253is set, then the responder is identified by key ID 254rather than by name. 255.Sh RETURN VALUES 256.Fn OCSP_RESPONSE_new 257and 258.Fn OCSP_response_create 259return a pointer to an 260.Vt OCSP_RESPONSE 261object or 262.Dv NULL 263if an error occurred. 264.Pp 265.Fn OCSP_BASICRESP_new 266and 267.Fn OCSP_response_get1_basic 268return a pointer to an 269.Vt OCSP_BASICRESP 270object or 271.Dv NULL 272if an error occurred. 273.Pp 274.Fn OCSP_RESPBYTES_new , 275.Fn OCSP_RESPDATA_new , 276and 277.Fn OCSP_RESPID_new 278return a pointer to an empty 279.Vt OCSP_RESPBYTES , 280.Vt OCSP_RESPDATA , 281or 282.Vt OCSP_RESPID 283object, respectively, or 284.Dv NULL 285if an error occurred. 286.Pp 287.Fn OCSP_response_status 288returns a status value. 289.Pp 290.Fn OCSP_response_status_str 291returns a pointer to a static string. 292.Pp 293.Fn OCSP_basic_sign 294return 1 on success or 0 on failure. 295.Sh SEE ALSO 296.Xr EVP_DigestInit 3 , 297.Xr OCSP_cert_to_id 3 , 298.Xr OCSP_request_add1_nonce 3 , 299.Xr OCSP_REQUEST_new 3 , 300.Xr OCSP_resp_find_status 3 , 301.Xr OCSP_sendreq_new 3 302.Sh STANDARDS 303RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate 304Status Protocol, section 4.2: Response Syntax 305.Sh HISTORY 306These functions first appeared in OpenSSL 0.9.7 307and have been available since 308.Ox 3.2 . 309