NAME
OCSP_SINGLERESP_new,
OCSP_SINGLERESP_free,
OCSP_CERTSTATUS_new,
OCSP_CERTSTATUS_free,
OCSP_REVOKEDINFO_new,
OCSP_REVOKEDINFO_free,
OCSP_resp_find_status,
OCSP_cert_status_str,
OCSP_resp_count,
OCSP_resp_get0,
OCSP_resp_find,
OCSP_SINGLERESP_get0_id,
OCSP_single_get0_status,
OCSP_check_validity,
OCSP_basic_verify —
OCSP response utility
functions
SYNOPSIS
#include
<openssl/ocsp.h>
OCSP_SINGLERESP *
OCSP_SINGLERESP_new(void);
void
OCSP_SINGLERESP_free(OCSP_SINGLERESP
*single);
OCSP_CERTSTATUS *
OCSP_CERTSTATUS_new(void);
void
OCSP_CERTSTATUS_free(OCSP_CERTSTATUS
*certstatus);
OCSP_REVOKEDINFO *
OCSP_REVOKEDINFO_new(void);
void
OCSP_REVOKEDINFO_free(OCSP_REVOKEDINFO
*revokedinfo);
int
OCSP_resp_find_status(OCSP_BASICRESP
*bs, OCSP_CERTID *id, int
*status, int *reason,
ASN1_GENERALIZEDTIME **revtime,
ASN1_GENERALIZEDTIME **thisupd,
ASN1_GENERALIZEDTIME **nextupd);
const char *
OCSP_cert_status_str(long
status);
int
OCSP_resp_count(OCSP_BASICRESP
*bs);
OCSP_SINGLERESP *
OCSP_resp_get0(OCSP_BASICRESP
*bs, int idx);
int
OCSP_resp_find(OCSP_BASICRESP
*bs, OCSP_CERTID *id, int
last);
const OCSP_CERTID *
OCSP_SINGLERESP_get0_id(const
OCSP_SINGLERESP *single);
int
OCSP_single_get0_status(OCSP_SINGLERESP
*single, int *reason,
ASN1_GENERALIZEDTIME **revtime,
ASN1_GENERALIZEDTIME **thisupd,
ASN1_GENERALIZEDTIME **nextupd);
int
OCSP_check_validity(ASN1_GENERALIZEDTIME
*thisupd, ASN1_GENERALIZEDTIME *nextupd,
long sec, long maxsec);
int
OCSP_basic_verify(OCSP_BASICRESP
*bs, STACK_OF(X509) *certs,
X509_STORE *st, unsigned long
flags);
DESCRIPTION
OCSP_SINGLERESP_new()
allocates and initializes an empty OCSP_SINGLERESP
object, representing an ASN.1 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
OCSP_RESPDATA of OCSP_BASICRESP
objects, which are described in
OCSP_BASICRESP_new(3).
OCSP_SINGLERESP_free()
frees single.
OCSP_CERTSTATUS_new()
allocates and initializes an empty OCSP_CERTSTATUS
object, representing an ASN.1 CertStatus structure
defined in RFC 6960. Such an object is used inside
OCSP_SINGLERESP.
OCSP_CERTSTATUS_free()
frees certstatus.
OCSP_REVOKEDINFO_new()
allocates and initializes an empty OCSP_REVOKEDINFO
object, representing an ASN.1 RevokedInfo structure
defined in RFC 6960. Such an object is used inside
OCSP_CERTSTATUS.
OCSP_REVOKEDINFO_free()
frees revokedinfo.
OCSP_resp_find_status()
searches bs for an OCSP response for
id. If it is successful, the fields of the response
are returned in *status,
*reason, *revtime,
*thisupd and *nextupd. The
*status value will be one of
V_OCSP_CERTSTATUS_GOOD,
V_OCSP_CERTSTATUS_REVOKED, or
V_OCSP_CERTSTATUS_UNKNOWN. The
*reason and *revtime fields are
only set if the status is V_OCSP_CERTSTATUS_REVOKED.
If set, the *reason field will be set to the
revocation reason which will be one of
OCSP_REVOKED_STATUS_NOSTATUS,
OCSP_REVOKED_STATUS_UNSPECIFIED,
OCSP_REVOKED_STATUS_KEYCOMPROMISE,
OCSP_REVOKED_STATUS_CACOMPROMISE,
OCSP_REVOKED_STATUS_AFFILIATIONCHANGED,
OCSP_REVOKED_STATUS_SUPERSEDED,
OCSP_REVOKED_STATUS_CESSATIONOFOPERATION,
OCSP_REVOKED_STATUS_CERTIFICATEHOLD or
OCSP_REVOKED_STATUS_REMOVEFROMCRL.
OCSP_cert_status_str()
converts one of the status codes retrieved by
OCSP_resp_find_status() to a string consisting of
one word.
OCSP_resp_count()
returns the number of OCSP_SINGLERESP structures in
bs.
OCSP_resp_get0()
returns the OCSP_SINGLERESP structure in
bs corresponding to index idx,
where idx runs from 0 to
OCSP_resp_count(bs)
- 1.
OCSP_resp_find()
searches bs for id and returns
the index of the first matching entry after last or
starting from the beginning if last is -1.
OCSP_single_get0_status()
extracts the fields of single in
*reason, *revtime,
*thisupd, and *nextupd.
OCSP_check_validity()
checks the validity of thisupd and
nextupd values which will be typically obtained from
OCSP_resp_find_status() or
OCSP_single_get0_status(). If
sec is non-zero it indicates how many seconds leeway
should be allowed in the check. If maxsec is positive
it indicates the maximum age of thisupd in
seconds.
Applications will typically call
OCSP_resp_find_status()
using the certificate ID of interest and then check its validity using
OCSP_check_validity(). They can then take
appropriate action based on the status of the certificate.
An OCSP response for a certificate contains
thisUpdate and
nextUpdate fields. Normally the current time should be
between these two values. To account for clock skew, the
maxsec field can be set to non-zero in
OCSP_check_validity().
Some responders do not set the nextUpdate field. This
would otherwise mean an ancient response would be considered valid: the
maxsec parameter to
OCSP_check_validity() can be used to limit the
permitted age of responses.
The values written to
*revtime, *thisupd, and
*nextupd by
OCSP_resp_find_status()
and 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 NULL if their value is not
required.
OCSP_basic_verify()
checks that the basic response message bs is correctly
signed and that the signer certificate can be validated. It takes
st as the trusted store and
certs as a set of untrusted intermediate certificates.
The function first tries to find the signer certificate of the response in
certs. It also searches the certificates the responder
may have included in bs unless the
flags contain OCSP_NOINTERN.
It fails if the signer certificate cannot be found. Next, the function
checks the signature of bs and fails on error unless
the flags contain OCSP_NOSIGS.
Then the function already returns success if the flags
contain OCSP_NOVERIFY or if the signer certificate
was found in certs and the flags
contain OCSP_TRUSTOTHER. Otherwise the function
continues by validating the signer certificate. To this end, all
certificates in certs and in bs
are considered as untrusted certificates for the construction of the
validation path for the signer certificate unless the
OCSP_NOCHAIN flag is set. After successful path
validation, the function returns success if the
OCSP_NOCHECKS flag is set. Otherwise it verifies
that the signer certificate meets the OCSP issuer criteria including
potential delegation. If this does not succeed and the
flags do not contain
OCSP_NOEXPLICIT, the function checks for explicit
trust for OCSP signing in the root CA certificate.
RETURN VALUES
OCSP_SINGLERESP_new(),
OCSP_CERTSTATUS_new(), and
OCSP_REVOKEDINFO_new() return a pointer to an empty
OCSP_SINGLERESP,
OCSP_CERTSTATUS, or
OCSP_REVOKEDINFO object, respectively, or
NULL if an error occurred.
OCSP_resp_find_status() returns 1 if
id is found in bs or 0
otherwise.
OCSP_cert_status_str() returns a pointer
to a static string.
OCSP_resp_count() returns the total number
of OCSP_SINGLERESP fields in
bs.
OCSP_resp_get0() returns a pointer to an
OCSP_SINGLERESP structure or
NULL if idx is out of
range.
OCSP_resp_find() returns the index of
id in bs (which may be 0) or -1
if id was not found.
OCSP_SINGLERESP_get0_id() returns an
internal pointer to the certificate ID object used by
single; the returned pointer should not be freed by
the caller.
OCSP_single_get0_status() returns the
status of single or -1 if an error occurred.
OCSP_basic_verify() returns 1 on success,
0 on error, or -1 on fatal error such as malloc failure.
SEE ALSO
OCSP_cert_to_id(3), OCSP_CRLID_new(3), OCSP_request_add1_nonce(3), OCSP_REQUEST_new(3), OCSP_response_status(3), OCSP_sendreq_new(3)
STANDARDS
RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate Status Protocol, section 4.2: Response Syntax
HISTORY
OCSP_SINGLERESP_new(),
OCSP_SINGLERESP_free(),
OCSP_CERTSTATUS_new(),
OCSP_CERTSTATUS_free(),
OCSP_REVOKEDINFO_new(),
OCSP_REVOKEDINFO_free(),
OCSP_resp_find_status(),
OCSP_cert_status_str(),
OCSP_resp_count(),
OCSP_resp_get0(),
OCSP_resp_find(),
OCSP_single_get0_status(), and
OCSP_check_validity() first appeared in OpenSSL
0.9.7 and have been available since OpenBSD 3.2.
OCSP_SINGLERESP_get0_id() first appeared
in OpenSSL 1.1.0 and has been available since OpenBSD
6.3.