1.\" $OpenBSD: OCSP_REQUEST_new.3,v 1.12 2022/02/19 13:09:36 jsg Exp $ 2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2014, 2016 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: February 19 2022 $ 69.Dt OCSP_REQUEST_NEW 3 70.Os 71.Sh NAME 72.Nm OCSP_REQUEST_new , 73.Nm OCSP_REQUEST_free , 74.Nm OCSP_SIGNATURE_new , 75.Nm OCSP_SIGNATURE_free , 76.Nm OCSP_REQINFO_new , 77.Nm OCSP_REQINFO_free , 78.Nm OCSP_ONEREQ_new , 79.Nm OCSP_ONEREQ_free , 80.Nm OCSP_request_add0_id , 81.Nm OCSP_request_sign , 82.Nm OCSP_request_add1_cert , 83.Nm OCSP_request_onereq_count , 84.Nm OCSP_request_onereq_get0 85.Nd OCSP request functions 86.Sh SYNOPSIS 87.In openssl/ocsp.h 88.Ft OCSP_REQUEST * 89.Fn OCSP_REQUEST_new void 90.Ft void 91.Fn OCSP_REQUEST_free "OCSP_REQUEST *req" 92.Ft OCSP_SIGNATURE * 93.Fn OCSP_SIGNATURE_new void 94.Ft void 95.Fn OCSP_SIGNATURE_free "OCSP_SIGNATURE *signature" 96.Ft OCSP_REQINFO * 97.Fn OCSP_REQINFO_new void 98.Ft void 99.Fn OCSP_REQINFO_free "OCSP_REQINFO *reqinfo" 100.Ft OCSP_ONEREQ * 101.Fn OCSP_ONEREQ_new void 102.Ft void 103.Fn OCSP_ONEREQ_free "OCSP_ONEREQ *onereq" 104.Ft OCSP_ONEREQ * 105.Fo OCSP_request_add0_id 106.Fa "OCSP_REQUEST *req" 107.Fa "OCSP_CERTID *cid" 108.Fc 109.Ft int 110.Fo OCSP_request_sign 111.Fa "OCSP_REQUEST *req" 112.Fa "X509 *signer" 113.Fa "EVP_PKEY *key" 114.Fa "const EVP_MD *dgst" 115.Fa "STACK_OF(X509) *certs" 116.Fa "unsigned long flags" 117.Fc 118.Ft int 119.Fo OCSP_request_add1_cert 120.Fa "OCSP_REQUEST *req" 121.Fa "X509 *cert" 122.Fc 123.Ft int 124.Fo OCSP_request_onereq_count 125.Fa "OCSP_REQUEST *req" 126.Fc 127.Ft OCSP_ONEREQ * 128.Fo OCSP_request_onereq_get0 129.Fa "OCSP_REQUEST *req" 130.Fa "int i" 131.Fc 132.Sh DESCRIPTION 133.Fn OCSP_REQUEST_new 134allocates and initializes an empty 135.Vt OCSP_REQUEST 136object, representing an ASN.1 137.Vt OCSPRequest 138structure defined in RFC 6960. 139.Fn OCSP_REQUEST_free 140frees 141.Fa req . 142.Pp 143.Fn OCSP_SIGNATURE_new 144allocates and initializes an empty 145.Vt OCSP_SIGNATURE 146object, representing an ASN.1 147.Vt Signature 148structure defined in RFC 6960. 149Such an object is used inside 150.Vt OCSP_REQUEST . 151.Fn OCSP_SIGNATURE_free 152frees 153.Fa signature . 154.Pp 155.Fn OCSP_REQINFO_new 156allocates and initializes an empty 157.Vt OCSP_REQINFO 158object, representing an ASN.1 159.Vt TBSRequest 160structure defined in RFC 6960. 161Such an object is used inside 162.Vt OCSP_REQUEST . 163It asks about the validity of one or more certificates. 164.Fn OCSP_REQINFO_free 165frees 166.Fa reqinfo . 167.Pp 168.Fn OCSP_ONEREQ_new 169allocates and initializes an empty 170.Vt OCSP_ONEREQ 171object, representing an ASN.1 172.Vt Request 173structure defined in RFC 6960. 174Such objects are used inside 175.Vt OCSP_REQINFO . 176Each one asks about the validity of one certificate. 177.Fn OCSP_ONEREQ_free 178frees 179.Fa onereq . 180.Pp 181.Fn OCSP_request_add0_id 182adds certificate ID 183.Fa cid 184to 185.Fa req . 186It returns the 187.Vt OCSP_ONEREQ 188object added so an application can add additional extensions to the 189request. 190The 191.Fa cid 192parameter must not be freed up after the operation. 193.Pp 194.Fn OCSP_request_sign 195signs OCSP request 196.Fa req 197using certificate 198.Fa signer , 199private key 200.Fa key , 201digest 202.Fa dgst , 203and additional certificates 204.Fa certs . 205If the 206.Fa flags 207option 208.Dv OCSP_NOCERTS 209is set, then no certificates will be included in the request. 210.Pp 211.Fn OCSP_request_add1_cert 212adds certificate 213.Fa cert 214to request 215.Fa req . 216The application is responsible for freeing up 217.Fa cert 218after use. 219.Pp 220.Fn OCSP_request_onereq_count 221returns the total number of 222.Vt OCSP_ONEREQ 223objects in 224.Fa req . 225.Pp 226.Fn OCSP_request_onereq_get0 227returns an internal pointer to the 228.Vt OCSP_ONEREQ 229contained in 230.Fa req 231of index 232.Fa i . 233The index value 234.Fa i 235runs from 0 to 236.Fn OCSP_request_onereq_count req No - 1 . 237.Pp 238.Fn OCSP_request_onereq_count 239and 240.Fn OCSP_request_onereq_get0 241are mainly used by OCSP responders. 242.Sh RETURN VALUES 243.Fn OCSP_REQUEST_new , 244.Fn OCSP_SIGNATURE_new , 245.Fn OCSP_REQINFO_new , 246and 247.Fn OCSP_ONEREQ_new 248return an empty 249.Vt OCSP_REQUEST , 250.Vt OCSP_SIGNATURE , 251.Vt OCSP_REQINFO , 252or 253.Vt OCSP_ONEREQ 254object, respectively, or 255.Dv NULL 256if an error occurred. 257.Pp 258.Fn OCSP_request_add0_id 259returns the 260.Vt OCSP_ONEREQ 261object containing 262.Fa cid 263or 264.Dv NULL 265if an error occurred. 266.Pp 267.Fn OCSP_request_sign 268and 269.Fn OCSP_request_add1_cert 270return 1 for success or 0 for failure. 271.Pp 272.Fn OCSP_request_onereq_count 273returns the total number of 274.Vt OCSP_ONEREQ 275objects in 276.Fa req . 277.Pp 278.Fn OCSP_request_onereq_get0 279returns a pointer to an 280.Vt OCSP_ONEREQ 281object or 282.Dv NULL 283if the index value is out of range. 284.Sh EXAMPLES 285Create an 286.Vt OCSP_REQUEST 287object for certificate 288.Fa cert 289with issuer 290.Fa issuer : 291.Bd -literal -offset indent 292OCSP_REQUEST *req; 293OCSP_ID *cid; 294 295req = OCSP_REQUEST_new(); 296if (req == NULL) 297 /* error */ 298cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer); 299if (cid == NULL) 300 /* error */ 301 302if (OCSP_REQUEST_add0_id(req, cid) == NULL) 303 /* error */ 304 305 /* Do something with req, e.g. query responder */ 306 307OCSP_REQUEST_free(req); 308.Ed 309.Sh SEE ALSO 310.Xr ACCESS_DESCRIPTION_new 3 , 311.Xr crypto 3 , 312.Xr d2i_OCSP_REQUEST 3 , 313.Xr d2i_OCSP_RESPONSE 3 , 314.Xr EVP_DigestInit 3 , 315.Xr OCSP_cert_to_id 3 , 316.Xr OCSP_CRLID_new 3 , 317.Xr OCSP_request_add1_nonce 3 , 318.Xr OCSP_resp_find_status 3 , 319.Xr OCSP_response_status 3 , 320.Xr OCSP_sendreq_new 3 , 321.Xr OCSP_SERVICELOC_new 3 , 322.Xr X509_ocspid_print 3 323.Sh STANDARDS 324RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate 325Status Protocol, section 4.1: Request Syntax 326.Sh HISTORY 327These functions first appeared in OpenSSL 0.9.7 328and have been available since 329.Ox 3.2 . 330