311 lines
13 KiB
Groff
Executable File
311 lines
13 KiB
Groff
Executable File
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.ie \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.el \{\
|
|
. de IX
|
|
..
|
|
.\}
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "OCSP_RESP_FIND_STATUS 3"
|
|
.TH OCSP_RESP_FIND_STATUS 3 "2020-03-02" "1.1.1e-dev" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
OCSP_resp_get0_certs, OCSP_resp_get0_signer, OCSP_resp_get0_id, OCSP_resp_get1_id, OCSP_resp_get0_produced_at, OCSP_resp_get0_signature, OCSP_resp_get0_tbs_sigalg, OCSP_resp_get0_respdata, OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find, OCSP_single_get0_status, OCSP_check_validity, OCSP_basic_verify \&\- OCSP response utility functions
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/ocsp.h>
|
|
\&
|
|
\& int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
|
|
\& int *reason,
|
|
\& ASN1_GENERALIZEDTIME **revtime,
|
|
\& ASN1_GENERALIZEDTIME **thisupd,
|
|
\& ASN1_GENERALIZEDTIME **nextupd);
|
|
\&
|
|
\& 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);
|
|
\& int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason,
|
|
\& ASN1_GENERALIZEDTIME **revtime,
|
|
\& ASN1_GENERALIZEDTIME **thisupd,
|
|
\& ASN1_GENERALIZEDTIME **nextupd);
|
|
\&
|
|
\& const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
|
|
\& const OCSP_BASICRESP* single);
|
|
\&
|
|
\& const ASN1_OCTET_STRING *OCSP_resp_get0_signature(const OCSP_BASICRESP *bs);
|
|
\& const X509_ALGOR *OCSP_resp_get0_tbs_sigalg(const OCSP_BASICRESP *bs);
|
|
\& const OCSP_RESPDATA *OCSP_resp_get0_respdata(const OCSP_BASICRESP *bs);
|
|
\& const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs);
|
|
\&
|
|
\& int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer,
|
|
\& STACK_OF(X509) *extra_certs);
|
|
\&
|
|
\& int OCSP_resp_get0_id(const OCSP_BASICRESP *bs,
|
|
\& const ASN1_OCTET_STRING **pid,
|
|
\& const X509_NAME **pname);
|
|
\& int OCSP_resp_get1_id(const OCSP_BASICRESP *bs,
|
|
\& ASN1_OCTET_STRING **pid,
|
|
\& X509_NAME **pname);
|
|
\&
|
|
\& 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);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fIOCSP_resp_find_status()\fR searches \fBbs\fR for an \s-1OCSP\s0 response for \fBid\fR. If it is
|
|
successful the fields of the response are returned in \fB*status\fR, \fB*reason\fR,
|
|
\&\fB*revtime\fR, \fB*thisupd\fR and \fB*nextupd\fR. The \fB*status\fR value will be one of
|
|
\&\fBV_OCSP_CERTSTATUS_GOOD\fR, \fBV_OCSP_CERTSTATUS_REVOKED\fR or
|
|
\&\fBV_OCSP_CERTSTATUS_UNKNOWN\fR. The \fB*reason\fR and \fB*revtime\fR fields are only
|
|
set if the status is \fBV_OCSP_CERTSTATUS_REVOKED\fR. If set the \fB*reason\fR field
|
|
will be set to the revocation reason which will be one of
|
|
\&\fB\s-1OCSP_REVOKED_STATUS_NOSTATUS\s0\fR, \fB\s-1OCSP_REVOKED_STATUS_UNSPECIFIED\s0\fR,
|
|
\&\fB\s-1OCSP_REVOKED_STATUS_KEYCOMPROMISE\s0\fR, \fB\s-1OCSP_REVOKED_STATUS_CACOMPROMISE\s0\fR,
|
|
\&\fB\s-1OCSP_REVOKED_STATUS_AFFILIATIONCHANGED\s0\fR, \fB\s-1OCSP_REVOKED_STATUS_SUPERSEDED\s0\fR,
|
|
\&\fB\s-1OCSP_REVOKED_STATUS_CESSATIONOFOPERATION\s0\fR,
|
|
\&\fB\s-1OCSP_REVOKED_STATUS_CERTIFICATEHOLD\s0\fR or \fB\s-1OCSP_REVOKED_STATUS_REMOVEFROMCRL\s0\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_count()\fR returns the number of \fB\s-1OCSP_SINGLERESP\s0\fR structures in \fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0()\fR returns the \fB\s-1OCSP_SINGLERESP\s0\fR structure in \fBbs\fR
|
|
corresponding to index \fBidx\fR. Where \fBidx\fR runs from 0 to
|
|
OCSP_resp_count(bs) \- 1.
|
|
.PP
|
|
\&\fIOCSP_resp_find()\fR searches \fBbs\fR for \fBid\fR and returns the index of the first
|
|
matching entry after \fBlast\fR or starting from the beginning if \fBlast\fR is \-1.
|
|
.PP
|
|
\&\fIOCSP_single_get0_status()\fR extracts the fields of \fBsingle\fR in \fB*reason\fR,
|
|
\&\fB*revtime\fR, \fB*thisupd\fR and \fB*nextupd\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_produced_at()\fR extracts the \fBproducedAt\fR field from the
|
|
single response \fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_signature()\fR returns the signature from \fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_tbs_sigalg()\fR returns the \fBsignatureAlgorithm\fR from \fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_respdata()\fR returns the \fBtbsResponseData\fR from \fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_certs()\fR returns any certificates included in \fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_signer()\fR attempts to retrieve the certificate that directly
|
|
signed \fBbs\fR. The \s-1OCSP\s0 protocol does not require that this certificate
|
|
is included in the \fBcerts\fR field of the response, so additional certificates
|
|
can be supplied in \fBextra_certs\fR if the certificates that may have
|
|
signed the response are known via some out-of-band mechanism.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_id()\fR gets the responder id of \fBbs\fR. If the responder \s-1ID\s0 is
|
|
a name then <*pname> is set to the name and \fB*pid\fR is set to \s-1NULL\s0. If the
|
|
responder \s-1ID\s0 is by key \s-1ID\s0 then \fB*pid\fR is set to the key \s-1ID\s0 and \fB*pname\fR
|
|
is set to \s-1NULL\s0. \fIOCSP_resp_get1_id()\fR leaves ownership of \fB*pid\fR and \fB*pname\fR
|
|
with the caller, who is responsible for freeing them. Both functions return 1
|
|
in case of success and 0 in case of failure. If \fIOCSP_resp_get1_id()\fR returns 0,
|
|
no freeing of the results is necessary.
|
|
.PP
|
|
\&\fIOCSP_check_validity()\fR checks the validity of \fBthisupd\fR and \fBnextupd\fR values
|
|
which will be typically obtained from \fIOCSP_resp_find_status()\fR or
|
|
\&\fIOCSP_single_get0_status()\fR. If \fBsec\fR is non-zero it indicates how many seconds
|
|
leeway should be allowed in the check. If \fBmaxsec\fR is positive it indicates
|
|
the maximum age of \fBthisupd\fR in seconds.
|
|
.PP
|
|
\&\fIOCSP_basic_verify()\fR checks that the basic response message \fBbs\fR is correctly
|
|
signed and that the signer certificate can be validated. It takes \fBst\fR as
|
|
the trusted store and \fBcerts\fR 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 \fBbs\fR unless the \fBflags\fR contain \fB\s-1OCSP_NOINTERN\s0\fR.
|
|
It fails if the signer certificate cannot be found.
|
|
Next, the function checks the signature of \fBbs\fR and fails on error
|
|
unless the \fBflags\fR contain \fB\s-1OCSP_NOSIGS\s0\fR. Then the function already returns
|
|
success if the \fBflags\fR contain \fB\s-1OCSP_NOVERIFY\s0\fR or if the signer certificate
|
|
was found in \fBcerts\fR and the \fBflags\fR contain \fB\s-1OCSP_TRUSTOTHER\s0\fR.
|
|
Otherwise the function continues by validating the signer certificate.
|
|
To this end, all certificates in \fBcert\fR and in \fBbs\fR are considered as
|
|
untrusted certificates for the construction of the validation path for the
|
|
signer certificate unless the \fB\s-1OCSP_NOCHAIN\s0\fR flag is set. After successful path
|
|
validation the function returns success if the \fB\s-1OCSP_NOCHECKS\s0\fR flag is set.
|
|
Otherwise it verifies that the signer certificate meets the \s-1OCSP\s0 issuer
|
|
criteria including potential delegation. If this does not succeed and the
|
|
\&\fBflags\fR do not contain \fB\s-1OCSP_NOEXPLICIT\s0\fR the function checks for explicit
|
|
trust for \s-1OCSP\s0 signing in the root \s-1CA\s0 certificate.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fIOCSP_resp_find_status()\fR returns 1 if \fBid\fR is found in \fBbs\fR and 0 otherwise.
|
|
.PP
|
|
\&\fIOCSP_resp_count()\fR returns the total number of \fB\s-1OCSP_SINGLERESP\s0\fR fields in
|
|
\&\fBbs\fR.
|
|
.PP
|
|
\&\fIOCSP_resp_get0()\fR returns a pointer to an \fB\s-1OCSP_SINGLERESP\s0\fR structure or
|
|
\&\fB\s-1NULL\s0\fR if \fBidx\fR is out of range.
|
|
.PP
|
|
\&\fIOCSP_resp_find()\fR returns the index of \fBid\fR in \fBbs\fR (which may be 0) or \-1 if
|
|
\&\fBid\fR was not found.
|
|
.PP
|
|
\&\fIOCSP_single_get0_status()\fR returns the status of \fBsingle\fR or \-1 if an error
|
|
occurred.
|
|
.PP
|
|
\&\fIOCSP_resp_get0_signer()\fR returns 1 if the signing certificate was located,
|
|
or 0 on error.
|
|
.PP
|
|
\&\fIOCSP_basic_verify()\fR returns 1 on success, 0 on error, or \-1 on fatal error such
|
|
as malloc failure.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
Applications will typically call \fIOCSP_resp_find_status()\fR using the certificate
|
|
\&\s-1ID\s0 of interest and then check its validity using \fIOCSP_check_validity()\fR. They
|
|
can then take appropriate action based on the status of the certificate.
|
|
.PP
|
|
An \s-1OCSP\s0 response for a certificate contains \fBthisUpdate\fR and \fBnextUpdate\fR
|
|
fields. Normally the current time should be between these two values. To
|
|
account for clock skew the \fBmaxsec\fR field can be set to non-zero in
|
|
\&\fIOCSP_check_validity()\fR. Some responders do not set the \fBnextUpdate\fR field, this
|
|
would otherwise mean an ancient response would be considered valid: the
|
|
\&\fBmaxsec\fR parameter to \fIOCSP_check_validity()\fR can be used to limit the permitted
|
|
age of responses.
|
|
.PP
|
|
The values written to \fB*revtime\fR, \fB*thisupd\fR and \fB*nextupd\fR by
|
|
\&\fIOCSP_resp_find_status()\fR and \fIOCSP_single_get0_status()\fR are internal pointers
|
|
which \fB\s-1MUST\s0 \s-1NOT\s0\fR be freed up by the calling application. Any or all of these
|
|
parameters can be set to \s-1NULL\s0 if their value is not required.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIcrypto\fR\|(7),
|
|
\&\fIOCSP_cert_to_id\fR\|(3),
|
|
\&\fIOCSP_request_add1_nonce\fR\|(3),
|
|
\&\fIOCSP_REQUEST_new\fR\|(3),
|
|
\&\fIOCSP_response_status\fR\|(3),
|
|
\&\fIOCSP_sendreq_new\fR\|(3)
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|