| 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/X509_STORE_CTX_set_verify_cb.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>X509_STORE_CTX_set_verify_cb</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="#warnings">WARNINGS</a></li>
<li><a href="#notes">NOTES</a></li>
<li><a href="#return_values">RETURN VALUES</a></li>
<li><a href="#examples">EXAMPLES</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#history">HISTORY</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>X509_STORE_CTX_get_cleanup,
X509_STORE_CTX_get_lookup_crls,
X509_STORE_CTX_get_lookup_certs,
X509_STORE_CTX_get_check_policy,
X509_STORE_CTX_get_cert_crl,
X509_STORE_CTX_get_check_crl,
X509_STORE_CTX_get_get_crl,
X509_STORE_CTX_get_check_revocation,
X509_STORE_CTX_get_check_issued,
X509_STORE_CTX_get_get_issuer,
X509_STORE_CTX_get_verify_cb,
X509_STORE_CTX_set_verify_cb,
X509_STORE_CTX_verify_cb
- get and set verification callback</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
#include <openssl/x509_vfy.h></pre>
<pre>
typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *);</pre>
<pre>
X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx);</pre>
<pre>
void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx,
X509_STORE_CTX_verify_cb verify_cb);</pre>
<pre>
X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx);
X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx);
X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx);
X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx);
X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx);
X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx);
X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx);</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>X509_STORE_CTX_set_verify_cb() sets the verification callback of <strong>ctx</strong> to
<strong>verify_cb</strong> overwriting any existing callback.</p>
<p>The verification callback can be used to customise the operation of certificate
verification, either by overriding error conditions or logging errors for
debugging purposes.</p>
<p>However, a verification callback is <strong>not</strong> essential and the default operation
is often sufficient.</p>
<p>The <strong>ok</strong> parameter to the callback indicates the value the callback should
return to retain the default behaviour. If it is zero then an error condition
is indicated. If it is 1 then no error occurred. If the flag
<strong>X509_V_FLAG_NOTIFY_POLICY</strong> is set then <strong>ok</strong> is set to 2 to indicate the
policy checking is complete.</p>
<p>The <strong>ctx</strong> parameter to the callback is the <strong>X509_STORE_CTX</strong> structure that
is performing the verification operation. A callback can examine this
structure and receive additional information about the error, for example
by calling X509_STORE_CTX_get_current_cert(). Additional application data can
be passed to the callback via the <strong>ex_data</strong> mechanism.</p>
<p>X509_STORE_CTX_get_verify_cb() returns the value of the current callback
for the specific <strong>ctx</strong>.</p>
<p>X509_STORE_CTX_get_get_issuer(),
X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
and X509_STORE_CTX_get_cleanup() return the function pointers cached
from the corresponding <strong>X509_STORE</strong>, please see
<em>X509_STORE_set_verify(3)</em> for more information.</p>
<p>
</p>
<hr />
<h1><a name="warnings">WARNINGS</a></h1>
<p>In general a verification callback should <strong>NOT</strong> unconditionally return 1 in
all circumstances because this will allow verification to succeed no matter
what the error. This effectively removes all security from the application
because <strong>any</strong> certificate (including untrusted generated ones) will be
accepted.</p>
<p>
</p>
<hr />
<h1><a name="notes">NOTES</a></h1>
<p>The verification callback can be set and inherited from the parent structure
performing the operation. In some cases (such as S/MIME verification) the
<strong>X509_STORE_CTX</strong> structure is created and destroyed internally and the
only way to set a custom verification callback is by inheriting it from the
associated <strong>X509_STORE</strong>.</p>
<p>
</p>
<hr />
<h1><a name="return_values">RETURN VALUES</a></h1>
<p>X509_STORE_CTX_set_verify_cb() does not return a value.</p>
<p>
</p>
<hr />
<h1><a name="examples">EXAMPLES</a></h1>
<p>Default callback operation:</p>
<pre>
int verify_callback(int ok, X509_STORE_CTX *ctx) {
return ok;
}</pre>
<p>Simple example, suppose a certificate in the chain is expired and we wish
to continue after this error:</p>
<pre>
int verify_callback(int ok, X509_STORE_CTX *ctx) {
/* Tolerate certificate expiration */
if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
return 1;
/* Otherwise don't override */
return ok;
}</pre>
<p>More complex example, we don't wish to continue after <strong>any</strong> certificate has
expired just one specific case:</p>
<pre>
int verify_callback(int ok, X509_STORE_CTX *ctx)
{
int err = X509_STORE_CTX_get_error(ctx);
X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);</pre>
<pre>
if (err == X509_V_ERR_CERT_HAS_EXPIRED) {
if (check_is_acceptable_expired_cert(err_cert)
return 1;
}
return ok;
}</pre>
<p>Full featured logging callback. In this case the <strong>bio_err</strong> is assumed to be
a global logging <strong>BIO</strong>, an alternative would to store a BIO in <strong>ctx</strong> using
<strong>ex_data</strong>.</p>
<pre>
int verify_callback(int ok, X509_STORE_CTX *ctx)
{
X509 *err_cert;
int err, depth;</pre>
<pre>
err_cert = X509_STORE_CTX_get_current_cert(ctx);
err = X509_STORE_CTX_get_error(ctx);
depth = X509_STORE_CTX_get_error_depth(ctx);</pre>
<pre>
BIO_printf(bio_err, "depth=%d ", depth);
if (err_cert) {
X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert),
0, XN_FLAG_ONELINE);
BIO_puts(bio_err, "\n");
}
else
BIO_puts(bio_err, "<no cert>\n");
if (!ok)
BIO_printf(bio_err, "verify error:num=%d:%s\n", err,
X509_verify_cert_error_string(err));
switch (err) {
case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
BIO_puts(bio_err, "issuer= ");
X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert),
0, XN_FLAG_ONELINE);
BIO_puts(bio_err, "\n");
break;
case X509_V_ERR_CERT_NOT_YET_VALID:
case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
BIO_printf(bio_err, "notBefore=");
ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert));
BIO_printf(bio_err, "\n");
break;
case X509_V_ERR_CERT_HAS_EXPIRED:
case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
BIO_printf(bio_err, "notAfter=");
ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert));
BIO_printf(bio_err, "\n");
break;
case X509_V_ERR_NO_EXPLICIT_POLICY:
policies_print(bio_err, ctx);
break;
}
if (err == X509_V_OK && ok == 2)
/* print out policies */</pre>
<pre>
BIO_printf(bio_err, "verify return:%d\n", ok);
return(ok);
}</pre>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><em>X509_STORE_CTX_get_error(3)</em>
<em>X509_STORE_set_verify_cb_func(3)</em>
<em>X509_STORE_CTX_get_ex_new_index(3)</em></p>
<p>
</p>
<hr />
<h1><a name="history">HISTORY</a></h1>
<p>The
X509_STORE_CTX_get_get_issuer(),
X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(),
X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(),
X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(),
X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls()
and X509_STORE_CTX_get_cleanup() functions were added in OpenSSL 1.1.0.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2009-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>