Document additions for X509 chain verification from HEAD
This commit is contained in:
Dr. Stephen Henson
parent
c90a1ae0c9
commit
5b2b60ae98
@ -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,
|
||||
|
||||
303
doc/crypto/X509_STORE_CTX_get_error.pod
Normal file
303
doc/crypto/X509_STORE_CTX_get_error.pod
Normal file
@ -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
|
||||
41
doc/crypto/X509_STORE_CTX_get_ex_new_index.pod
Normal file
41
doc/crypto/X509_STORE_CTX_get_ex_new_index.pod
Normal file
@ -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
|
||||
122
doc/crypto/X509_STORE_CTX_new.pod
Normal file
122
doc/crypto/X509_STORE_CTX_new.pod
Normal file
@ -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
|
||||
161
doc/crypto/X509_STORE_CTX_set_verify_cb.pod
Normal file
161
doc/crypto/X509_STORE_CTX_set_verify_cb.pod
Normal file
@ -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
|
||||
54
doc/crypto/X509_STORE_set_verify_cb_func.pod
Normal file
54
doc/crypto/X509_STORE_set_verify_cb_func.pod
Normal file
@ -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
|
||||
171
doc/crypto/X509_VERIFY_PARAM_set_flags.pod
Normal file
171
doc/crypto/X509_VERIFY_PARAM_set_flags.pod
Normal file
@ -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
|
||||
53
doc/crypto/X509_verify_cert.pod
Normal file
53
doc/crypto/X509_verify_cert.pod
Normal file
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user