From 0e82e0e1d0dcbf1f014f1d36d0626d2a0b699a0d Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sat, 23 Jul 2016 16:00:02 +0200 Subject: [PATCH] Document the X509_STORE and X509_STORE_CTX setters and getters Reviewed-by: Rich Salz --- doc/crypto/X509_STORE_CTX_set_verify_cb.pod | 33 ++- doc/crypto/X509_STORE_set_verify_cb_func.pod | 205 +++++++++++++++++-- 2 files changed, 222 insertions(+), 16 deletions(-) diff --git a/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/doc/crypto/X509_STORE_CTX_set_verify_cb.pod index 57371bf286..527cba1017 100644 --- a/doc/crypto/X509_STORE_CTX_set_verify_cb.pod +++ b/doc/crypto/X509_STORE_CTX_set_verify_cb.pod @@ -16,6 +16,18 @@ X509_STORE_CTX_set_verify_cb - get and set verification callback void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_cb verify_cb); + X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx); + 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 X509_STORE_CTX_set_verify_cb() sets the verification callback of B to @@ -29,7 +41,7 @@ However a verification callback is B essential and the default operation is often sufficient. The B 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 is set then B is set to 2 to indicate the policy checking is complete. @@ -43,6 +55,16 @@ be passed to the callback via the B mechanism. X509_STORE_CTX_get_verify_cb() returns the value of the current callback for the specific B. +X509_STORE_CTX_get_verify(), 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, please see +L for more information. + + =head1 WARNING In general a verification callback should B unconditionally return 1 in @@ -161,6 +183,15 @@ L L L +=head1 HISTORY + +X509_STORE_CTX_get_verify(), 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 addded in OpenSSL 1.1.0. + =head1 COPYRIGHT Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/crypto/X509_STORE_set_verify_cb_func.pod b/doc/crypto/X509_STORE_set_verify_cb_func.pod index 7e66b23e04..950e83385d 100644 --- a/doc/crypto/X509_STORE_set_verify_cb_func.pod +++ b/doc/crypto/X509_STORE_set_verify_cb_func.pod @@ -8,26 +8,185 @@ X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification callb #include - void X509_STORE_set_verify_cb(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); - + typedef int (*X509_STORE_CTX_verify_cb)(int ok, X509_STORE_CTX *ctx); + typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *ctx); + typedef int (*X509_STORE_CTX_get_issuer_fn)(X509 **issuer, + X509_STORE_CTX *ctx, X509 *x); + typedef int (*X509_STORE_CTX_check_issued_fn)(X509_STORE_CTX *ctx, + X509 *x, X509 *issuer); + typedef int (*X509_STORE_CTX_check_revocation_fn)(X509_STORE_CTX *ctx); + typedef int (*X509_STORE_CTX_get_crl_fn)(X509_STORE_CTX *ctx, + X509_CRL **crl, X509 *x); + typedef int (*X509_STORE_CTX_check_crl_fn)(X509_STORE_CTX *ctx, X509_CRL *crl); + typedef int (*X509_STORE_CTX_cert_crl_fn)(X509_STORE_CTX *ctx, + X509_CRL *crl, X509 *x); + typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx); + typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx, + X509_NAME *nm); + typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(X509_STORE_CTX *ctx, + X509_NAME *nm); + typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx); + + void X509_STORE_set_verify_cb(X509_STORE *ctx, + X509_STORE_CTX_verify_cb verify_cb); + X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(X509_STORE_CTX *ctx); + + void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify_fn verify); + X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx); + + void X509_STORE_set_get_issuer(X509_STORE *ctx, + X509_STORE_CTX_get_issuer_fn get_issuer); + X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_issued(X509_STORE *ctx, + X509_STORE_CTX_check_issued_fn check_issued); + X509_STORE_CTX_check_issued_fn X509_STORE_get_check_issued(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_revocation(X509_STORE *ctx, + X509_STORE_CTX_check_revocation_fn check_revocation); + X509_STORE_CTX_check_revocation_fn X509_STORE_get_check_revocation(X509_STORE_CTX *ctx); + + void X509_STORE_set_get_crl(X509_STORE *ctx, + X509_STORE_CTX_get_crl_fn get_crl); + X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_crl(X509_STORE *ctx, + X509_STORE_CTX_check_crl_fn check_crl); + X509_STORE_CTX_check_crl_fn X509_STORE_get_check_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_cert_crl(X509_STORE *ctx, + X509_STORE_CTX_cert_crl_fn cert_crl); + X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_policy(X509_STORE *ctx, + X509_STORE_CTX_check_policy_fn check_policy); + X509_STORE_CTX_check_policy_fn X509_STORE_get_check_policy(X509_STORE_CTX *ctx); + + void X509_STORE_set_lookup_certs(X509_STORE *ctx, + X509_STORE_CTX_lookup_certs_fn lookup_certs); + X509_STORE_CTX_lookup_certs_fn X509_STORE_get_lookup_certs(X509_STORE_CTX *ctx); + + void X509_STORE_set_lookup_crls(X509_STORE *ctx, + X509_STORE_CTX_lookup_crls_fn lookup_crls); + X509_STORE_CTX_lookup_crls_fn X509_STORE_get_lookup_crls(X509_STORE_CTX *ctx); + + void X509_STORE_set_cleanup(X509_STORE *ctx, + X509_STORE_CTX_cleanup_fn cleanup); + X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(X509_STORE_CTX *ctx); + + /* Aliases */ void X509_STORE_set_verify_cb_func(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + X509_STORE_CTX_verify_cb verify_cb); + void X509_STORE_set_verify_func(X509_STORE *ctx, + X509_STORE_CTX_verify_fn verify); + void X509_STORE_set_lookup_crls_cb(X509_STORE *ctx, + X509_STORE_CTX_lookup_crls_fn lookup_crls); =head1 DESCRIPTION X509_STORE_set_verify_cb() sets the verification callback of B to -B overwriting any existing callback. - -X509_STORE_set_verify_cb_func() also sets the verification callback but it -is implemented as a macro. +B overwriting the previous callback. +The callback assigned with this function becomes a default for the one +that can be assigned directly to the corresponding B, +please see L for further information. + +X509_STORE_set_verify() sets the final chain verification function for +B to B. +Its purpose is to go through the chain of certificates and check that +all signatures are valid and that the current time is within the +limits of each certificate's first and last validity time. +The final chain verification functions must return 0 on failure and 1 +on success. +I + +X509_STORE_set_get_issuer() sets the function to get the issuer +certificate that verifies the given certificate B. +When found, the issuer certificate must be assigned to B<*issuer>. +This function must return 0 on failure and 1 on success. +I + +X509_STORE_set_check_issued() sets the function to check that a given +certificate B is issued with the issuer certificate B. +This function must return 0 on failure (among others if B hasn't +been issued with B) and 1 on success. +I + +X509_STORE_set_check_revocation() sets the revocation checking +function. +Its purpose is to look through the final chain and check the +revocation status for each certificate. +It must return 0 on failure and 1 on success. +I + +X509_STORE_set_get_crl() sets the function to get the crl for a given +certificate B. +When found, the crl must be assigned to B<*crl>. +This function must return 0 on failure and 1 on success. +I + +X509_STORE_set_check_crl() sets the function to check the validity of +the given B. +This function must return 0 on failure and 1 on success. +I + +X509_STORE_set_cert_crl() sets the function to check the revocation +status of the given certificate B against the given B. +This function must return 0 on failure and 1 on success. +I + +X509_STORE_set_check_policy() sets the function to check the policies +of all the certificates in the final chain.. +This function must return 0 on failure and 1 on success. +I + +X509_STORE_set_lookup_certs() and X509_STORE_set_lookup_crls() set the +functions to look up all the certs or all the CRLs that match the +given name B. +These functions return NULL on failure and a pointer to a stack of +certificates (B) or to a stack of CRLs (B) on +success. +I + +X509_STORE_set_cleanup() sets the final cleanup function, which is +called when the context (B) is being torn down. +This function doesn't return any value. +I + +X509_STORE_get_verify_cb(), X509_STORE_CTX_get_verify(), +X509_STORE_get_get_issuer(), X509_STORE_get_check_issued(), +X509_STORE_get_check_revocation(), X509_STORE_get_get_crl(), +X509_STORE_get_check_crl(), X509_STORE_set_verify(), +X509_STORE_set_get_issuer(), X509_STORE_get_cert_crl(), +X509_STORE_get_check_policy(), X509_STORE_get_lookup_certs(), +X509_STORE_get_lookup_crls() and X509_STORE_get_cleanup() all return +the function pointer assigned with X509_STORE_set_check_issued(), +X509_STORE_set_check_revocation(), X509_STORE_set_get_crl(), +X509_STORE_set_check_crl(), X509_STORE_set_cert_crl(), +X509_STORE_set_check_policy(), X509_STORE_set_lookup_certs(), +X509_STORE_set_lookup_crls() and X509_STORE_set_cleanup(), or NULL if +no assignment has been made. + +X509_STORE_set_verify_cb_func(), X509_STORE_set_verify_func() and +X509_STORE_set_lookup_crls_cb() are aliases for +X509_STORE_set_verify_cb(), X509_STORE_set_verify() and +X509_STORE_set_lookup_crls, available as macros for backward +compatibility. =head1 NOTES -The verification callback from an B is inherited by -the corresponding B structure when it is initialized. This can -be used to set the verification callback when the B is -otherwise inaccessible (for example during S/MIME verification). +All the callbacks from a B are inherited by the +corresponding B structure when it is initialized. +See L for further details. =head1 BUGS @@ -36,18 +195,34 @@ OpenSSL 1.0.0. =head1 RETURN VALUES -X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return -a value. +The X509_STORE_set_*() functions do not return a value. + +The X509_STORE_get_*() functions return a pointer of the appropriate +function type. =head1 SEE ALSO -L +L, L, L =head1 HISTORY X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. +X509_STORE_set_verify_cb(), X509_STORE_get_verify_cb(), +X509_STORE_set_verify(), X509_STORE_CTX_get_verify(), +X509_STORE_set_get_issuer(), X509_STORE_get_get_issuer(), +X509_STORE_set_check_issued(), X509_STORE_get_check_issued(), +X509_STORE_set_check_revocation(), X509_STORE_get_check_revocation(), +X509_STORE_set_get_crl(), X509_STORE_get_get_crl(), +X509_STORE_set_check_crl(), X509_STORE_get_check_crl(), +X509_STORE_set_cert_crl(), X509_STORE_get_cert_crl(), +X509_STORE_set_check_policy(), X509_STORE_get_check_policy(), +X509_STORE_set_lookup_certs(), X509_STORE_get_lookup_certs(), +X509_STORE_set_lookup_crls(), X509_STORE_get_lookup_crls(), +X509_STORE_set_cleanup() and X509_STORE_get_cleanup() were addded in +OpenSSL 1.1.0. + =head1 COPYRIGHT Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. -- GitLab