On 2009.10.13 at 15:25:19 +0200, Dr. Stephen Henson wrote: > > X509_STORE_CTX, X509_VERIFY_PARAM and X509_LOOKUP_hash_dir/X509_LOOKUP_file > > documents would follow. > > OK thanks. I'll have a look at that. > > I'll add some documentation for X509_VERIFY_PARAM myself when I have time (I'm > more familiar with it having written the stuff). >
Attached manual pages for X509_LOOKUP_ methods, X509_check_issued and X509_check_ca functions.
=pod =head1 NAME X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_load_cert_file, X509_load_crl_file, X509_load_cert_crl_file - Default OpenSSL certificate lookup methods =head1 SYNOPSIS #include <openssl/x509_vfy.h> X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); X509_LOOKUP_METHOD *X509_LOOKUP_file(void); int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); =head1 DESCRIPTION B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate lookup methods to use with B<X509_STORE>, provided by OpenSSL library. Users of the library typically do not need to create instanses of these methods manually, they would be created automatically by L<X509_STORE_load_locations(3)|X509_STORE_load_locations(3)> or L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> functions. Internally loading of certificates and CRLs is implemented via functions B<X509_load_cert_crl_file>, B<X509_load_cert_file> and B<X509_load_crl_file>. These functions support parameter I<type>, which can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified file into memory cache of B<X509_STORE> objects which given B<ctx> parameter is associated with. Functions B<X509_load_cert_file> and B<X509_load_crl_file> can load both PEM and DER formats depending of type value. Because DER format cannot contain more than one certificate or CRL object (while PEM can contain several concatenated PEM objects) B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to B<X509_load_cert_file>. Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions to load default certificate store file (see L<X509_STORE_set_default_paths>. Functions return number of objects loaded from file or 0 in case of error. Both methods support adding several certificate locations into one B<X509_STORE>. This page documents certificate store formats used by these methods and caching policy. =head2 FILE METHOD B<X509_LOOKUP_file> method loads entire set of certificates and CRLs into memory immediately when file name is passed to it. File format is ASCII text which contains concatenated PEM certificates and CRLs. This method should be used by applications which work with limited set of CAs. =head2 HASHED DIR METHOD B<X509_LOOKUP_hash_dir> is more sophisticated method, which loads certificates and CRLs on demand, but caches them in the memory once they are loaded. However, since OpenSSL 1.0.0beta1 it checks for newer CRLs upon each lookup, so if newer CRL would appear in the directory, it would be loaded. Directory should contain each certificate and CRL in the separate file in the PEM format, with file name derived from certificate subject (or CRL issuer) hash, as returned by L<X509_NAME_hash(3)|X509_NAME_hash(3)> function of with option B<-hash> of L<x509(1)|x509(1)> or L<crl(1)|crl(1)> command. This hash value is appended by suffix .I<N> for certificates and B<.r>I<N> for CRLs where I<N> is sequentual number among certificates with same hash value, so it is possible to have in the store several certificates with same subject or several CRLs with same issuer (and, for example, different validity period). When checking for new CRLs once one CRL for given hash value is loaded, hash_dir lookup method checks only for certificates with sequentual number greater than one of already cached CRL. Note that hash algorithm used for subject hashing is changed in OpenSSL 1.0, so all certificate stores have to be rehashed upon transitopn from 0.9.8 to 1.0.0. OpenSSL includes utility L<c_rehash(1)|c_rehash(1)> which creates symlinks with correct hashed names for all files with .pem suffix in the given directory. =head1 SEE ALSO L<pem(3)|pem(3)>, L<d2i_X509_bio(3)|d2i_X509_bio(3)>, L<X509_STORE_load_locations(3)|X509_STORE_load_locations(3)>, L<X509_STORE_add_lookup(3)|X609_store_add_lookup(3)>, L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, =cut
=pod =head1 NAME X509_check_issued - checks if certificate is issued by another certificate =head1 SYNOPSIS #include <openssl/x509v3.h> int X509_check_issued(X509 *issuer, X509 *subject); =head1 DESCRIPTION This function checks if certificate I<subject> was issued using CA certificate I<issuer>. This function takes into account not only matching of issuer field of I<subject> with subject field of I<issuer>, but also compares B<authorityKeyIdentifier> extension of I<subject> with B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier> present in the I<subject> certificate and checks B<keyUsage> field of I<issuer>. =head1 RETURN VALUE Function return B<X509_V_OK> if certificate I<subject> is issued by I<issuer> or some B<X509_V_ERR*> constant to indicate an error. =head1 SEE ALSO L<X509_verify_cert(3)|X509_verify_cert(3)>, L<X509_check_ca(3)|X509_check_ca(3)>, L<verify(1)|verify(1)> =cut
=pod =head1 NAME X509_check_ca - check if given certificate is CA certificate =head1 SYNOPSIS #include <openssl/x509v3.h> int X509_check_ca(X509 *cert); =head1 DESCRIPTION This function checks if given certificate is CA certificate (can be used to sign other certificates). =head1 RETURN VALUE Function return 0, if it is not CA certificate, 1 if it is proper X509v3 CA certificate with B<basicConstraints> extension CA:TRUE, 3, if it is selfsigned X509 v1 certificate, 4, if it is certificate with B<keyUsage> extension with bit B<keyCertSign> set, but without B<basicConstraints>, and 5 if it has outdated Netscape Certificate Type extension telling that it is CA certificate. Actually, any non-zero value means that this certificate could have been used to sign other certificates. =head1 SEE ALSO L<X509_verify_cert(3)|X509_verify_cert(3)>, L<X509_check_issued(3)|X509_check_issued(3)>, L<X509_check_purpose(3)|X509_check_purpose(3)> =cut
