diff --git a/apps/lib/s_cb.c b/apps/lib/s_cb.c index 4ae8d8a1b9214..a58945857d352 100644 --- a/apps/lib/s_cb.c +++ b/apps/lib/s_cb.c @@ -1377,8 +1377,10 @@ int ssl_load_stores(SSL_CTX *ctx, vfy = X509_STORE_new(); if (vfy == NULL) goto err; - if (vfyCAfile != NULL && !X509_STORE_load_file(vfy, vfyCAfile)) + if (vfyCAfile != NULL && !X509_STORE_load_file(vfy, vfyCAfile)) { + BIO_printf(bio_err, "Error loading trusted peer verification cert file %s\n", vfyCAfile); goto err; + } if (vfyCApath != NULL && !X509_STORE_load_path(vfy, vfyCApath)) goto err; if (vfyCAstore != NULL && !X509_STORE_load_store(vfy, vfyCAstore)) @@ -1393,8 +1395,10 @@ int ssl_load_stores(SSL_CTX *ctx, ch = X509_STORE_new(); if (ch == NULL) goto err; - if (chCAfile != NULL && !X509_STORE_load_file(ch, chCAfile)) + if (chCAfile != NULL && !X509_STORE_load_file(ch, chCAfile)) { + BIO_printf(bio_err, "Error loading trusted chain building cert file %s\n", chCAfile); goto err; + } if (chCApath != NULL && !X509_STORE_load_path(ch, chCApath)) goto err; if (chCAstore != NULL && !X509_STORE_load_store(ch, chCAstore)) diff --git a/apps/rehash.c b/apps/rehash.c index e6b12d36fb6f7..23da595b6da08 100644 --- a/apps/rehash.c +++ b/apps/rehash.c @@ -268,7 +268,7 @@ static int do_file(const char *filename, const char *fullpath, enum Hash h) if (sk_X509_INFO_num(inf) != 1) { BIO_printf(bio_err, "%s: warning: skipping %s, " - "it does not contain exactly one certificate or CRL\n", + "it seems not to contain exactly one certificate or CRL in PEM format\n", opt_getprog(), filename); /* This is not an error. */ goto end; diff --git a/apps/s_client.c b/apps/s_client.c index c90241be9a461..c714f5aca8525 100644 --- a/apps/s_client.c +++ b/apps/s_client.c @@ -1899,7 +1899,7 @@ int s_client_main(int argc, char **argv) vfyCApath, vfyCAfile, vfyCAstore, chCApath, chCAfile, chCAstore, crls, crl_download)) { - BIO_printf(bio_err, "Error loading locations for server cert verificationi and client cert chain building\n"); + BIO_printf(bio_err, "Error loading locations for server cert verification and client cert chain building\n"); ERR_print_errors(bio_err); goto end; } diff --git a/doc/man1/openssl-rehash.pod.in b/doc/man1/openssl-rehash.pod.in index 380ad6dd2a46f..79c8249728973 100644 --- a/doc/man1/openssl-rehash.pod.in +++ b/doc/man1/openssl-rehash.pod.in @@ -33,14 +33,14 @@ B =head1 DESCRIPTION -This command is generally equivalent to the external -script B, +This command is generally equivalent to the external script B, except for minor differences noted below. -B scans directories and calculates a hash value of -each F<.pem>, F<.crt>, F<.cer>, or F<.crl> -file in the specified directory list and creates symbolic links -for each file, where the name of the link is the hash value. +B scans directories and calculates a hash value for each +F<.pem>, F<.crt>, F<.cer>, or F<.crl> file in the specified directory list +that is in PEM format and contains exactly one certificate or CRL. +For each of these files, it creates a symbolic link with its name being the +hash value of the certificate subject name or CRL issuer name, respectively. (If the platform does not support symbolic links, a copy is made.) This command is useful as many programs that use OpenSSL require directories to be set up like this in order to find certificates. @@ -66,12 +66,12 @@ the period, like this: IBI. Multiple objects may have the same hash; they will be indicated by incrementing the I value. Duplicates are found by comparing the -full SHA-1 fingerprint. A warning will be displayed if a duplicate -is found. +full SHA-1 fingerprint of the certificate or CRL. +A warning will be displayed if a duplicate is found. -A warning will also be displayed if there are files that -cannot be parsed as either a certificate or a CRL or if -more than one such object appears in the file. +A warning will also be displayed if there are files with a recoginzed filename +extension that cannot be parsed as either a certificate or a CRL in PEM format +or contain more than one such object. =head2 Script Configuration @@ -85,8 +85,11 @@ a certificate or CRL: $OPENSSL x509 -hash -fingerprint -noout -in FILENAME $OPENSSL crl -hash -fingerprint -noout -in FILENAME -where I is the filename. It must output the hash of the -file on the first line, and the fingerprint on the second, +where I is the filename. It must output +for the certificate or CRL contained in the input file the +hash value of the certificate subject name or CRL issuer name, respectively, +on the first line, +and the fingerprint of the full certificate or CRL structure on the second line, optionally prefixed with some text and an equals sign. =head1 OPTIONS diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 49e632be51776..c7aa6a3198ccf 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -321,26 +321,32 @@ Limit verify output to only errors. =item B<-CAfile> I -A file in PEM format containing trusted CA certificates. +A file in PEM format containing one or more trusted CA certificates. +They are used as trust anchors when verifying the server's certificate unless +overridden by B<-verifyCAfile>, B<-verifyCApath>, or B<-verifyCAstore> options. +They are used as trust anchors when attempting +to build the client certificate chain provided to the server unless +overridden by B<-chainCAfile>, B<-chainCApath>, or B<-chainCAstore> options. =item B<-CApath> I -A directory with files in PEM format containing trusted CA certificates. +A directory with files in PEM format, each containing a trusted CA certificate +for the same purposes as specified with the B<-CAfile> option. This directory must be in "hash format", -see L for more information. +see L for more information. =item B<-CAstore> I -The URI of a store containing trusted CA certificates in PEM format. +The URI of a store containing trusted CA certificates in PEM format +for the same purposes as specified with the B<-CAfile> option. The URI may indicate a single certificate, as well as a collection of them. -With URIs in the C scheme, this acts as B<-CAfile> or -B<-CApath>, depending on if the URI indicates a directory or a -single file. -See L for more information on the C scheme. +With URIs in the C scheme, this is generally treated like B<-CApath> or +B<-CAfile>, depending on if the URI indicates a directory or a single file. +See L for more information on the C scheme. =item B<-verifyCAfile> I -A file in PEM format containing CA certificates +A file in PEM format containing one or more CA certificates to trust for verifying the server's certificate. =item B<-verifyCApath> I, B<-CApath> I @@ -355,14 +361,13 @@ see L for more information. URI of a store containing CA certificates. to trust for verifying the server's certificate. The URI may indicate a single certificate, as well as a collection of them. -With URIs in the C scheme, this acts as B<-verifyCAfile> or -B<-verifyCApath>, depending on if the URI indicates a directory or a -single file. +With URIs in the C scheme, this is generally treated like B<-CApath> or +B<-CAfile>, depending on if the URI indicates a directory or a single file. See L for more information on the C scheme. =item B<-chainCAfile> I -A file in PEM format containing trusted CA certificates to use +A file in PEM format containing one or more trusted CA certificates to use when attempting to build the client certificate chain provided to the server. =item B<-chainCApath> I @@ -377,9 +382,8 @@ see L for more information. The URI of a store containing trusted certificates to use when attempting to build the client certificate chain provided to the server. The URI may indicate a single certificate, as well as a collection of them. -With URIs in the C scheme, this acts as B<-chainCAfile> or -B<-chainCApath>, depending on if the URI indicates a directory or a -single file. +With URIs in the C scheme, this is generally treated like B<-CApath> or +B<-CAfile>, depending on if the URI indicates a directory or a single file. See L for more information on the C scheme. =item B<-requestCAfile> I diff --git a/doc/man1/openssl-verification-options.pod b/doc/man1/openssl-verification-options.pod index 38ae58d83defd..fa0495d85ed24 100644 --- a/doc/man1/openssl-verification-options.pod +++ b/doc/man1/openssl-verification-options.pod @@ -411,7 +411,8 @@ effect. =item B<-trusted> I -Parse I as a set of one or more certificates. +Parse I as a set of certificates. +When the file is in PEM format, it may contain multiple certificates. Each of them qualifies as trusted if has a suitable positive trust attribute or it is self-signed or the B<-partial_chain> option is specified. This option implies the B<-no-CAfile>, B<-no-CApath>, and B<-no-CAstore> options @@ -421,7 +422,8 @@ This option may be used multiple times. =item B<-untrusted> I -Parse I as a set of one or more certificates. +Parse I as a set of certificates. +When the file is in PEM format, it may contain multiple certificates. All certificates (typically of intermediate CAs) are considered untrusted and may be used to construct a certificate chain from the target certificate to a trust anchor. diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod index 3f54c1ef2c71c..be5134bce1b4e 100644 --- a/doc/man3/SSL_CTX_load_verify_locations.pod +++ b/doc/man3/SSL_CTX_load_verify_locations.pod @@ -31,7 +31,7 @@ SSL_CTX_load_verify_dir(), SSL_CTX_load_verify_file(), SSL_CTX_load_verify_store(), and SSL_CTX_load_verify_locations() specify the locations at which trusted CA certificates in PEM format are located. For details see the L below. -The SSL context B B be NULL. +The SSL context I B be NULL. Details of the certificate verification and chain checking process are described in L. @@ -49,7 +49,7 @@ The default CA certificates file is called F in the default OpenSSL directory. Alternatively the B environment variable can be defined to override this location. -B B be NULL. +I B be NULL. SSL_CTX_set_default_verify_dir() is similar to SSL_CTX_set_default_verify_paths() except that just the default directory is @@ -74,7 +74,7 @@ building the chain of the own client/server certificate unless overridden by L, L, L, or L. -If B is not NULL, it points to a file of CA certificates in PEM +If I is not NULL, it points to a file of CA certificates in PEM format. The file can contain several CA certificates identified by -----BEGIN CERTIFICATE----- @@ -84,41 +84,43 @@ format. The file can contain several CA certificates identified by sequences. Before, between, and after the certificates text is allowed which can be used e.g. for descriptions of the certificates. -The B is processed on execution of the SSL_CTX_load_verify_locations() +The I is processed on execution of the SSL_CTX_load_verify_locations() function. -If B is not NULL, it points to a directory containing CA certificates -in PEM format. The files each contain one CA certificate. The files are +If I is not NULL, it points to a directory containing CA certificates +in PEM format. The files each contain exactly one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available. -If more than one CA certificate with the same name hash value exist, the +If more than one CA certificate with the same subject name hash value exist, the extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in the ordering of the extension number, regardless of other properties of the certificates. -Use the B utility to create the necessary links. +Use the L utility to create the necessary links. -The certificates in B are only looked up when required, e.g. when -building the certificate chain or when actually performing the verification -of a peer certificate. +The certificate files in I are only looked up when required, e.g., when +building the certificate chain of the own client or server certificate +or when actually performing the verification of a peer certificate. When looking up CA certificates for chain building, the OpenSSL library -will search for suitable certificates first in B, then in B. +will search for suitable certificates first in I, then in I. Details of the chain building process are described in -L. +L. -If B is not NULL, it's a URI for to a store, which may +I must not be NULL. It must be a URI to a store, which may represent a single container or a whole catalogue of containers. -Apart from the B not necessarily being a local file or -directory, it's generally treated the same way as a B. +If I starts with the scheme C, it is treated like a local file +or directory. Apart from the I not necessarily being a local file or +directory, it's generally treated the same way as a I +if the store behaves like a directory, otherwise like I. In server mode, when requesting a client certificate, the server must send the list of CAs of which it will accept client certificates. This list -is not influenced by the contents of B or B and must +is not influenced by the contents of I or I and must explicitly be set using the L family of functions. When building its own certificate chain, an OpenSSL client/server will -try to fill in missing certificates from B/B, if the +try to fill in missing certificates from I/I, if the certificate chain was not explicitly specified (see L, L. @@ -140,7 +142,7 @@ For SSL_CTX_load_verify_locations the following return values can occur: =item Z<>0 -The operation failed because B and B are NULL or the +The operation failed because I and I are NULL or the processing at one of the locations specified failed. Check the error stack to find out the reason. @@ -166,13 +168,13 @@ ca1.pem ca2.pem ca3.pem: done Prepare the directory /some/where/certs containing several CA certificates -for use as B: +for use as I: - cd /some/where/certs - c_rehash . + openssl rehash /some/where/certs =head1 SEE ALSO +L, L, L, L, diff --git a/doc/man3/SSL_CTX_set1_verify_cert_store.pod b/doc/man3/SSL_CTX_set1_verify_cert_store.pod index 5826eef608dff..8a1ed975d55ac 100644 --- a/doc/man3/SSL_CTX_set1_verify_cert_store.pod +++ b/doc/man3/SSL_CTX_set1_verify_cert_store.pod @@ -32,13 +32,13 @@ verification or chain store SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store() set the certificate store used for peer certificate verification to B. -The override for this purpose any locations set by +They override for this purpose any locations set by L, L, L, L, etc. SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() set the cert store for building the chain of the own client/server certificate to B. -The override for this purpose any locations set by +They override for this purpose any locations set by L, L, L, L, etc. diff --git a/doc/man3/X509_LOOKUP.pod b/doc/man3/X509_LOOKUP.pod index de4eca7fdad72..ca4f83472b463 100644 --- a/doc/man3/X509_LOOKUP.pod +++ b/doc/man3/X509_LOOKUP.pod @@ -123,10 +123,16 @@ I indicates what type of object is expected. This can only be used with a lookup using the implementation L. -X509_LOOKUP_add_store_ex() passes a URI for a directory-like structure -from which containers with certificates and CRLs are loaded on demand +X509_LOOKUP_add_store_ex() passes a URI for a directory-like or file-like +structure from which containers with certificates and CRLs are loaded on demand into the associated B. The library context I and property query I are used when fetching algorithms from providers. +If I is not NULL, it must be a URI to a store, which may +represent a single container or a whole catalogue of containers. +If I starts with the scheme C, it is treated like a local file +or directory. Apart from the I not necessarily being a local file or +directory, the function behaves generally like X509_LOOKUP_add_dir() if +the store is a directory, otherwise like X509_LOOKUP_load_file_ex(). X509_LOOKUP_add_store() is similar to X509_LOOKUP_add_store_ex() but uses NULL for the library context I and property query I. diff --git a/doc/man3/X509_LOOKUP_hash_dir.pod b/doc/man3/X509_LOOKUP_hash_dir.pod index 22a599692549f..8878032660b4c 100644 --- a/doc/man3/X509_LOOKUP_hash_dir.pod +++ b/doc/man3/X509_LOOKUP_hash_dir.pod @@ -80,7 +80,7 @@ set of CAs. B is a more advanced method, which loads certificates and CRLs on demand, and caches them in memory once -they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs +they are loaded. It also checks for newer CRLs upon each lookup, so that newer CRLs are as soon as they appear in the directory. @@ -109,12 +109,8 @@ When checking for new CRLs once one CRL for given hash value is loaded, hash_dir lookup method checks only for certificates with sequence number greater than that of the already cached CRL. -Note that the hash algorithm used for subject name hashing changed in OpenSSL -1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL -0.9.8 to 1.0.0. - OpenSSL includes a L utility which creates symlinks with -hashed names for all files with F<.pem> suffix in a given directory. +hashed names for all files with suffix like F<.pem> in a given directory. =head2 OSSL_STORE Method @@ -140,6 +136,7 @@ the number of loaded objects or 0 on error. =head1 SEE ALSO +L, L, L, L, @@ -148,6 +145,9 @@ L =head1 HISTORY +The hash algorithm used for subject name hashing changed in OpenSSL 1.0.0. All +certificate stores had to be rehashed when moving from OpenSSL 0.9.8 to 1.0.0. + The functions X509_load_cert_file_ex(), X509_load_cert_crl_file_ex() and X509_LOOKUP_store() were added in OpenSSL 3.0. diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod index 0075ffc33dff7..f6516eaca311b 100644 --- a/doc/man3/X509_STORE_add_cert.pod +++ b/doc/man3/X509_STORE_add_cert.pod @@ -102,14 +102,24 @@ query I are used when fetching algorithms from providers. X509_STORE_load_file() is similar to X509_STORE_load_file_ex() but uses NULL for the library context I and property query I. -X509_STORE_load_path() loads trusted certificate(s) into an -B from a given directory with files in PEM format. +X509_STORE_load_path() sets in B the given directory with +certificate files in PEM format as source of trusted certificate(s). +The certificate files in B are only looked up when required, e.g., when +building the certificate chain or when actually performing the verification +of a peer certificate. The certificates in the directory must be in hashed form, as documented in L. +Use the L utility to create the necessary links. X509_STORE_load_store_ex() loads trusted certificate(s) into an B from a store in PEM format at a given URI. The library context I and property query I are used when fetching algorithms from providers. +I must not be NULL. It must be a URI to a store, which may +represent a single container or a whole catalogue of containers. +If I starts with the scheme C, it is treated like a local file +or directory. Apart from the I not necessarily being a local file or +directory, the function behaves generally like X509_STORE_load_path() if the +store is a directory, otherwise like X509_STORE_load_file_ex(). X509_STORE_load_store() is similar to X509_STORE_load_store_ex() but uses NULL for the library context I and property query I. @@ -148,8 +158,9 @@ L, or NULL on error. =head1 SEE ALSO -L. -L. +L, +L, +L, L, L