1=pod 2 3=head1 NAME 4 5OCSP_resp_find_status, OCSP_resp_count, 6OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status, 7OCSP_resp_get0_produced_at, OCSP_resp_get0_signature, 8OCSP_resp_get0_tbs_sigalg, OCSP_resp_get0_respdata, 9OCSP_resp_get0_certs, OCSP_resp_get0_signer, 10OCSP_resp_get0_id, OCSP_resp_get1_id, 11OCSP_check_validity, OCSP_basic_verify 12- OCSP response utility functions 13 14=head1 SYNOPSIS 15 16 #include <openssl/ocsp.h> 17 18 int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status, 19 int *reason, 20 ASN1_GENERALIZEDTIME **revtime, 21 ASN1_GENERALIZEDTIME **thisupd, 22 ASN1_GENERALIZEDTIME **nextupd); 23 24 int OCSP_resp_count(OCSP_BASICRESP *bs); 25 OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx); 26 int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last); 27 int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason, 28 ASN1_GENERALIZEDTIME **revtime, 29 ASN1_GENERALIZEDTIME **thisupd, 30 ASN1_GENERALIZEDTIME **nextupd); 31 32 const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at( 33 const OCSP_BASICRESP* single); 34 35 const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs); 36 const X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs); 37 const OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs); 38 const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs); 39 40 int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer, 41 STACK_OF(X509) *extra_certs); 42 43 int OCSP_resp_get0_id(const OCSP_BASICRESP *bs, 44 const ASN1_OCTET_STRING **pid, 45 const X509_NAME **pname); 46 int OCSP_resp_get1_id(const OCSP_BASICRESP *bs, 47 ASN1_OCTET_STRING **pid, 48 X509_NAME **pname); 49 50 int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd, 51 ASN1_GENERALIZEDTIME *nextupd, 52 long sec, long maxsec); 53 54 int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs, 55 X509_STORE *st, unsigned long flags); 56 57=head1 DESCRIPTION 58 59OCSP_resp_find_status() searches I<bs> for an OCSP response for I<id>. If it is 60successful the fields of the response are returned in I<*status>, I<*reason>, 61I<*revtime>, I<*thisupd> and I<*nextupd>. The I<*status> value will be one of 62B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or 63B<V_OCSP_CERTSTATUS_UNKNOWN>. The I<*reason> and I<*revtime> fields are only 64set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the I<*reason> field 65will be set to the revocation reason which will be one of 66B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>, 67B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>, 68B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>, 69B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>, 70B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>. 71 72OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in I<bs>. 73 74OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in I<bs> corresponding 75to index I<idx>, where I<idx> runs from 0 to OCSP_resp_count(bs) - 1. 76 77OCSP_resp_find() searches I<bs> for I<id> and returns the index of the first 78matching entry after I<last> or starting from the beginning if I<last> is -1. 79 80OCSP_single_get0_status() extracts the fields of I<single> in I<*reason>, 81I<*revtime>, I<*thisupd> and I<*nextupd>. 82 83OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the 84single response I<bs>. 85 86OCSP_resp_get0_signature() returns the signature from I<bs>. 87 88OCSP_resp_get0_tbs_sigalg() returns the B<signatureAlgorithm> from I<bs>. 89 90OCSP_resp_get0_respdata() returns the B<tbsResponseData> from I<bs>. 91 92OCSP_resp_get0_certs() returns any certificates included in I<bs>. 93 94OCSP_resp_get0_signer() attempts to retrieve the certificate that directly 95signed I<bs>. The OCSP protocol does not require that this certificate 96is included in the B<certs> field of the response, so additional certificates 97can be supplied via the I<extra_certs> if the certificates that may have 98signed the response are known via some out-of-band mechanism. 99 100OCSP_resp_get0_id() gets the responder id of I<bs>. If the responder ID is 101a name then <*pname> is set to the name and I<*pid> is set to NULL. If the 102responder ID is by key ID then I<*pid> is set to the key ID and I<*pname> 103is set to NULL. 104 105OCSP_resp_get1_id() is the same as OCSP_resp_get0_id() 106but leaves ownership of I<*pid> and I<*pname> with the caller, 107who is responsible for freeing them unless the function returns 0. 108 109OCSP_check_validity() checks the validity of its I<thisupd> and I<nextupd> 110arguments, which will be typically obtained from OCSP_resp_find_status() or 111OCSP_single_get0_status(). If I<sec> is nonzero it indicates how many seconds 112leeway should be allowed in the check. If I<maxsec> is positive it indicates 113the maximum age of I<thisupd> in seconds. 114 115OCSP_basic_verify() checks that the basic response message I<bs> is correctly 116signed and that the signer certificate can be validated. It takes I<st> as 117the trusted store and I<certs> as a set of untrusted intermediate certificates. 118The function first tries to find the signer certificate of the response 119in I<certs>. It then searches the certificates the responder may have included 120in I<bs> unless I<flags> contains B<OCSP_NOINTERN>. 121It fails if the signer certificate cannot be found. 122Next, unless I<flags> contains B<OCSP_NOSIGS>, the function checks 123the signature of I<bs> and fails on error. Then the function already returns 124success if I<flags> contains B<OCSP_NOVERIFY> or if the signer certificate 125was found in I<certs> and I<flags> contains B<OCSP_TRUSTOTHER>. 126Otherwise the function continues by validating the signer certificate. 127If I<flags> contains B<OCSP_PARTIAL_CHAIN> it takes intermediate CA 128certificates in I<st> as trust anchors. 129For more details, see the description of B<X509_V_FLAG_PARTIAL_CHAIN> 130in L<X509_VERIFY_PARAM_set_flags(3)/VERIFICATION FLAGS>. 131If I<flags> contains B<OCSP_NOCHAIN> it ignores all certificates in I<certs> 132and in I<bs>, else it takes them as untrusted intermediate CA certificates 133and uses them for constructing the validation path for the signer certificate. 134Certificate revocation status checks using CRLs is disabled during path validation 135if the signer certificate contains the B<id-pkix-ocsp-no-check> extension. 136After successful path 137validation the function returns success if the B<OCSP_NOCHECKS> flag is set. 138Otherwise it verifies that the signer certificate meets the OCSP issuer 139criteria including potential delegation. If this does not succeed and the 140B<OCSP_NOEXPLICIT> flag is not set the function checks for explicit 141trust for OCSP signing in the root CA certificate. 142 143=head1 RETURN VALUES 144 145OCSP_resp_find_status() returns 1 if I<id> is found in I<bs> and 0 otherwise. 146 147OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in I<bs> 148or -1 on error. 149 150OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or 151NULL on error, such as I<idx> being out of range. 152 153OCSP_resp_find() returns the index of I<id> in I<bs> (which may be 0) 154or -1 on error, such as when I<id> was not found. 155 156OCSP_single_get0_status() returns the status of I<single> or -1 if an error 157occurred. 158 159OCSP_resp_get0_produced_at() returns the B<producedAt> field from I<bs>. 160 161OCSP_resp_get0_signature() returns the signature from I<bs>. 162 163OCSP_resp_get0_tbs_sigalg() returns the B<signatureAlgorithm> field from I<bs>. 164 165OCSP_resp_get0_respdata() returns the B<tbsResponseData> field from I<bs>. 166 167OCSP_resp_get0_certs() returns any certificates included in I<bs>. 168 169OCSP_resp_get0_signer() returns 1 if the signing certificate was located, 170or 0 if not found or on error. 171 172OCSP_resp_get0_id() and OCSP_resp_get1_id() return 1 on success, 0 on failure. 173 174OCSP_check_validity() returns 1 if I<thisupd> and I<nextupd> are valid time 175values and the current time + I<sec> is not before I<thisupd> and, 176if I<maxsec> >= 0, the current time - I<maxsec> is not past I<nextupd>. 177Otherwise it returns 0 to indicate an error. 178 179OCSP_basic_verify() returns 1 on success, 0 on verification not successful, 180or -1 on a fatal error such as malloc failure. 181 182=head1 NOTES 183 184Applications will typically call OCSP_resp_find_status() using the certificate 185ID of interest and then check its validity using OCSP_check_validity(). They 186can then take appropriate action based on the status of the certificate. 187 188An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate> 189fields. Normally the current time should be between these two values. To 190account for clock skew the I<maxsec> field can be set to nonzero in 191OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this 192would otherwise mean an ancient response would be considered valid: the 193I<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted 194age of responses. 195 196The values written to I<*revtime>, I<*thisupd> and I<*nextupd> by 197OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers 198which MUST NOT be freed up by the calling application. Any or all of these 199parameters can be set to NULL if their value is not required. 200 201=head1 SEE ALSO 202 203L<crypto(7)>, 204L<OCSP_cert_to_id(3)>, 205L<OCSP_request_add1_nonce(3)>, 206L<OCSP_REQUEST_new(3)>, 207L<OCSP_response_status(3)>, 208L<OCSP_sendreq_new(3)>, 209L<X509_VERIFY_PARAM_set_flags(3)> 210 211=head1 COPYRIGHT 212 213Copyright 2015-2023 The OpenSSL Project Authors. All Rights Reserved. 214 215Licensed under the Apache License 2.0 (the "License"). You may not use 216this file except in compliance with the License. You can obtain a copy 217in the file LICENSE in the source distribution or at 218L<https://www.openssl.org/source/license.html>. 219 220=cut 221