| Current Path : /usr/opt/openssl11/share/doc/openssl/html/man3/ |
FreeBSD hs32.drive.ne.jp 9.1-RELEASE FreeBSD 9.1-RELEASE #1: Wed Jan 14 12:18:08 JST 2015 root@hs32.drive.ne.jp:/sys/amd64/compile/hs32 amd64 |
| Current File : //usr/opt/openssl11/share/doc/openssl/html/man3/OCSP_resp_get0.html |
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>OCSP_resp_find_status</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@hsxx.drive.ne.jp" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#return_values">RETURN VALUES</a></li>
<li><a href="#notes">NOTES</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p>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</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
#include <openssl/ocsp.h></pre>
<pre>
int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status,
int *reason,
ASN1_GENERALIZEDTIME **revtime,
ASN1_GENERALIZEDTIME **thisupd,
ASN1_GENERALIZEDTIME **nextupd);</pre>
<pre>
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);</pre>
<pre>
const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at(
const OCSP_BASICRESP* single);</pre>
<pre>
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);</pre>
<pre>
int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer,
STACK_OF(X509) *extra_certs);</pre>
<pre>
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);</pre>
<pre>
int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd,
ASN1_GENERALIZEDTIME *nextupd,
long sec, long maxsec);</pre>
<pre>
int OCSP_basic_verify(OCSP_BASICRESP *bs, STACK_OF(X509) *certs,
X509_STORE *st, unsigned long flags);</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><code>OCSP_resp_find_status()</code> searches <strong>bs</strong> for an OCSP response for <strong>id</strong>. If it is
successful the fields of the response are returned in <strong>*status</strong>, <strong>*reason</strong>,
<strong>*revtime</strong>, <strong>*thisupd</strong> and <strong>*nextupd</strong>. The <strong>*status</strong> value will be one of
<strong>V_OCSP_CERTSTATUS_GOOD</strong>, <strong>V_OCSP_CERTSTATUS_REVOKED</strong> or
<strong>V_OCSP_CERTSTATUS_UNKNOWN</strong>. The <strong>*reason</strong> and <strong>*revtime</strong> fields are only
set if the status is <strong>V_OCSP_CERTSTATUS_REVOKED</strong>. If set the <strong>*reason</strong> field
will be set to the revocation reason which will be one of
<strong>OCSP_REVOKED_STATUS_NOSTATUS</strong>, <strong>OCSP_REVOKED_STATUS_UNSPECIFIED</strong>,
<strong>OCSP_REVOKED_STATUS_KEYCOMPROMISE</strong>, <strong>OCSP_REVOKED_STATUS_CACOMPROMISE</strong>,
<strong>OCSP_REVOKED_STATUS_AFFILIATIONCHANGED</strong>, <strong>OCSP_REVOKED_STATUS_SUPERSEDED</strong>,
<strong>OCSP_REVOKED_STATUS_CESSATIONOFOPERATION</strong>,
<strong>OCSP_REVOKED_STATUS_CERTIFICATEHOLD</strong> or <strong>OCSP_REVOKED_STATUS_REMOVEFROMCRL</strong>.</p>
<p><code>OCSP_resp_count()</code> returns the number of <strong>OCSP_SINGLERESP</strong> structures in <strong>bs</strong>.</p>
<p>OCSP_resp_get0() returns the <strong>OCSP_SINGLERESP</strong> structure in <strong>bs</strong>
corresponding to index <strong>idx</strong>. Where <strong>idx</strong> runs from 0 to
OCSP_resp_count(bs) - 1.</p>
<p><code>OCSP_resp_find()</code> searches <strong>bs</strong> for <strong>id</strong> and returns the index of the first
matching entry after <strong>last</strong> or starting from the beginning if <strong>last</strong> is -1.</p>
<p>OCSP_single_get0_status() extracts the fields of <strong>single</strong> in <strong>*reason</strong>,
<strong>*revtime</strong>, <strong>*thisupd</strong> and <strong>*nextupd</strong>.</p>
<p>OCSP_resp_get0_produced_at() extracts the <strong>producedAt</strong> field from the
single response <strong>bs</strong>.</p>
<p>OCSP_resp_get0_signature() returns the signature from <strong>bs</strong>.</p>
<p>OCSP_resp_get0_tbs_sigalg() returns the <strong>signatureAlgorithm</strong> from <strong>bs</strong>.</p>
<p>OCSP_resp_get0_respdata() returns the <strong>tbsResponseData</strong> from <strong>bs</strong>.</p>
<p>OCSP_resp_get0_certs() returns any certificates included in <strong>bs</strong>.</p>
<p>OCSP_resp_get0_signer() attempts to retrieve the certificate that directly
signed <strong>bs</strong>. The OCSP protocol does not require that this certificate
is included in the <strong>certs</strong> field of the response, so additional certificates
can be supplied in <strong>extra_certs</strong> if the certificates that may have
signed the response are known via some out-of-band mechanism.</p>
<p>OCSP_resp_get0_id() gets the responder id of <strong>bs</strong>. If the responder ID is
a name then <*pname> is set to the name and <strong>*pid</strong> is set to NULL. If the
responder ID is by key ID then <strong>*pid</strong> is set to the key ID and <strong>*pname</strong>
is set to NULL. OCSP_resp_get1_id() leaves ownership of <strong>*pid</strong> and <strong>*pname</strong>
with the caller, who is responsible for freeing them. Both functions return 1
in case of success and 0 in case of failure. If OCSP_resp_get1_id() returns 0,
no freeing of the results is necessary.</p>
<p><code>OCSP_check_validity()</code> checks the validity of <strong>thisupd</strong> and <strong>nextupd</strong> values
which will be typically obtained from <code>OCSP_resp_find_status()</code> or
OCSP_single_get0_status(). If <strong>sec</strong> is nonzero it indicates how many seconds
leeway should be allowed in the check. If <strong>maxsec</strong> is positive it indicates
the maximum age of <strong>thisupd</strong> in seconds.</p>
<p><code>OCSP_basic_verify()</code> checks that the basic response message <strong>bs</strong> is correctly
signed and that the signer certificate can be validated. It takes <strong>st</strong> as
the trusted store and <strong>certs</strong> 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 <strong>bs</strong> unless the <strong>flags</strong> contain <strong>OCSP_NOINTERN</strong>.
It fails if the signer certificate cannot be found.
Next, the function checks the signature of <strong>bs</strong> and fails on error
unless the <strong>flags</strong> contain <strong>OCSP_NOSIGS</strong>. Then the function already returns
success if the <strong>flags</strong> contain <strong>OCSP_NOVERIFY</strong> or if the signer certificate
was found in <strong>certs</strong> and the <strong>flags</strong> contain <strong>OCSP_TRUSTOTHER</strong>.
Otherwise the function continues by validating the signer certificate.
To this end, all certificates in <strong>cert</strong> and in <strong>bs</strong> are considered as
untrusted certificates for the construction of the validation path for the
signer certificate unless the <strong>OCSP_NOCHAIN</strong> flag is set. After successful path
validation the function returns success if the <strong>OCSP_NOCHECKS</strong> 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
<strong>flags</strong> do not contain <strong>OCSP_NOEXPLICIT</strong> the function checks for explicit
trust for OCSP signing in the root CA certificate.</p>
<p>
</p>
<hr />
<h1><a name="return_values">RETURN VALUES</a></h1>
<p><code>OCSP_resp_find_status()</code> returns 1 if <strong>id</strong> is found in <strong>bs</strong> and 0 otherwise.</p>
<p><code>OCSP_resp_count()</code> returns the total number of <strong>OCSP_SINGLERESP</strong> fields in
<strong>bs</strong>.</p>
<p>OCSP_resp_get0() returns a pointer to an <strong>OCSP_SINGLERESP</strong> structure or
<strong>NULL</strong> if <strong>idx</strong> is out of range.</p>
<p><code>OCSP_resp_find()</code> returns the index of <strong>id</strong> in <strong>bs</strong> (which may be 0) or -1 if
<strong>id</strong> was not found.</p>
<p>OCSP_single_get0_status() returns the status of <strong>single</strong> or -1 if an error
occurred.</p>
<p>OCSP_resp_get0_signer() returns 1 if the signing certificate was located,
or 0 on error.</p>
<p><code>OCSP_basic_verify()</code> returns 1 on success, 0 on error, or -1 on fatal error such
as malloc failure.</p>
<p>
</p>
<hr />
<h1><a name="notes">NOTES</a></h1>
<p>Applications will typically call <code>OCSP_resp_find_status()</code> using the certificate
ID of interest and then check its validity using <code>OCSP_check_validity()</code>. They
can then take appropriate action based on the status of the certificate.</p>
<p>An OCSP response for a certificate contains <strong>thisUpdate</strong> and <strong>nextUpdate</strong>
fields. Normally the current time should be between these two values. To
account for clock skew the <strong>maxsec</strong> field can be set to nonzero in
<code>OCSP_check_validity()</code>. Some responders do not set the <strong>nextUpdate</strong> field, this
would otherwise mean an ancient response would be considered valid: the
<strong>maxsec</strong> parameter to <code>OCSP_check_validity()</code> can be used to limit the permitted
age of responses.</p>
<p>The values written to <strong>*revtime</strong>, <strong>*thisupd</strong> and <strong>*nextupd</strong> by
<code>OCSP_resp_find_status()</code> and OCSP_single_get0_status() are internal pointers
which <strong>MUST NOT</strong> be freed up by the calling application. Any or all of these
parameters can be set to NULL if their value is not required.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><em>crypto(7)</em>,
<em>OCSP_cert_to_id(3)</em>,
<em>OCSP_request_add1_nonce(3)</em>,
<em>OCSP_REQUEST_new(3)</em>,
<em>OCSP_response_status(3)</em>,
<em>OCSP_sendreq_new(3)</em></p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2015-2020 The OpenSSL Project Authors. All Rights Reserved.</p>
<p>Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
</body>
</html>