1.\" $OpenBSD: OCSP_resp_find_status.3,v 1.11 2022/03/31 17:27:17 naddy Exp $ 2.\" full merge up to: OpenSSL c952780c Jun 21 07:03:34 2016 -0400 3.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2016, 2018, 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.\" and David von Oheimb <David.von.Oheimb@siemens.com>. 24.\" Copyright (c) 2014, 2018 The OpenSSL Project. All rights reserved. 25.\" 26.\" Redistribution and use in source and binary forms, with or without 27.\" modification, are permitted provided that the following conditions 28.\" are met: 29.\" 30.\" 1. Redistributions of source code must retain the above copyright 31.\" notice, this list of conditions and the following disclaimer. 32.\" 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in 35.\" the documentation and/or other materials provided with the 36.\" distribution. 37.\" 38.\" 3. All advertising materials mentioning features or use of this 39.\" software must display the following acknowledgment: 40.\" "This product includes software developed by the OpenSSL Project 41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 42.\" 43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 44.\" endorse or promote products derived from this software without 45.\" prior written permission. For written permission, please contact 46.\" openssl-core@openssl.org. 47.\" 48.\" 5. Products derived from this software may not be called "OpenSSL" 49.\" nor may "OpenSSL" appear in their names without prior written 50.\" permission of the OpenSSL Project. 51.\" 52.\" 6. Redistributions of any form whatsoever must retain the following 53.\" acknowledgment: 54.\" "This product includes software developed by the OpenSSL Project 55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 69.\" 70.Dd $Mdocdate: March 31 2022 $ 71.Dt OCSP_RESP_FIND_STATUS 3 72.Os 73.Sh NAME 74.Nm OCSP_SINGLERESP_new , 75.Nm OCSP_SINGLERESP_free , 76.Nm OCSP_CERTSTATUS_new , 77.Nm OCSP_CERTSTATUS_free , 78.Nm OCSP_REVOKEDINFO_new , 79.Nm OCSP_REVOKEDINFO_free , 80.Nm OCSP_resp_find_status , 81.Nm OCSP_cert_status_str , 82.Nm OCSP_resp_count , 83.Nm OCSP_resp_get0 , 84.Nm OCSP_resp_find , 85.Nm OCSP_SINGLERESP_get0_id , 86.Nm OCSP_single_get0_status , 87.Nm OCSP_check_validity , 88.Nm OCSP_basic_verify 89.Nd OCSP response utility functions 90.Sh SYNOPSIS 91.In openssl/ocsp.h 92.Ft OCSP_SINGLERESP * 93.Fn OCSP_SINGLERESP_new void 94.Ft void 95.Fn OCSP_SINGLERESP_free "OCSP_SINGLERESP *single" 96.Ft OCSP_CERTSTATUS * 97.Fn OCSP_CERTSTATUS_new void 98.Ft void 99.Fn OCSP_CERTSTATUS_free "OCSP_CERTSTATUS *certstatus" 100.Ft OCSP_REVOKEDINFO * 101.Fn OCSP_REVOKEDINFO_new void 102.Ft void 103.Fn OCSP_REVOKEDINFO_free "OCSP_REVOKEDINFO *revokedinfo" 104.Ft int 105.Fo OCSP_resp_find_status 106.Fa "OCSP_BASICRESP *bs" 107.Fa "OCSP_CERTID *id" 108.Fa "int *status" 109.Fa "int *reason" 110.Fa "ASN1_GENERALIZEDTIME **revtime" 111.Fa "ASN1_GENERALIZEDTIME **thisupd" 112.Fa "ASN1_GENERALIZEDTIME **nextupd" 113.Fc 114.Ft const char * 115.Fo OCSP_cert_status_str 116.Fa "long status" 117.Fc 118.Ft int 119.Fo OCSP_resp_count 120.Fa "OCSP_BASICRESP *bs" 121.Fc 122.Ft OCSP_SINGLERESP * 123.Fo OCSP_resp_get0 124.Fa "OCSP_BASICRESP *bs" 125.Fa "int idx" 126.Fc 127.Ft int 128.Fo OCSP_resp_find 129.Fa "OCSP_BASICRESP *bs" 130.Fa "OCSP_CERTID *id" 131.Fa "int last" 132.Fc 133.Ft const OCSP_CERTID * 134.Fo OCSP_SINGLERESP_get0_id 135.Fa "const OCSP_SINGLERESP *single" 136.Fc 137.Ft int 138.Fo OCSP_single_get0_status 139.Fa "OCSP_SINGLERESP *single" 140.Fa "int *reason" 141.Fa "ASN1_GENERALIZEDTIME **revtime" 142.Fa "ASN1_GENERALIZEDTIME **thisupd" 143.Fa "ASN1_GENERALIZEDTIME **nextupd" 144.Fc 145.Ft int 146.Fo OCSP_check_validity 147.Fa "ASN1_GENERALIZEDTIME *thisupd" 148.Fa "ASN1_GENERALIZEDTIME *nextupd" 149.Fa "long sec" 150.Fa "long maxsec" 151.Fc 152.Ft int 153.Fo OCSP_basic_verify 154.Fa "OCSP_BASICRESP *bs" 155.Fa "STACK_OF(X509) *certs" 156.Fa "X509_STORE *st" 157.Fa "unsigned long flags" 158.Fc 159.Sh DESCRIPTION 160.Fn OCSP_SINGLERESP_new 161allocates and initializes an empty 162.Vt OCSP_SINGLERESP 163object, representing an ASN.1 164.Vt SingleResponse 165structure defined in RFC 6960. 166Each such object can store the server's answer regarding the validity 167of one individual certificate. 168Such objects are used inside the 169.Vt OCSP_RESPDATA 170of 171.Vt OCSP_BASICRESP 172objects, which are described in 173.Xr OCSP_BASICRESP_new 3 . 174.Fn OCSP_SINGLERESP_free 175frees 176.Fa single . 177.Pp 178.Fn OCSP_CERTSTATUS_new 179allocates and initializes an empty 180.Vt OCSP_CERTSTATUS 181object, representing an ASN.1 182.Vt CertStatus 183structure defined in RFC 6960. 184Such an object is used inside 185.Vt OCSP_SINGLERESP . 186.Fn OCSP_CERTSTATUS_free 187frees 188.Fa certstatus . 189.Pp 190.Fn OCSP_REVOKEDINFO_new 191allocates and initializes an empty 192.Vt OCSP_REVOKEDINFO 193object, representing an ASN.1 194.Vt RevokedInfo 195structure defined in RFC 6960. 196Such an object is used inside 197.Vt OCSP_CERTSTATUS . 198.Fn OCSP_REVOKEDINFO_free 199frees 200.Fa revokedinfo . 201.Pp 202.Fn OCSP_resp_find_status 203searches 204.Fa bs 205for an OCSP response for 206.Fa id . 207If it is successful, the fields of the response are returned in 208.Pf * Fa status , 209.Pf * Fa reason , 210.Pf * Fa revtime , 211.Pf * Fa thisupd 212and 213.Pf * Fa nextupd . 214The 215.Pf * Fa status 216value will be one of 217.Dv V_OCSP_CERTSTATUS_GOOD , 218.Dv V_OCSP_CERTSTATUS_REVOKED , 219or 220.Dv V_OCSP_CERTSTATUS_UNKNOWN . 221The 222.Pf * Fa reason 223and 224.Pf * Fa revtime 225fields are only set if the status is 226.Dv V_OCSP_CERTSTATUS_REVOKED . 227If set, the 228.Pf * Fa reason 229field will be set to the revocation reason which will be one of 230.Dv OCSP_REVOKED_STATUS_NOSTATUS , 231.Dv OCSP_REVOKED_STATUS_UNSPECIFIED , 232.Dv OCSP_REVOKED_STATUS_KEYCOMPROMISE , 233.Dv OCSP_REVOKED_STATUS_CACOMPROMISE , 234.Dv OCSP_REVOKED_STATUS_AFFILIATIONCHANGED , 235.Dv OCSP_REVOKED_STATUS_SUPERSEDED , 236.Dv OCSP_REVOKED_STATUS_CESSATIONOFOPERATION , 237.Dv OCSP_REVOKED_STATUS_CERTIFICATEHOLD 238or 239.Dv OCSP_REVOKED_STATUS_REMOVEFROMCRL . 240.Pp 241.Fn OCSP_cert_status_str 242converts one of the 243.Fa status 244codes retrieved by 245.Fn OCSP_resp_find_status 246to a string consisting of one word. 247.Pp 248.Fn OCSP_resp_count 249returns the number of 250.Vt OCSP_SINGLERESP 251structures in 252.Fa bs . 253.Pp 254.Fn OCSP_resp_get0 255returns the 256.Vt OCSP_SINGLERESP 257structure in 258.Fa bs 259corresponding to index 260.Fa idx , 261where 262.Fa idx 263runs from 0 to 264.Fn OCSP_resp_count bs No - 1 . 265.Pp 266.Fn OCSP_resp_find 267searches 268.Fa bs 269for 270.Fa id 271and returns the index of the first matching entry after 272.Fa last 273or starting from the beginning if 274.Fa last 275is -1. 276.Pp 277.Fn OCSP_single_get0_status 278extracts the fields of 279.Fa single 280in 281.Pf * Fa reason , 282.Pf * Fa revtime , 283.Pf * Fa thisupd , 284and 285.Pf * Fa nextupd . 286.Pp 287.Fn OCSP_check_validity 288checks the validity of 289.Fa thisupd 290and 291.Fa nextupd 292values which will be typically obtained from 293.Fn OCSP_resp_find_status 294or 295.Fn OCSP_single_get0_status . 296If 297.Fa sec 298is non-zero, it indicates how many seconds leeway should be allowed in 299the check. 300If 301.Fa maxsec 302is positive, it indicates the maximum age of 303.Fa thisupd 304in seconds. 305.Pp 306Applications will typically call 307.Fn OCSP_resp_find_status 308using the certificate ID of interest and then check its validity using 309.Fn OCSP_check_validity . 310They can then take appropriate action based on the status of the 311certificate. 312.Pp 313An OCSP response for a certificate contains 314.Sy thisUpdate 315and 316.Sy nextUpdate 317fields. 318Normally the current time should be between these two values. 319To account for clock skew, the 320.Fa maxsec 321field can be set to non-zero in 322.Fn OCSP_check_validity . 323Some responders do not set the 324.Sy nextUpdate 325field. 326This would otherwise mean an ancient response would be considered 327valid: the 328.Fa maxsec 329parameter to 330.Fn OCSP_check_validity 331can be used to limit the permitted age of responses. 332.Pp 333The values written to 334.Pf * Fa revtime , 335.Pf * Fa thisupd , 336and 337.Pf * Fa nextupd 338by 339.Fn OCSP_resp_find_status 340and 341.Fn OCSP_single_get0_status 342are internal pointers which must not be freed up by the calling 343application. 344Any or all of these parameters can be set to 345.Dv NULL 346if their value is not required. 347.Pp 348.Fn OCSP_basic_verify 349checks that the basic response message 350.Fa bs 351is correctly signed and that the signer certificate can be validated. 352It takes 353.Fa st 354as the trusted store and 355.Fa certs 356as a set of untrusted intermediate certificates. 357The function first tries to find the signer certificate of the response in 358.Fa certs . 359It also searches the certificates the responder may have included in 360.Fa bs 361unless the 362.Fa flags 363contain 364.Dv OCSP_NOINTERN . 365It fails if the signer certificate cannot be found. 366Next, the function checks the signature of 367.Fa bs 368and fails on error unless the 369.Fa flags 370contain 371.Dv OCSP_NOSIGS . 372Then the function already returns 373success if the 374.Fa flags 375contain 376.Dv OCSP_NOVERIFY 377or if the signer certificate was found in 378.Fa certs 379and the 380.Fa flags 381contain 382.Dv OCSP_TRUSTOTHER . 383Otherwise the function continues by validating the signer certificate. 384To this end, all certificates in 385.Fa certs 386and in 387.Fa bs 388are considered as untrusted certificates for the construction of 389the validation path for the signer certificate unless the 390.Dv OCSP_NOCHAIN 391flag is set. 392After successful path 393validation, the function returns success if the 394.Dv OCSP_NOCHECKS 395flag is set. 396Otherwise it verifies that the signer certificate meets the OCSP issuer 397criteria including potential delegation. 398If this does not succeed and the 399.Fa flags 400do not contain 401.Dv OCSP_NOEXPLICIT , 402the function checks for explicit trust for OCSP signing 403in the root CA certificate. 404.Sh RETURN VALUES 405.Fn OCSP_SINGLERESP_new , 406.Fn OCSP_CERTSTATUS_new , 407and 408.Fn OCSP_REVOKEDINFO_new 409return a pointer to an empty 410.Vt OCSP_SINGLERESP , 411.Vt OCSP_CERTSTATUS , 412or 413.Vt OCSP_REVOKEDINFO 414object, respectively, or 415.Dv NULL 416if an error occurred. 417.Pp 418.Fn OCSP_resp_find_status 419returns 1 if 420.Fa id 421is found in 422.Fa bs 423or 0 otherwise. 424.Pp 425.Fn OCSP_cert_status_str 426returns a pointer to a static string. 427.Pp 428.Fn OCSP_resp_count 429returns the total number of 430.Vt OCSP_SINGLERESP 431fields in 432.Fa bs . 433.Pp 434.Fn OCSP_resp_get0 435returns a pointer to an 436.Vt OCSP_SINGLERESP 437structure or 438.Dv NULL 439if 440.Fa idx 441is out of range. 442.Pp 443.Fn OCSP_resp_find 444returns the index of 445.Fa id 446in 447.Fa bs 448(which may be 0) or -1 if 449.Fa id 450was not found. 451.Pp 452.Fn OCSP_SINGLERESP_get0_id 453returns an internal pointer to the certificate ID object used by 454.Fa single ; 455the returned pointer should not be freed by the caller. 456.Pp 457.Fn OCSP_single_get0_status 458returns the status of 459.Fa single 460or -1 if an error occurred. 461.Pp 462.Fn OCSP_basic_verify 463returns 1 on success, 0 on error, or -1 on fatal error such as malloc failure. 464.Sh SEE ALSO 465.Xr OCSP_cert_to_id 3 , 466.Xr OCSP_CRLID_new 3 , 467.Xr OCSP_request_add1_nonce 3 , 468.Xr OCSP_REQUEST_new 3 , 469.Xr OCSP_response_status 3 , 470.Xr OCSP_sendreq_new 3 471.Sh STANDARDS 472RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate 473Status Protocol, section 4.2: Response Syntax 474.Sh HISTORY 475.Fn OCSP_SINGLERESP_new , 476.Fn OCSP_SINGLERESP_free , 477.Fn OCSP_CERTSTATUS_new , 478.Fn OCSP_CERTSTATUS_free , 479.Fn OCSP_REVOKEDINFO_new , 480.Fn OCSP_REVOKEDINFO_free , 481.Fn OCSP_resp_find_status , 482.Fn OCSP_cert_status_str , 483.Fn OCSP_resp_count , 484.Fn OCSP_resp_get0 , 485.Fn OCSP_resp_find , 486.Fn OCSP_single_get0_status , 487and 488.Fn OCSP_check_validity 489first appeared in OpenSSL 0.9.7 and have been available since 490.Ox 3.2 . 491.Pp 492.Fn OCSP_SINGLERESP_get0_id 493first appeared in OpenSSL 1.1.0 and has been available since 494.Ox 6.3 . 495