diff options
Diffstat (limited to 'deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod')
| -rw-r--r-- | deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod | 212 |
1 files changed, 133 insertions, 79 deletions
diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod index b9787a6ca6..3be256dc74 100644 --- a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod @@ -2,14 +2,42 @@ =head1 NAME -X509_STORE_CTX_set_verify_cb - set verification callback +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 =head1 SYNOPSIS #include <openssl/x509_vfy.h> + typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *); + + X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + X509_STORE_CTX_verify_cb verify_cb); + + 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); =head1 DESCRIPTION @@ -24,7 +52,7 @@ However a verification callback is B<not> essential and the default operation is often sufficient. The B<ok> parameter to the callback indicates the value the callback should -return to retain the default behaviour. If it is zero then and error condition +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 B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the policy checking is complete. @@ -35,6 +63,19 @@ 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 B<ex_data> mechanism. +X509_STORE_CTX_get_verify_cb() returns the value of the current callback +for the specific B<ctx>. + +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 B<X509_STORE>, please see +L<X509_STORE_set_verify(3)> for more information. + + =head1 WARNING In general a verification callback should B<NOT> unconditionally return 1 in @@ -60,102 +101,115 @@ X509_STORE_CTX_set_verify_cb() does not return a value. Default callback operation: int verify_callback(int ok, X509_STORE_CTX *ctx) - { - return ok; - } + { + return ok; + } Simple example, suppose a certificate in the chain is expired and we wish to continue after this error: 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; - } + { + /* Tolerate certificate expiration */ + if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) + return 1; + /* Otherwise don't override */ + return ok; + } More complex example, we don't wish to continue after B<any> certificate has expired just one specific case: 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); - if (err == X509_V_ERR_CERT_HAS_EXPIRED) - { - if (check_is_acceptable_expired_cert(err_cert) - return 1; - } - return ok; - } + { + int err = X509_STORE_CTX_get_error(ctx); + X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); + if (err == X509_V_ERR_CERT_HAS_EXPIRED) + { + if (check_is_acceptable_expired_cert(err_cert) + return 1; + } + return ok; + } Full featured logging callback. In this case the B<bio_err> is assumed to be a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using B<ex_data>. - + int verify_callback(int ok, X509_STORE_CTX *ctx) - { - X509 *err_cert; - int err,depth; - - err_cert = X509_STORE_CTX_get_current_cert(ctx); - err = X509_STORE_CTX_get_error(ctx); - depth = X509_STORE_CTX_get_error_depth(ctx); - - 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 */ - - BIO_printf(bio_err,"verify return:%d\n",ok); - return(ok); - } + { + X509 *err_cert; + int err, depth; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + 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 */ + + BIO_printf(bio_err, "verify return:%d\n", ok); + return(ok); + } =head1 SEE ALSO -L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> -L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)> -L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)> +L<X509_STORE_CTX_get_error(3)> +L<X509_STORE_set_verify_cb_func(3)> +L<X509_STORE_CTX_get_ex_new_index(3)> =head1 HISTORY -X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and -OpenSSL. +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() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. =cut |