diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2009-10-18 15:28:59 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2009-10-18 15:28:59 +0000 |
commit | 5b2b60ae9807b0980b00da7da7415c9b75931eea (patch) | |
tree | 48237e237268c69c396ef49b81baeeb9377e490f | |
parent | c90a1ae0c9d6a9531eec9b4fd693f2ecfee023c4 (diff) | |
download | openssl-5b2b60ae9807b0980b00da7da7415c9b75931eea.tar.gz |
Document additions for X509 chain verification from HEAD
-rw-r--r-- | doc/crypto/DSA_get_ex_new_index.pod | 2 | ||||
-rw-r--r-- | doc/crypto/X509_STORE_CTX_get_error.pod | 303 | ||||
-rw-r--r-- | doc/crypto/X509_STORE_CTX_get_ex_new_index.pod | 41 | ||||
-rw-r--r-- | doc/crypto/X509_STORE_CTX_new.pod | 122 | ||||
-rw-r--r-- | doc/crypto/X509_STORE_CTX_set_verify_cb.pod | 161 | ||||
-rw-r--r-- | doc/crypto/X509_STORE_set_verify_cb_func.pod | 54 | ||||
-rw-r--r-- | doc/crypto/X509_VERIFY_PARAM_set_flags.pod | 171 | ||||
-rw-r--r-- | doc/crypto/X509_verify_cert.pod | 53 |
8 files changed, 906 insertions, 1 deletions
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 <openssl/DSA.h> + #include <openssl/dsa.h> 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 <openssl/x509.h> + #include <openssl/x509_vfy.h> + + 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<ctx>, see +the B<ERROR CODES> section for a full description of all error codes. + +X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. 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<depth> 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<ctx> which +caused the error or B<NULL> 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<not> successful the returned chain may be incomplete or invalid. The +returned chain persists after the B<ctx> 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<n>. + +=head1 RETURN VALUES + +X509_STORE_CTX_get_error() returns B<X509_V_OK> 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<NULL> if no certificate is relevant to the error. + +X509_verify_cert_error_string() returns a human readable error string for +verification error B<n>. + +=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<X509_V_OK: ok> + +the operation was successful. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> + +the issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. + +=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> + +the CRL of a certificate could not be found. + +=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> + +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<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> + +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<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> + +the public key in the certificate SubjectPublicKeyInfo could not be read. + +=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> + +the signature of the certificate is invalid. + +=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> + +the signature of the certificate is invalid. + +=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> + +the certificate is not yet valid: the notBefore date is after the current time. + +=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> + +the certificate has expired: that is the notAfter date is before the current time. + +=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> + +the CRL is not yet valid. + +=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> + +the CRL has expired. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> + +the certificate notBefore field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> + +the certificate notAfter field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> + +the CRL lastUpdate field contains an invalid time. + +=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> + +the CRL nextUpdate field contains an invalid time. + +=item B<X509_V_ERR_OUT_OF_MEM: out of memory> + +an error occurred trying to allocate memory. This should never happen. + +=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> + +the passed certificate is self signed and the same certificate cannot be found +in the list of trusted certificates. + +=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> + +the certificate chain could be built up using the untrusted certificates but +the root could not be found locally. + +=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> + +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<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> + +no signatures could be verified because the chain contains only one certificate +and it is not self signed. + +=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> + +the certificate chain length is greater than the supplied maximum depth. Unused. + +=item B<X509_V_ERR_CERT_REVOKED: certificate revoked> + +the certificate has been revoked. + +=item B<X509_V_ERR_INVALID_CA: invalid CA certificate> + +a CA certificate is invalid. Either it is not a CA or its extensions are not +consistent with the supplied purpose. + +=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> + +the basicConstraints pathlength parameter has been exceeded. + +=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> + +the supplied certificate cannot be used for the specified purpose. + +=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> + +the root CA is not marked as trusted for the specified purpose. + +=item B<X509_V_ERR_CERT_REJECTED: certificate rejected> + +the root CA is marked to reject the specified purpose. + +=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> + +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<not> in itself an error. + +=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> + +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<not> in itself an error. + +=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> + +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<not> in itself an error. + +=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> + +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<not> in itself +an error. + +=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension> + +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. + + +=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension> + +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<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> + +The verification flags were set to require and explicit policy but none was +present. + +=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> + +The only CRLs that could be found did not match the scope of the certificate. + +=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> + +Some feature of a certificate extension is not supported. Unused. + +=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> + +A name constraint violation occured in the permitted subtrees. + +=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> + +A name constraint violation occured in the excluded subtrees. + +=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported> + +A certificate name constraints extension included a minimum or maximum field: +this is not supported. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type> + +An unsupported name constraint type was encountered. OpenSSL currently only +supports directory name, DNS name, email and URI types. + +=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax> + +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<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> + +An error occured when attempting to verify the CRL path. This error can only +happen if extended CRL checking is enabled. + +=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> + +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<X509_VERIFY_CTX> structure. + +In versions of OpenSSL before 1.0 the current certificate returned by +X509_STORE_CTX_get_current_cert() was never B<NULL>. 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<X509_verify_cert(3)|X509_verify_cert(3)> + +=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 <openssl/x509_vfy.h> + + 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<RSA_get_ex_new_index(3)>. + +=head1 NOTES + +This mechanism is used internally by the B<ssl> library to store the B<SSL> +structure associated with a verification operation in an B<X509_STORE_CTX> +structure. + +=head1 SEE ALSO + +L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)> + +=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 <openssl/x509_vfy.h> + + 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<X509_STORE_CTX> structure for subsequent use +by X509_verify_cert(). + +X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. + +X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. +The context can then be reused with an new call to X509_STORE_CTX_init(). + +X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> +is no longer valid. + +X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. +The trusted certificate store is set to B<store>, the end entity certificate +to be verified is set to B<x509> and a set of additional certificates (which +will be untrusted but may be used to build the chain) in B<chain>. Any or +all of the B<store>, B<x509> and B<chain> parameters can be B<NULL>. + +X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx> +to B<sk>. This is an alternative way of specifying trusted certificates +instead of using an B<X509_STORE>. + +X509_STORE_CTX_set_cert() sets the certificate to be vertified in B<ctx> to +B<x>. + +X509_STORE_CTX_set_chain() sets the additional certificate chain used by B<ctx> +to B<sk>. + +X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate +verification to B<sk>. These CRLs will only be used if CRL verification is +enabled in the associated B<X509_VERIFY_PARAM> 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<ctx>. + +X509_STORE_CTX_set0_param() sets the intenal verification parameter pointer +to B<param>. After this call B<param> should not be used. + +X509_STORE_CTX_set_default() looks up and sets the default verification +method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from B<name>. + +=head1 NOTES + +The certificates and CRLs in a store are used internally and should B<not> +be freed up until after the associated B<X509_STORE_CTX> is freed. Legacy +applications might implicitly use an B<X509_STORE_CTX> like this: + + X509_STORE_CTX ctx; + X509_STORE_CTX_init(&ctx, store, cert, chain); + +this is B<not> 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<not> +be freed up until after the associated B<X509_STORE_CTX> 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<NULL> 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<X509_VERIFY_PARAM> +structure or B<NULL> 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<X509_verify_cert(3)|X509_verify_cert(3)> +L<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)> + +=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 <openssl/x509_vfy.h> + + 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<ctx> to +B<verify_cb> 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<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 +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. + +The B<ctx> parameter to the callback is the B<X509_STORE_CTX> 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<ex_data> mechanism. + +=head1 WARNING + +In general a verification callback should B<NOT> 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<any> 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<X509_STORE_CTX> structure is created and destroyed internally and the +only way to set a custom verification callback is by inheriting it from the +associated B<X509_STORE>. + +=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<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; + } + +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); + } + +=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)> + +=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 <openssl/x509_vfy.h> + + 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<ctx> to +B<verify_cb> 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<X509_STORE> is inherited by +the corresponding B<X509_STORE_CTX> structure when it is initialized. This can +be used to set the verification callback when the B<X509_STORE_CTX> 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<X509_STORE_CTX_set_verify_cb(3)|X509_STORE_CTX_set_verify_cb(3)> +L<CMS_verify(3)|CMS_verify(3)> + +=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 <openssl/x509_vfy.h> + + 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<X509_VERIFY_PARAM> structure associated with +a certificate verification operation. + +The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring +it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete +description of values the B<flags> parameter can take. + +X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. + +X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. + +X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> +to B<purpose>. 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<param> to +B<trust>. + +X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to +B<t>. Normally the current time is used. + +X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled +by default) and adds B<policy> 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<policies>. Any existing +policy set is cleared. The B<policies> parameter can be B<NULL> to clear +an existing policy set. + +X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. +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<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf +certificate. An error occurs if a suitable CRL cannot be found. + +B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate +chain. + +B<X509_V_FLAG_IGNORE_CRITICAL> 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<WARNING> 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<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken +certificates and makes the verification strictly apply B<X509> rules. + +B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. + +B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default +no policy checking is peformed. Additional information is sent to the +verification callback relating to policy checking. + +B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and +B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any +policy> and B<inhibit policy mapping> flags respectively as defined in +B<RFC3280>. Policy checking is automatically enabled if any of these flags +are set. + +If B<X509_V_FLAG_NOTIFY_POLICY> 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<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set +they are enabled. + +If B<X509_V_FLAG_USE_DELTAS> ise set delta CRLs (if present) are used to +determine certificate status. If not set deltas are ignored. + +B<X509_V_FLAG_CHECK_SS_SIGNATURE> 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<X509_V_FLAG_CB_ISSUER_CHECK> flag enables debugging of certificate +issuer checks. It is B<not> 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<must> 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<X509_STORE>) constructed CRLs are not +maintained. + +If CRLs checking is enable CRLs are expected to be available in the +corresponding B<X509_STORE> 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<SSL_CTX> structure B<ctx>: + + 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<X509_verify_cert(3)|X509_verify_cert(3)> + +=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 <openssl/x509.h> + + 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<ctx>. A complete description of +the process is contained in the L<verify(1)|verify(1)> 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<ctx> 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<ctx> (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<x509.h> as opposed to most chain verification +functiosn which use B<x509_vfy.h>. + +=head1 SEE ALSO + +L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> + +=head1 HISTORY + +X509_verify_cert() is available in all versions of SSLeay and OpenSSL. + +=cut |