.\" $OpenBSD: OCSP_resp_find_status.3,v 1.8 2018/03/23 23:18:17 schwarze Exp $ .\" full merge up to: OpenSSL c952780c Jun 21 07:03:34 2016 -0400 .\" .\" This file is a derived work. .\" The changes are covered by the following Copyright and license: .\" .\" Copyright (c) 2016, 2018 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 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: March 23 2018 $ .Dt OCSP_RESP_FIND_STATUS 3 .Os .Sh NAME .Nm OCSP_SINGLERESP_new , .Nm OCSP_SINGLERESP_free , .Nm OCSP_CERTSTATUS_new , .Nm OCSP_CERTSTATUS_free , .Nm OCSP_REVOKEDINFO_new , .Nm OCSP_REVOKEDINFO_free , .Nm OCSP_resp_find_status , .Nm OCSP_resp_count , .Nm OCSP_resp_get0 , .Nm OCSP_resp_find , .Nm OCSP_SINGLERESP_get0_id , .Nm OCSP_single_get0_status , .Nm OCSP_check_validity .Nd OCSP response utility functions .Sh SYNOPSIS .In openssl/ocsp.h .Ft OCSP_SINGLERESP * .Fn OCSP_SINGLERESP_new void .Ft void .Fn OCSP_SINGLERESP_free "OCSP_SINGLERESP *single" .Ft OCSP_CERTSTATUS * .Fn OCSP_CERTSTATUS_new void .Ft void .Fn OCSP_CERTSTATUS_free "OCSP_CERTSTATUS *certstatus" .Ft OCSP_REVOKEDINFO * .Fn OCSP_REVOKEDINFO_new void .Ft void .Fn OCSP_REVOKEDINFO_free "OCSP_REVOKEDINFO *revokedinfo" .Ft int .Fo OCSP_resp_find_status .Fa "OCSP_BASICRESP *bs" .Fa "OCSP_CERTID *id" .Fa "int *status" .Fa "int *reason" .Fa "ASN1_GENERALIZEDTIME **revtime" .Fa "ASN1_GENERALIZEDTIME **thisupd" .Fa "ASN1_GENERALIZEDTIME **nextupd" .Fc .Ft int .Fo OCSP_resp_count .Fa "OCSP_BASICRESP *bs" .Fc .Ft OCSP_SINGLERESP * .Fo OCSP_resp_get0 .Fa "OCSP_BASICRESP *bs" .Fa "int idx" .Fc .Ft int .Fo OCSP_resp_find .Fa "OCSP_BASICRESP *bs" .Fa "OCSP_CERTID *id" .Fa "int last" .Fc .Ft const OCSP_CERTID * .Fo OCSP_SINGLERESP_get0_id .Fa "const OCSP_SINGLERESP *single" .Fc .Ft int .Fo OCSP_single_get0_status .Fa "OCSP_SINGLERESP *single" .Fa "int *reason" .Fa "ASN1_GENERALIZEDTIME **revtime" .Fa "ASN1_GENERALIZEDTIME **thisupd" .Fa "ASN1_GENERALIZEDTIME **nextupd" .Fc .Ft int .Fo OCSP_check_validity .Fa "ASN1_GENERALIZEDTIME *thisupd" .Fa "ASN1_GENERALIZEDTIME *nextupd" .Fa "long sec" .Fa "long maxsec" .Fc .Sh DESCRIPTION .Fn OCSP_SINGLERESP_new allocates and initializes an empty .Vt OCSP_SINGLERESP object, representing an ASN.1 .Vt SingleResponse structure defined in RFC 6960. Each such object can store the server's answer regarding the validity of one individual certificate. Such objects are used inside the .Vt OCSP_RESPDATA of .Vt OCSP_BASICRESP objects, which are described in .Xr OCSP_BASICRESP_new 3 . .Fn OCSP_SINGLERESP_free frees .Fa single . .Pp .Fn OCSP_CERTSTATUS_new allocates and initializes an empty .Vt OCSP_CERTSTATUS object, representing an ASN.1 .Vt CertStatus structure defined in RFC 6960. Such an object is used inside .Vt OCSP_SINGLERESP . .Fn OCSP_CERTSTATUS_free frees .Fa certstatus . .Pp .Fn OCSP_REVOKEDINFO_new allocates and initializes an empty .Vt OCSP_REVOKEDINFO object, representing an ASN.1 .Vt RevokedInfo structure defined in RFC 6960. Such an object is used inside .Vt OCSP_CERTSTATUS . .Fn OCSP_REVOKEDINFO_free frees .Fa revokedinfo . .Pp .Fn OCSP_resp_find_status searches .Fa bs for an OCSP response for .Fa id . If it is successful, the fields of the response are returned in .Pf * Fa status , .Pf * Fa reason , .Pf * Fa revtime , .Pf * Fa thisupd and .Pf * Fa nextupd . The .Pf * Fa status value will be one of .Dv V_OCSP_CERTSTATUS_GOOD , .Dv V_OCSP_CERTSTATUS_REVOKED , or .Dv V_OCSP_CERTSTATUS_UNKNOWN . The .Pf * Fa reason and .Pf * Fa revtime fields are only set if the status is .Dv V_OCSP_CERTSTATUS_REVOKED . If set, the .Pf * Fa reason field will be set to the revocation reason which will be one of .Dv OCSP_REVOKED_STATUS_NOSTATUS , .Dv OCSP_REVOKED_STATUS_UNSPECIFIED , .Dv OCSP_REVOKED_STATUS_KEYCOMPROMISE , .Dv OCSP_REVOKED_STATUS_CACOMPROMISE , .Dv OCSP_REVOKED_STATUS_AFFILIATIONCHANGED , .Dv OCSP_REVOKED_STATUS_SUPERSEDED , .Dv OCSP_REVOKED_STATUS_CESSATIONOFOPERATION , .Dv OCSP_REVOKED_STATUS_CERTIFICATEHOLD or .Dv OCSP_REVOKED_STATUS_REMOVEFROMCRL . .Pp .Fn OCSP_resp_count returns the number of .Vt OCSP_SINGLERESP structures in .Fa bs . .Pp .Fn OCSP_resp_get0 returns the .Vt OCSP_SINGLERESP structure in .Fa bs corresponding to index .Fa idx , where .Fa idx runs from 0 to .Fn OCSP_resp_count bs No - 1 . .Pp .Fn OCSP_resp_find searches .Fa bs for .Fa id and returns the index of the first matching entry after .Fa last or starting from the beginning if .Fa last is -1. .Pp .Fn OCSP_single_get0_status extracts the fields of .Fa single in .Pf * Fa reason , .Pf * Fa revtime , .Pf * Fa thisupd , and .Pf * Fa nextupd . .Pp .Fn OCSP_check_validity checks the validity of .Fa thisupd and .Fa nextupd values which will be typically obtained from .Fn OCSP_resp_find_status or .Fn OCSP_single_get0_status . If .Fa sec is non-zero it indicates how many seconds leeway should be allowed in the check. If .Fa maxsec is positive it indicates the maximum age of .Fa thisupd in seconds. .Pp Applications will typically call .Fn OCSP_resp_find_status using the certificate ID of interest and then check its validity using .Fn OCSP_check_validity . They can then take appropriate action based on the status of the certificate. .Pp An OCSP response for a certificate contains .Sy thisUpdate and .Sy nextUpdate fields. Normally the current time should be between these two values. To account for clock skew, the .Fa maxsec field can be set to non-zero in .Fn OCSP_check_validity . Some responders do not set the .Sy nextUpdate field. This would otherwise mean an ancient response would be considered valid: the .Fa maxsec parameter to .Fn OCSP_check_validity can be used to limit the permitted age of responses. .Pp The values written to .Pf * Fa revtime , .Pf * Fa thisupd , and .Pf * Fa nextupd by .Fn OCSP_resp_find_status and .Fn OCSP_single_get0_status are internal pointers which must not be freed up by the calling application. Any or all of these parameters can be set to .Dv NULL if their value is not required. .Sh RETURN VALUES .Fn OCSP_SINGLERESP_new , .Fn OCSP_CERTSTATUS_new , and .Fn OCSP_REVOKEDINFO_new return a pointer to an empty .Vt OCSP_SINGLERESP , .Vt OCSP_CERTSTATUS , or .Vt OCSP_REVOKEDINFO object, respectively, or .Dv NULL if an error occurred. .Pp .Fn OCSP_resp_find_status returns 1 if .Fa id is found in .Fa bs or 0 otherwise. .Pp .Fn OCSP_resp_count returns the total number of .Vt OCSP_SINGLERESP fields in .Fa bs . .Pp .Fn OCSP_resp_get0 returns a pointer to an .Vt OCSP_SINGLERESP structure or .Dv NULL if .Fa idx is out of range. .Pp .Fn OCSP_resp_find returns the index of .Fa id in .Fa bs (which may be 0) or -1 if .Fa id was not found. .Pp .Fn OCSP_SINGLERESP_get0_id returns an internal pointer to the certificate ID object used by .Fa single ; the returned pointer should not be freed by the caller. .Pp .Fn OCSP_single_get0_status returns the status of .Fa single or -1 if an error occurred. .Sh SEE ALSO .Xr OCSP_cert_to_id 3 , .Xr OCSP_CRLID_new 3 , .Xr OCSP_request_add1_nonce 3 , .Xr OCSP_REQUEST_new 3 , .Xr OCSP_response_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 .Sh HISTORY .Fn OCSP_SINGLERESP_new , .Fn OCSP_SINGLERESP_free , .Fn OCSP_CERTSTATUS_new , .Fn OCSP_CERTSTATUS_free , .Fn OCSP_REVOKEDINFO_new , .Fn OCSP_REVOKEDINFO_free , .Fn OCSP_resp_find_status , .Fn OCSP_resp_count , .Fn OCSP_resp_get0 , .Fn OCSP_resp_find , .Fn OCSP_single_get0_status , and .Fn OCSP_check_validity first appeared in OpenSSL 0.9.7 and have been available since .Ox 3.2 . .Pp .Fn OCSP_SINGLERESP_get0_id first appeared in OpenSSL 1.1.0 and has been available since .Ox 6.3 .