211 lines
8.8 KiB
HTML
Executable File
211 lines
8.8 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>SSL_CTX_load_verify_locations</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#warnings">WARNINGS</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>SSL_CTX_load_verify_dir, SSL_CTX_load_verify_file,
|
|
SSL_CTX_load_verify_store, SSL_CTX_set_default_verify_paths,
|
|
SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file,
|
|
SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations
|
|
- set default locations for trusted CA certificates</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
int SSL_CTX_load_verify_dir(SSL_CTX *ctx, const char *CApath);
|
|
int SSL_CTX_load_verify_file(SSL_CTX *ctx, const char *CAfile);
|
|
int SSL_CTX_load_verify_store(SSL_CTX *ctx, const char *CAstore);</pre>
|
|
<pre>
|
|
int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);</pre>
|
|
<pre>
|
|
int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
|
|
int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
|
|
int SSL_CTX_set_default_verify_store(SSL_CTX *ctx);</pre>
|
|
<p>Deprecated since OpenSSL 3.0, can be hidden entirely by defining
|
|
<strong>OPENSSL_API_COMPAT</strong> with a suitable version value, see
|
|
<em>openssl_user_macros(7)</em>:</p>
|
|
<pre>
|
|
int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
|
|
const char *CApath);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p><code>SSL_CTX_load_verify_dir()</code>, <code>SSL_CTX_load_verify_file()</code>,
|
|
<code>SSL_CTX_load_verify_store()</code> specifies the locations for <strong>ctx</strong>, at
|
|
which CA certificates for verification purposes are located. The
|
|
certificates available via <strong>CAfile</strong>, <strong>CApath</strong> and <strong>CAstore</strong> are
|
|
trusted.</p>
|
|
<p><code>SSL_CTX_set_default_verify_paths()</code> specifies that the default locations from
|
|
which CA certificates are loaded should be used. There is one default directory,
|
|
one default file and one default store.
|
|
The default CA certificates directory is called <em class="file">certs</em> in the default OpenSSL
|
|
directory, and this is also the default store.
|
|
Alternatively the <strong>SSL_CERT_DIR</strong> environment variable can be defined to
|
|
override this location.
|
|
The default CA certificates file is called <em class="file">cert.pem</em> in the default
|
|
OpenSSL directory.
|
|
Alternatively the <strong>SSL_CERT_FILE</strong> environment variable can be defined to
|
|
override this location.</p>
|
|
<p><code>SSL_CTX_set_default_verify_dir()</code> is similar to
|
|
<code>SSL_CTX_set_default_verify_paths()</code> except that just the default directory is
|
|
used.</p>
|
|
<p><code>SSL_CTX_set_default_verify_file()</code> is similar to
|
|
<code>SSL_CTX_set_default_verify_paths()</code> except that just the default file is
|
|
used.</p>
|
|
<p><code>SSL_CTX_set_default_verify_store()</code> is similar to
|
|
<code>SSL_CTX_set_default_verify_paths()</code> except that just the default store is
|
|
used.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>If <strong>CAfile</strong> is not NULL, it points to a file of CA certificates in PEM
|
|
format. The file can contain several CA certificates identified by</p>
|
|
<pre>
|
|
-----BEGIN CERTIFICATE-----
|
|
... (CA certificate in base64 encoding) ...
|
|
-----END CERTIFICATE-----</pre>
|
|
<p>sequences. Before, between, and after the certificates text is allowed
|
|
which can be used e.g. for descriptions of the certificates.</p>
|
|
<p>The <strong>CAfile</strong> is processed on execution of the <code>SSL_CTX_load_verify_locations()</code>
|
|
function.</p>
|
|
<p>If <strong>CApath</strong> is not NULL, it points to a directory containing CA certificates
|
|
in PEM format. The files each contain 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
|
|
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 <strong>c_rehash</strong> utility to create the necessary links.</p>
|
|
<p>The certificates in <strong>CApath</strong> are only looked up when required, e.g. when
|
|
building the certificate chain or when actually performing the verification
|
|
of a peer certificate.</p>
|
|
<p>When looking up CA certificates, the OpenSSL library will first search the
|
|
certificates in <strong>CAfile</strong>, then those in <strong>CApath</strong>. Certificate matching
|
|
is done based on the subject name, the key identifier (if present), and the
|
|
serial number as taken from the certificate to be verified. If these data
|
|
do not match, the next certificate will be tried. If a first certificate
|
|
matching the parameters is found, the verification process will be performed;
|
|
no other certificates for the same parameters will be searched in case of
|
|
failure.</p>
|
|
<p>If <strong>CAstore</strong> is not NULL, it's a URI for to a store, which may
|
|
represent a single container or a whole catalogue of containers.
|
|
Apart from the <strong>CAstore</strong> not necessarily being a local file or
|
|
directory, it's generally treated the same way as a <strong>CApath</strong>.</p>
|
|
<p>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 <strong>CAfile</strong> or <strong>CApath</strong> and must
|
|
explicitly be set using the
|
|
<em>SSL_CTX_set_client_CA_list(3)</em>
|
|
family of functions.</p>
|
|
<p>When building its own certificate chain, an OpenSSL client/server will
|
|
try to fill in missing certificates from <strong>CAfile</strong>/<strong>CApath</strong>, if the
|
|
certificate chain was not explicitly specified (see
|
|
<em>SSL_CTX_add_extra_chain_cert(3)</em>,
|
|
<em>SSL_CTX_use_certificate(3)</em>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="warnings">WARNINGS</a></h1>
|
|
<p>If several CA certificates matching the name, key identifier, and serial
|
|
number condition are available, only the first one will be examined. This
|
|
may lead to unexpected results if the same CA certificate is available
|
|
with different expiration dates. If a "certificate expired" verification
|
|
error occurs, no other certificate will be searched. Make sure to not
|
|
have expired certificates mixed with valid ones.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>For SSL_CTX_load_verify_locations the following return values can occur:</p>
|
|
<ol>
|
|
<li>
|
|
<p>The operation failed because <strong>CAfile</strong> and <strong>CApath</strong> are NULL or the
|
|
processing at one of the locations specified failed. Check the error
|
|
stack to find out the reason.</p>
|
|
</li>
|
|
<li>
|
|
<p>The operation succeeded.</p>
|
|
</li>
|
|
</ol>
|
|
<p><code>SSL_CTX_set_default_verify_paths()</code>, <code>SSL_CTX_set_default_verify_dir()</code> and
|
|
<code>SSL_CTX_set_default_verify_file()</code> all return 1 on success or 0 on failure. A
|
|
missing default location is still treated as a success.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Generate a CA certificate file with descriptive text from the CA certificates
|
|
ca1.pem ca2.pem ca3.pem:</p>
|
|
<pre>
|
|
#!/bin/sh
|
|
rm CAfile.pem
|
|
for i in ca1.pem ca2.pem ca3.pem ; do
|
|
openssl x509 -in $i -text >> CAfile.pem
|
|
done</pre>
|
|
<p>Prepare the directory /some/where/certs containing several CA certificates
|
|
for use as <strong>CApath</strong>:</p>
|
|
<pre>
|
|
cd /some/where/certs
|
|
c_rehash .</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ssl(7)</em>,
|
|
<em>SSL_CTX_set_client_CA_list(3)</em>,
|
|
<em>SSL_get_client_CA_list(3)</em>,
|
|
<em>SSL_CTX_use_certificate(3)</em>,
|
|
<em>SSL_CTX_add_extra_chain_cert(3)</em>,
|
|
<em>SSL_CTX_set_cert_store(3)</em>,
|
|
<em>SSL_CTX_set_client_CA_list(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|