From 5b2b60ae9807b0980b00da7da7415c9b75931eea Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Sun, 18 Oct 2009 15:28:59 +0000 Subject: [PATCH] Document additions for X509 chain verification from HEAD --- doc/crypto/DSA_get_ex_new_index.pod | 2 +- doc/crypto/X509_STORE_CTX_get_error.pod | 303 ++++++++++++++++++ .../X509_STORE_CTX_get_ex_new_index.pod | 41 +++ doc/crypto/X509_STORE_CTX_new.pod | 122 +++++++ doc/crypto/X509_STORE_CTX_set_verify_cb.pod | 161 ++++++++++ doc/crypto/X509_STORE_set_verify_cb_func.pod | 54 ++++ doc/crypto/X509_VERIFY_PARAM_set_flags.pod | 171 ++++++++++ doc/crypto/X509_verify_cert.pod | 53 +++ 8 files changed, 906 insertions(+), 1 deletion(-) create mode 100644 doc/crypto/X509_STORE_CTX_get_error.pod create mode 100644 doc/crypto/X509_STORE_CTX_get_ex_new_index.pod create mode 100644 doc/crypto/X509_STORE_CTX_new.pod create mode 100644 doc/crypto/X509_STORE_CTX_set_verify_cb.pod create mode 100644 doc/crypto/X509_STORE_set_verify_cb_func.pod create mode 100644 doc/crypto/X509_VERIFY_PARAM_set_flags.pod create mode 100644 doc/crypto/X509_verify_cert.pod diff --git a/doc/crypto/DSA_get_ex_new_index.pod b/doc/crypto/DSA_get_ex_new_index.pod index 4612e708ec..fb6efc1182 100644 --- a/doc/crypto/DSA_get_ex_new_index.pod +++ b/doc/crypto/DSA_get_ex_new_index.pod @@ -6,7 +6,7 @@ DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specifi =head1 SYNOPSIS - #include + #include int DSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, diff --git a/doc/crypto/X509_STORE_CTX_get_error.pod b/doc/crypto/X509_STORE_CTX_get_error.pod new file mode 100644 index 0000000000..a883f6c097 --- /dev/null +++ b/doc/crypto/X509_STORE_CTX_get_error.pod @@ -0,0 +1,303 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, X509_STORE_CTX_get_error_depth, X509_STORE_CTX_get_current_cert, X509_STORE_CTX_get1_chain, X509_verify_cert_error_string - get or set certificate verification status information + +=head1 SYNOPSIS + + #include + #include + + int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); + int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); + X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); + + STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); + + const char *X509_verify_cert_error_string(long n); + +=head1 DESCRIPTION + +These functions are typically called after X509_verify_cert() has indicated +an error or in a verification callback to determine the nature of an error. + +X509_STORE_CTX_get_error() returns the error code of B, see +the B section for a full description of all error codes. + +X509_STORE_CTX_set_error() sets the error code of B to B. For example +it might be used in a verification callback to set an error based on additional +checks. + +X509_STORE_CTX_get_error_depth() returns the B of the error. This is a +non-negative integer representing where in the certificate chain the error +occurred. If it is zero it occured in the end entity certificate, one if +it is the certificate which signed the end entity certificate and so on. + +X509_STORE_CTX_get_current_cert() returns the certificate in B which +caused the error or B if no certificate is relevant. + +X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous +call to X509_verify_cert() is successful. If the call to X509_verify_cert() +is B successful the returned chain may be incomplete or invalid. The +returned chain persists after the B structure is freed, when it is +no longer needed it should be free up using: + + sk_X509_pop_free(chain, X509_free); + +X509_verify_cert_error_string() returns a human readable error string for +verification error B. + +=head1 RETURN VALUES + +X509_STORE_CTX_get_error() returns B or an error code. + +X509_STORE_CTX_get_error_depth() returns a non-negative error depth. + +X509_STORE_CTX_get_current_cert() returns the cerificate which caused the +error or B if no certificate is relevant to the error. + +X509_verify_cert_error_string() returns a human readable error string for +verification error B. + +=head1 ERROR CODES + +A list of error codes and messages is shown below. Some of the +error codes are defined but currently never returned: these are described as +"unused". + +=over 4 + +=item B + +the operation was successful. + +=item B + +the issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. + +=item B + +the CRL of a certificate could not be found. + +=item B + +the certificate signature could not be decrypted. This means that the actual +signature value could not be determined rather than it not matching the +expected value, this is only meaningful for RSA keys. + +=item B + +the CRL signature could not be decrypted: this means that the actual signature +value could not be determined rather than it not matching the expected value. +Unused. + +=item B + +the public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B + +the signature of the certificate is invalid. + +=item B + +the signature of the certificate is invalid. + +=item B + +the certificate is not yet valid: the notBefore date is after the current time. + +=item B + +the certificate has expired: that is the notAfter date is before the current time. + +=item B + +the CRL is not yet valid. + +=item B + +the CRL has expired. + +=item B + +the certificate notBefore field contains an invalid time. + +=item B + +the certificate notAfter field contains an invalid time. + +=item B + +the CRL lastUpdate field contains an invalid time. + +=item B + +the CRL nextUpdate field contains an invalid time. + +=item B + +an error occurred trying to allocate memory. This should never happen. + +=item B + +the passed certificate is self signed and the same certificate cannot be found +in the list of trusted certificates. + +=item B + +the certificate chain could be built up using the untrusted certificates but +the root could not be found locally. + +=item B + +the issuer certificate of a locally looked up certificate could not be found. +This normally means the list of trusted certificates is not complete. + +=item B + +no signatures could be verified because the chain contains only one certificate +and it is not self signed. + +=item B + +the certificate chain length is greater than the supplied maximum depth. Unused. + +=item B + +the certificate has been revoked. + +=item B + +a CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. + +=item B + +the basicConstraints pathlength parameter has been exceeded. + +=item B + +the supplied certificate cannot be used for the specified purpose. + +=item B + +the root CA is not marked as trusted for the specified purpose. + +=item B + +the root CA is marked to reject the specified purpose. + +=item B + +the current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. This is only set +if issuer check debugging is enabled it is used for status notification and +is B in itself an error. + +=item B + +the current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. This is only set if issuer check debugging is enabled it is used +for status notification and is B in itself an error. + +=item B + +the current candidate issuer certificate was rejected because its issuer name +and serial number was present and did not match the authority key identifier of +the current certificate. This is only set if issuer check debugging is enabled +it is used for status notification and is B in itself an error. + +=item B + +the current candidate issuer certificate was rejected because its keyUsage +extension does not permit certificate signing. This is only set if issuer check +debugging is enabled it is used for status notification and is B in itself +an error. + +=item B + +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. + + +=item B + +A certificate policies extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. This error only +occurs if policy processing is enabled. + +=item B + +The verification flags were set to require and explicit policy but none was +present. + +=item B + +The only CRLs that could be found did not match the scope of the certificate. + +=item B + +Some feature of a certificate extension is not supported. Unused. + +=item B + +A name constraint violation occured in the permitted subtrees. + +=item B + +A name constraint violation occured in the excluded subtrees. + +=item B + +A certificate name constraints extension included a minimum or maximum field: +this is not supported. + +=item B + +An unsupported name constraint type was encountered. OpenSSL currently only +supports directory name, DNS name, email and URI types. + +=item B + +The format of the name constraint is not recognised: for example an email +address format of a form not mentioned in RFC3280. This could be caused by +a garbage extension or some new feature not currently supported. + +=item B + +An error occured when attempting to verify the CRL path. This error can only +happen if extended CRL checking is enabled. + +=item B + +an application specific error. This will never be returned unless explicitly +set by an application. + +=head1 NOTES + +The above functions should be used instead of directly referencing the fields +in the B structure. + +In versions of OpenSSL before 1.0 the current certificate returned by +X509_STORE_CTX_get_current_cert() was never B. Applications should +check the return value before printing out any debugging information relating +to the current certificate. + +If an unrecognised error code is passed to X509_verify_cert_error_string() the +numerical value of the unknown code is returned in a static buffer. This is not +thread safe but will never happen unless an invalid code is passed. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod b/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod new file mode 100644 index 0000000000..8d6b9dda47 --- /dev/null +++ b/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX structures + +=head1 SYNOPSIS + + #include + + int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); + + char *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); + +=head1 DESCRIPTION + +These functions handle application specific data in X509_STORE_CTX structures. +Their usage is identical to that of RSA_get_ex_new_index(), RSA_set_ex_data() +and RSA_get_ex_data() as described in L. + +=head1 NOTES + +This mechanism is used internally by the B library to store the B +structure associated with a verification operation in an B +structure. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +X509_STORE_CTX_get_ex_new_index(), X509_STORE_CTX_set_ex_data() and +X509_STORE_CTX_get_ex_data() are available since OpenSSL 0.9.5. + +=cut diff --git a/doc/crypto/X509_STORE_CTX_new.pod b/doc/crypto/X509_STORE_CTX_new.pod new file mode 100644 index 0000000000..b17888f149 --- /dev/null +++ b/doc/crypto/X509_STORE_CTX_new.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - X509_STORE_CTX initialisation + +=head1 SYNOPSIS + + #include + + X509_STORE_CTX *X509_STORE_CTX_new(void); + void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); + void X509_STORE_CTX_free(X509_STORE_CTX *ctx); + + int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, + X509 *x509, STACK_OF(X509) *chain); + + void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); + + void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); + void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); + void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); + + X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); + int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); + +=head1 DESCRIPTION + +These functions initialise an B structure for subsequent use +by X509_verify_cert(). + +X509_STORE_CTX_new() returns a newly initialised B structure. + +X509_STORE_CTX_cleanup() internally cleans up an B structure. +The context can then be reused with an new call to X509_STORE_CTX_init(). + +X509_STORE_CTX_free() completely frees up B. After this call B +is no longer valid. + +X509_STORE_CTX_init() sets up B for a subsequent verification operation. +The trusted certificate store is set to B, the end entity certificate +to be verified is set to B and a set of additional certificates (which +will be untrusted but may be used to build the chain) in B. Any or +all of the B, B and B parameters can be B. + +X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B +to B. This is an alternative way of specifying trusted certificates +instead of using an B. + +X509_STORE_CTX_set_cert() sets the certificate to be vertified in B to +B. + +X509_STORE_CTX_set_chain() sets the additional certificate chain used by B +to B. + +X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate +verification to B. These CRLs will only be used if CRL verification is +enabled in the associated B structure. This might be +used where additional "useful" CRLs are supplied as part of a protocol, +for example in a PKCS#7 structure. + +X509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an intenal pointer +to the verification parameters associated with B. + +X509_STORE_CTX_set0_param() sets the intenal verification parameter pointer +to B. After this call B should not be used. + +X509_STORE_CTX_set_default() looks up and sets the default verification +method to B. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from B. + +=head1 NOTES + +The certificates and CRLs in a store are used internally and should B +be freed up until after the associated B is freed. Legacy +applications might implicitly use an B like this: + + X509_STORE_CTX ctx; + X509_STORE_CTX_init(&ctx, store, cert, chain); + +this is B recommended in new applications they should instead do: + + X509_STORE_CTX *ctx; + ctx = X509_STORE_CTX_new(); + if (ctx == NULL) + /* Bad error */ + X509_STORE_CTX_init(ctx, store, cert, chain); + +=head1 BUGS + +The certificates and CRLs in a context are used internally and should B +be freed up until after the associated B is freed. Copies +should be made or reference counts increased instead. + +=head1 RETURN VALUES + +X509_STORE_CTX_new() returns an newly allocates context or B is an +error occurred. + +X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. + +X509_STORE_CTX_get0_param() returns a pointer to an B +structure or B if an error occurred. + +X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), X509_STORE_CTX_trusted_stack(), +X509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), +X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return +values. + +X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. + +=head1 SEE ALSO + +L +L + +=head1 HISTORY + +X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 + +=cut diff --git a/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/doc/crypto/X509_STORE_CTX_set_verify_cb.pod new file mode 100644 index 0000000000..b9787a6ca6 --- /dev/null +++ b/doc/crypto/X509_STORE_CTX_set_verify_cb.pod @@ -0,0 +1,161 @@ +=pod + +=head1 NAME + +X509_STORE_CTX_set_verify_cb - set verification callback + +=head1 SYNOPSIS + + #include + + void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, + int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + +=head1 DESCRIPTION + +X509_STORE_CTX_set_verify_cb() sets the verification callback of B to +B overwriting any existing callback. + +The verification callback can be used to customise the operation of certificate +verification, either by overriding error conditions or logging errors for +debugging purposes. + +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 +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. + +The B parameter to the callback is the B 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 B mechanism. + +=head1 WARNING + +In general a verification callback should B 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 B certificate (including untrusted generated ones) will be +accepted. + +=head1 NOTES + +The verification callback can be set and inherited from the parent structure +performing the operation. In some cases (such as S/MIME verification) the +B structure is created and destroyed internally and the +only way to set a custom verification callback is by inheriting it from the +associated B. + +=head1 RETURN VALUES + +X509_STORE_CTX_set_verify_cb() does not return a value. + +=head1 EXAMPLES + +Default callback operation: + + int verify_callback(int ok, X509_STORE_CTX *ctx) + { + 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; + } + +More complex example, we don't wish to continue after B 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; + } + +Full featured logging callback. In this case the B is assumed to be +a global logging B, an alternative would to store a BIO in B using +B. + + 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, "\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 +L +L + +=head1 HISTORY + +X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and +OpenSSL. + +=cut diff --git a/doc/crypto/X509_STORE_set_verify_cb_func.pod b/doc/crypto/X509_STORE_set_verify_cb_func.pod new file mode 100644 index 0000000000..1b774fc0cb --- /dev/null +++ b/doc/crypto/X509_STORE_set_verify_cb_func.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification callback + +=head1 SYNOPSIS + + #include + + void X509_STORE_set_verify_cb(X509_STORE *st, + int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + + void X509_STORE_set_verify_cb_func(X509_STORE *st, + int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + +=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. + +=head 1 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). + +=head1 BUGS + +The macro version of this function was the only one available before +OpenSSL 1.0.0. + +=head1 RETURN VALUES + +X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return +a value. + +=head1 SEE ALSO + +L +L + +=head1 HISTORY + +X509_STORE_set_verify_cb_func() is available in all versions of SSLeay and +OpenSSL. + +X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. + +=cut diff --git a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod new file mode 100644 index 0000000000..b68eece033 --- /dev/null +++ b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod @@ -0,0 +1,171 @@ +=pod + +=head1 NAME + +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters + +=head1 SYNOPSIS + + #include + + int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); + int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, + unsigned long flags); + unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); + + int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); + int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); + + void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); + + int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, + ASN1_OBJECT *policy); + int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, + STACK_OF(ASN1_OBJECT) *policies); + + void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); + int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); + +=head1 DESCRIPTION + +These functions manipulate the B structure associated with +a certificate verification operation. + +The X509_VERIFY_PARAM_set_flags() function sets the flags in B by oring +it with B. See the B section for a complete +description of values the B parameter can take. + +X509_VERIFY_PARAM_get_flags() returns the flags in B. + +X509_VERIFY_PARAM_clear_flags() clears the flags B in B. + +X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B +to B. This determines the acceptable purpose of the certificate +chain, for example SSL client or SSL server. + +X509_VERIFY_PARAM_set_trust() sets the trust setting in B to +B. + +X509_VERIFY_PARAM_set_time() sets the verification time in B to +B. Normally the current time is used. + +X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled +by default) and adds B to the acceptable policy set. + +X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled +by default) and sets the acceptable policy set to B. Any existing +policy set is cleared. The B parameter can be B to clear +an existing policy set. + +X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B. +That is the maximum number of untrusted CA certificates that can appear in a +chain. + +=head1 RETURN VALUES + +X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), +X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), +X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 +for success and 0 for failure. + +X509_VERIFY_PARAM_get_flags() returns the current verification flags. + +X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return +values. + +X509_VERIFY_PARAM_get_depth() returns the current verification depth. + +=head1 VERIFICATION FLAGS + +The verification flags consists of zero or more of the following flags +ored together. + +B enables CRL checking for the certificate chain leaf +certificate. An error occurs if a suitable CRL cannot be found. + +B enables CRL checking for the entire certificate +chain. + +B disabled critical extension checking. By default +any unhandled critical extensions in certificates or (if checked) CRLs results +in a fatal error. If this flag is set unhandled critical extensions are +ignored. B setting this option for anything other than debugging +purposes can be a security risk. Finer control over which extensions are +supported can be performed in the verification callback. + +THe B flag disables workarounds for some broken +certificates and makes the verification strictly apply B rules. + +B enables proxy certificate verification. + +B enables certificate policy checking, by default +no policy checking is peformed. Additional information is sent to the +verification callback relating to policy checking. + +B, B and +B set the B, B and B flags respectively as defined in +B. Policy checking is automatically enabled if any of these flags +are set. + +If B is set and the policy checking is successful +a special status code is set to the verification callback. This permits it +to examine the valid policy tree and perform additional checks or simply +log it for debugging purposes. + +By default some addtional features such as indirect CRLs and CRLs signed by +different keys are disabled. If B is set +they are enabled. + +If B ise set delta CRLs (if present) are used to +determine certificate status. If not set deltas are ignored. + +B enables checking of the root CA self signed +cerificate signature. By default this check is disabled because it doesn't +add any additional security but in some cases applications might want to +check the signature anyway. A side effect of not checking the root CA +signature is that disabled or unsupported message digests on the root CA +are not treated as fatal errors. + +The B flag enables debugging of certificate +issuer checks. It is B needed unless you are logging certificate +verification. If this flag is set then additional status codes will be sent +to the verification callback and it B be prepared to handle such cases +without assuming they are hard errors. + +=head1 NOTES + +The above functions should be used to manipulate verification parameters +instead of legacy functions which work in specific structures such as +X509_STORE_CTX_set_flags(). + +=head1 BUGS + +Delta CRL checking is currently primitive. Only a single delta can be used and +(partly due to limitations of B) constructed CRLs are not +maintained. + +If CRLs checking is enable CRLs are expected to be available in the +corresponding B structure. No attempt is made to download +CRLs from the CRL distribution points extension. + +=head1 EXAMPLE + +Enable CRL checking when performing certificate verification during SSL +connections associated with an B structure B: + + X509_VERIFY_PARAM *param; + param = X509_VERIFY_PARAM_new(); + X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); + SSL_CTX_set1_param(ctx, param); + X509_VERIFY_PARAM_free(param); + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/X509_verify_cert.pod b/doc/crypto/X509_verify_cert.pod new file mode 100644 index 0000000000..5253bdcd70 --- /dev/null +++ b/doc/crypto/X509_verify_cert.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +X509_verify_cert - discover and verify X509 certificte chain + +=head1 SYNOPSIS + + #include + + int X509_verify_cert(X509_STORE_CTX *ctx); + +=head1 DESCRIPTION + +The X509_verify_cert() function attempts to discover and validate a +certificate chain based on parameters in B. A complete description of +the process is contained in the L manual page. + +=head1 RETURN VALUES + +If a complete chain can be built and validated this function returns 1, +otherwise it return zero, in exceptional circumstances it can also +return a negative code. + +If the function fails additional error information can be obtained by +examining B using, for example X509_STORE_CTX_get_error(). + +=head1 NOTES + +Applications rarely call this function directly but it is used by +OpenSSL internally for certificate validation, in both the S/MIME and +SSL/TLS code. + +The negative return value from X509_verify_cert() can only occur if no +certificate is set in B (due to a programming error) or if a retry +operation is requested during internal lookups (which never happens with +standard lookup methods). It is however recommended that application check +for <= 0 return value on error. + +=head1 BUGS + +This function uses the header B as opposed to most chain verification +functiosn which use B. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +X509_verify_cert() is available in all versions of SSLeay and OpenSSL. + +=cut -- 2.40.0