On 2009.10.13 at 14:12:22 +0200, Dr. Stephen Henson wrote:
> On Tue, Oct 13, 2009, Victor B. Wagner wrote:
>
> > On 2009.10.12 at 19:00:30 +0200, Dr. Stephen Henson wrote:
> >
> > >
> > > Well we are in the middle of a beta relase cycle so making incompatible
> > > changes and/or major new functionality isn't an option.
> >
> > Is this (#2) a major new functionality, given that cache field in
> > X509_CTX is already here and applications rely on it?
> >
>
> If it breaks existing applications yes, if it is a bugfix no. I think in this
> case it is arguably "fixing" something which is broken so it could come under
> that.
It shouldn't break existing applications, which do not care about cache
field, because X509_STORE_new
initializes it to 1 (may be change it to 0xfffffff for future
use of bitfield just now).
It would probably fix stunnel, which sets cache for CRL store to 0 and
expects CRLs to be reloaded.
> I'd suggest using a bitfield in this case but you need rather more flags than
> just each type of object. For example some application which need to verify
> certificates at times in the past might want to keep expired objects around.
So, we have at least two flags for each type of object
1 << X509_LU_whaterver
and X509_LU_KEEP_EXPIRED << X509_LU_whatever
> Although applications don't use X509_STORE_CTX directly they do use it and
> related APIs indirectly and some understading of how these structures interact
> would help.
Of course.
> In that vein we'd need to document X509_STORE_CTX, X509_verify_cert() and
> X509_VERIFY_PARAM (and related functions). Some of this could just copy and
> paste or point to some existing documentation for the verify utility.
Now I'm attaching a pod file which documents parts of X509_STORE API
which is needed to initialize X509_STORE for verifying PKCS7/CMS/TS_response
and altering behavoir of SSL_CTX certificate validation, because I've
already written it.
X509_STORE_CTX, X509_VERIFY_PARAM and X509_LOOKUP_hash_dir/X509_LOOKUP_file
documents would follow.
=pod
=head1 NAME
X509_STORE_new, X509_STORE_free,
X509_STORE_load_locations,
X509_STORE_set_default_paths,
X509_STORE_add_cert,
X509_STORE_add_crl,
X509_verify_cert,
X509_STORE_add_lookup,
X509_STORE_set_flags,
X509_STORE_set_purpose,
X509_STORE_set_depth,
X509_STORE_set1_param
X509_STORE_set_verify_cb_func,
X509_STORE_set_trust - manipulate trusted certificate store
=head1 SYNOPSIS
#include <openssl/x509_vfy.h>
X509_STORE *X509_STORE_new();
void X509_STORE_free(X509_STORE *store);
int X509_STORE_load_locations (X509_STORE *store, const char *file,
const char *dir);
int X509_store_set_default_paths(X509_STORE *store);
int X509_STORE_add_cert(X509_STORE *store, X509 *cert);
X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store,
X509_LOOKUP_METHOD *m);
int X509_STORE_add_crl(X509_STORE *store, X509_CRL *crl);
int X509_STORE_set1_param(X509_STORE *store, X509_VERIFY_PARAM *param);
int X509_STORE_set_flags(X509_STORE *store, unsigned long flags);
int X509_STORE_set_purpose(X509_STORE *store, int purpose);
int X509_STORE_set_trust(X509_STORE *store, int trust);
int X509_STORE_set_depth(X509_STORE *store, int depth);
X509_STORE_set_verify_cb_func(X509_STORE *store, int (*verify_cb)(int
ok, X509_STORE_CTX *ctx))
=head1 DESCRIPTION
B<X509_STORE> structure holds information, neccessary for certificate
verification process. This information include set of trusted CA
certificates and corresponding CRLs, various flags modifying
verification process and additional information such as required
certificate purpose and policy.
This structure can be passed to L<PKCS7_verify(3)|PKCS7_verify(#)>
and L<CMS_verify(3)|CMS_verify(3)> functions. When SSL_CTX is created, it
creates
B<X509_STORE> internally. This store can be obtained using
L<SSL_CTX_get_cert_store(3)|SSL_CTX_get_cert_store(3)> function and its
behavoir modified by setting
flags and other verification parameters. It is also possible to replace
internally created B<X509_STORE> by custom one using
L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(#)>.
B<X509_STORE> doesn't neccessary hold all trusted certificates and CRLs
in itself. There is flexible mechanism of B<X509_LOOKUP_METHODS> which
allows to implement own certificate storage, for example with relational
database backend or LDAP. OpenSSL implements two simple lookup methods:
L<X509_LOOKUP_file(3)|X509_LOOKUP_file(3)> and
L<X509_LOOKUP_hash_dir(3)|X509_LOOKUP_hash_dir(3)>. Users typically don't
need to create instances of these lookup methods explicitely. They are
created in the B<X509_STORE_load_locations> (or
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>).
Actual certificate verification, lookup and chain building is performed
by B<X509_STORE_CTX> object, which is created based on B<X509_STORE>
object. Unless application need to check certificates and CRLs by its
own, it doesn't need to create B<X509_STORE_CTX>, it would be created
internally by SSL or PKCS7/CMS API functions.
=head2 CREATING X509_STORE AND SETTING LOCATIONS AND CALLBACKS
Typically SSL applications do not create B<X509_STORE> explicitely,
because it is created implicitely by libssl, and libssl provides own API
to do basic initialization of B<X509_STORE>.
But applications which use L<PKCS7_verify(3)|PKCS7_verify(3)> or
L<CMS_verify(3)|CMS_verify(3)> have to do
it manually, because these functions expect to receive ready to use
B<X509_STORE>.
Function B<X509_STORE_new> creates new empty certificate store. Before
this store can be used for certificate verification, some lookup methods
and locations should be added. After use object should be freed by
B<X509_STORE_free> function.
B<X509_STORE_set_default_paths> sets default (compiled into OpenSSL)
locations for certificaate validation (typically these locations include
I<$OPENSSLDIR>B</certs> directory and I<$OPENSSLDIR>B</cert.pem> file.
Function L<SSL_CTX_set_default_verify_paths> does the same for
B<X509_STORE> inside B<SSL_CTX> structure.
In many cases using default store is considered security flaw.
Typically, default certificate store contains certificates for all
well-known public CA, as provided by operating system vendor. So, for
client applications, such as web browsers, using default system store is
good idea, but for server applications probably not.
B<X509_STORE_load_locations> function adds explicitely specified
directory and/or file with certificates, adding corresponding lookup
method instances if neccessary. If B<dir> argument is not NULL, it
should point to directory with hashed certificates (see
L<c_rehash(1)|c_rehash(1)>
manual page). If B<file> argument is not NULL, it should be ASCII file,
containing several concatenated certificates and/or CRLs in the PEM
format.
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> does same
for SSL_CTX.
B<X509_STORE_add_cert> and B<X509_STORE_add_crl> add certificate or CRL
to B<X509_STORE> explicitely.
B<X509_STORE_add_lookup> creates instance of given B<X509_LOOKUP_METHOD>
and adds it to X509_STORE, returning pointer to this instance. This
function is typically used only by applications, which implement their
own custom X509_LOOKUP methods.
Macro B<X509_STORE_set_verify_cb_func>, sets default verify callback
function for X509_STORE, which is inherited by X509_STORE_CTX.
Applications, which uses SSL library should never use this macro and use
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)> instead. Applications, which
create
B<X509_STORE_CTX> manually, should also never use this macro, use
L<X509_STORE_CTX_set_verify_cb(3)|X509_STORE_CTX_set_verify_cb(3)> instead.
But for PKCS7/CMS applications this macro
is only way to provide application-based certificate validation
callback.
Callback function receives two arguments: integer flag B<ok> which is
non-zero if certificate passed all built-in checks or 0 if something wrong with
this certificate, and B<X509_STORE_CTX> structure, which contains
certificate being validated and error message if any.
If this function returns 0, certificate considered rejected, and if it
returns 1, it is accepted, even if B<ok> parameter on entry was 0.
Value of B<ok> equal to 2 means that callback is called to notify that
policy check succeeds. In this case currentcert field in the
B<X509_STORE_CTX> is set to NULL. Callback might do additional checks and
return 0 if something is wrong.
B<X509_STORE_set_verify_depth> limit length of the certificate chain to
given depth. See also
L<SSL_CTX_set_verify_depth(3)|SSL_CTX_set_verify_depth(3)> and
L<X509_STORE_CTX_set_depth(3)|X509_STORE_CTX_set_depth(3)>.
=head2 MODIFYING CERTIFICATE VERIFICATION BEHAVOIR
Function B<X509_STORE_set_purpose> set certificate purpose, acceptable
for given certificate validation process. Typically applications don't
need to use this function explicitely, because both SSL and PKCS7/CMS
routines set purpose internally. Purpose is passed to this function
using one of B<X509_PURPOSE*> constants, defined in the B<x509v3.h> or
using return value of
L<X509_PURPOSE_get_by_sname(3)|X509_PURPOSE_get_by_sname(3)> function.
Function B<X509_STORE_set_trust> sets trust (I don't know why it is
needed)
Function B<X509_STORE_set1_param> replaces verification parameters
(possibly altered by other functions described in this page, by
copy of the passed B<X509_VERIFY_PARAM> structure. See
L<X509_VERIFY_PARAM_new(3)|X509_VERIFY_PARAM_new(3)>.
Creating and setting this structure is only way to set check time and
policy list to the B<X509_STORE> object, although X509_STORE_CTX
provides its own API to set these parameters.
Function B<X509_STORE_set_flags> sets various flags, affecting
verification process. Most of these flags corresponds to command-line
options of L<verify> command. Parameter I<flags> is OR-ed combination of
folowing constant
=over 4
=item B<X509_V_FLAG_CB_ISSUER_CHECK>
Calls verify callback for some issuer+subject checks.
=item B<X509_V_FLAG_USE_CHECK_TIME>
Use check time stored in the B<X509_STORE_CTX> object instead of current
time when verifying certificate validity period. This flag makes no
sense during SSL handshake, because only current time matters.
When check time is applicable, (for example checking if signature of
some archived message was valid at the time of message signing),
L<X509_VERIFY_PARAM_set_time(3)|X509_VERIFY_PARAM_set_time(3)>.
=item B<X509_V_FLAG_CRL_CHECK>
Turns on lookup of the verified certificate in the CRL. If this flag is
set and certificate store contains no CRL for the issuer of checked
certificate, or contains outdated CRL, check would fail.
=item B<X509_V_FLAG_CRL_CHECK_ALL>
Lookup all certificates in the chain (not only verified cert, but all
intermediate CA certificates and root certificate itself) in the
corresponding CRL.
=item B<X509_V_FLAG_IGNORE_CRITICAL>
Do not fail if some certificate or CRL in the chain contains critical
extension, unknow to OpenSSL. This is very dangerous option because this
critical extension can mark issuer certificate as irrelevant to given
case or mark CRL as too narrow. So, turn it on only if your are
absolutely sure why your CA put particular unparsable critical extension in
the certificate/CRL and you are not verifying certificates issued by
public CA.
=item B<X509_V_FLAG_X509_STRICT>
By default OpenSSL uses some hacks to handle certificates, issued by
broken CAs. This option turns these hacks of and require strict
compilance of the checked certificates to X509 standard.
=item B<X509_V_FLAG_ALLOW_PROXY_CERTS>
Allow proxy certificates in the chain. If software doesn't allow users
to pass this flag to the library, users can use environment variable
B<OPENSSL_ALLOW_PROXY_CERTS> instead.
=item B<X509_V_FLAG_POLICY_CHECK>
Enables policy checking. Required policy should be added to the
verification parameters using
L<X509_VERIFY_PARAM_add0_policy(3)|X509_VERIFY_PARAM_add0_policy(3)>
=item B<X509_V_FLAG_EXPLICIT_POLICY>
Set policy variable require-explicit-policy (see RFC3280 et al).
=item B<X509_V_FLAG_INHIBIT_ANY>
Set policy variable inhibit-any-policy (see RFC3280 et al)
=item B<X509_V_FLAG_INHIBIT_MAP>
Set policy variable inhibit-policy-mapping (see RFC3280 et al)
=item B<X509_V_FLAG_NOTIFY_POLICY>
If this flag is set, certificate verification procedure would call
verify callback with ok value equal to 2 if policy check succeeds.
=item B<X509_V_FLAG_POLICY_MASK>
OR-ed combination of all policy-related flags.
=back
B<X509_STORE-E<gt>cache> field. This field is boolean flag, which
controls memory caching of the certificates and CRLs by default lookup
method B<X509_LOOKUP_hash_dir>. It is set to 1 (caching is enabled) upon
B<X509_STORE_new>, but
applications, which wants trusted certificates and CRLs to be reloaded from
disk any time when verification is performed, can set it to 1.
=head1 SEE ALSO
L<X509_verify_cert(3)|X509_verify_cert(3)>,
L<X509_STORE_CTX_new(3)|X509_STORE_CTX_new(3)>,
L<X509_VERIFY_PARAM_new(3)|X509_VERIFY_PARAM_new(3)>,
L<X509_LOOKUP_hash_dir(3)>,
L<X509_LOOKUP_file(3)>,
L<SSL_CTX_get_cert_store(3)|SSL_CTX_get_cert_store(3)>,
L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>,
L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
=cut
