183 lines
9.0 KiB
HTML
183 lines
9.0 KiB
HTML
|
<?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_add1_chain_cert</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="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#history">HISTORY</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_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
|
||
|
SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
|
||
|
SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
|
||
|
SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
|
||
|
SSL_build_cert_chain, SSL_CTX_select_current_cert,
|
||
|
SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra
|
||
|
chain certificate processing</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/ssl.h></pre>
|
||
|
<pre>
|
||
|
int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
|
||
|
int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
|
||
|
int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
|
||
|
int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
|
||
|
int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
|
||
|
int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);</pre>
|
||
|
<pre>
|
||
|
int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
|
||
|
int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
|
||
|
int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
|
||
|
int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
|
||
|
int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
|
||
|
int SSL_clear_chain_certs(SSL *ssl);</pre>
|
||
|
<pre>
|
||
|
int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
|
||
|
int SSL_build_cert_chain(SSL *ssl, flags);</pre>
|
||
|
<pre>
|
||
|
int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
|
||
|
int SSL_select_current_cert(SSL *ssl, X509 *x509);
|
||
|
int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
|
||
|
int SSL_set_current_cert(SSL *ssl, long op);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p>SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain
|
||
|
associated with the current certificate of <strong>ctx</strong> to <strong>sk</strong>.</p>
|
||
|
<p>SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single
|
||
|
certificate <strong>x509</strong> to the chain associated with the current certificate of
|
||
|
<strong>ctx</strong>.</p>
|
||
|
<p>SSL_CTX_get0_chain_certs() retrieves the chain associated with the current
|
||
|
certificate of <strong>ctx</strong>.</p>
|
||
|
<p><code>SSL_CTX_clear_chain_certs()</code> clears any existing chain associated with the
|
||
|
current certificate of <strong>ctx</strong>. (This is implemented by calling
|
||
|
SSL_CTX_set0_chain() with <strong>sk</strong> set to <strong>NULL</strong>).</p>
|
||
|
<p><code>SSL_CTX_build_cert_chain()</code> builds the certificate chain for <strong>ctx</strong> normally
|
||
|
this uses the chain store or the verify store if the chain store is not set.
|
||
|
If the function is successful the built chain will replace any existing chain.
|
||
|
The <strong>flags</strong> parameter can be set to <strong>SSL_BUILD_CHAIN_FLAG_UNTRUSTED</strong> to use
|
||
|
existing chain certificates as untrusted CAs, <strong>SSL_BUILD_CHAIN_FLAG_NO_ROOT</strong>
|
||
|
to omit the root CA from the built chain, <strong>SSL_BUILD_CHAIN_FLAG_CHECK</strong> to
|
||
|
use all existing chain certificates only to build the chain (effectively
|
||
|
sanity checking and rearranging them if necessary), the flag
|
||
|
<strong>SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR</strong> ignores any errors during verification:
|
||
|
if flag <strong>SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR</strong> is also set verification errors
|
||
|
are cleared from the error queue.</p>
|
||
|
<p>Each of these functions operates on the <em>current</em> end entity
|
||
|
(i.e. server or client) certificate. This is the last certificate loaded or
|
||
|
selected on the corresponding <strong>ctx</strong> structure.</p>
|
||
|
<p><code>SSL_CTX_select_current_cert()</code> selects <strong>x509</strong> as the current end entity
|
||
|
certificate, but only if <strong>x509</strong> has already been loaded into <strong>ctx</strong> using a
|
||
|
function such as <code>SSL_CTX_use_certificate()</code>.</p>
|
||
|
<p>SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(),
|
||
|
SSL_add1_chain_cert(), SSL_get0_chain_certs(), <code>SSL_clear_chain_certs()</code>,
|
||
|
<code>SSL_build_cert_chain()</code>, <code>SSL_select_current_cert()</code> and <code>SSL_set_current_cert()</code>
|
||
|
are similar except they apply to SSL structure <strong>ssl</strong>.</p>
|
||
|
<p><code>SSL_CTX_set_current_cert()</code> changes the current certificate to a value based
|
||
|
on the <strong>op</strong> argument. Currently <strong>op</strong> can be <strong>SSL_CERT_SET_FIRST</strong> to use
|
||
|
the first valid certificate or <strong>SSL_CERT_SET_NEXT</strong> to set the next valid
|
||
|
certificate after the current certificate. These two operations can be
|
||
|
used to iterate over all certificates in an <strong>SSL_CTX</strong> structure.</p>
|
||
|
<p><code>SSL_set_current_cert()</code> also supports the option <strong>SSL_CERT_SET_SERVER</strong>.
|
||
|
If <strong>ssl</strong> is a server and has sent a certificate to a connected client
|
||
|
this option sets that certificate to the current certificate and returns 1.
|
||
|
If the negotiated cipher suite is anonymous (and thus no certificate will
|
||
|
be sent) 2 is returned and the current certificate is unchanged. If <strong>ssl</strong>
|
||
|
is not a server or a certificate has not been sent 0 is returned and
|
||
|
the current certificate is unchanged.</p>
|
||
|
<p>All these functions are implemented as macros. Those containing a <strong>1</strong>
|
||
|
increment the reference count of the supplied certificate or chain so it must
|
||
|
be freed at some point after the operation. Those containing a <strong>0</strong> do
|
||
|
not increment reference counts and the supplied certificate or chain
|
||
|
<strong>MUST NOT</strong> be freed after the operation.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="notes">NOTES</a></h1>
|
||
|
<p>The chains associate with an SSL_CTX structure are copied to any SSL
|
||
|
structures when <code>SSL_new()</code> is called. SSL structures will not be affected
|
||
|
by any chains subsequently changed in the parent SSL_CTX.</p>
|
||
|
<p>One chain can be set for each key type supported by a server. So, for example,
|
||
|
an RSA and a DSA certificate can (and often will) have different chains.</p>
|
||
|
<p>The functions <code>SSL_CTX_build_cert_chain()</code> and <code>SSL_build_cert_chain()</code> can
|
||
|
be used to check application configuration and to ensure any necessary
|
||
|
subordinate CAs are sent in the correct order. Misconfigured applications
|
||
|
sending incorrect certificate chains often cause problems with peers.</p>
|
||
|
<p>For example an application can add any set of certificates using
|
||
|
<code>SSL_CTX_use_certificate_chain_file()</code> then call <code>SSL_CTX_build_cert_chain()</code>
|
||
|
with the option <strong>SSL_BUILD_CHAIN_FLAG_CHECK</strong> to check and reorder them.</p>
|
||
|
<p>Applications can issue non fatal warnings when checking chains by setting
|
||
|
the flag <strong>SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS</strong> and checking the return
|
||
|
value.</p>
|
||
|
<p>Calling <code>SSL_CTX_build_cert_chain()</code> or <code>SSL_build_cert_chain()</code> is more
|
||
|
efficient than the automatic chain building as it is only performed once.
|
||
|
Automatic chain building is performed on each new session.</p>
|
||
|
<p>If any certificates are added using these functions no certificates added
|
||
|
using <code>SSL_CTX_add_extra_chain_cert()</code> will be used.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>SSL_set_current_cert()</code> with <strong>SSL_CERT_SET_SERVER</strong> return 1 for success, 2 if
|
||
|
no server certificate is used because the cipher suites is anonymous and 0
|
||
|
for failure.</p>
|
||
|
<p><code>SSL_CTX_build_cert_chain()</code> and <code>SSL_build_cert_chain()</code> return 1 for success
|
||
|
and 0 for failure. If the flag <strong>SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR</strong> and
|
||
|
a verification error occurs then 2 is returned.</p>
|
||
|
<p>All other functions return 1 for success and 0 for failure.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><em>ssl(7)</em>,
|
||
|
<em>SSL_CTX_add_extra_chain_cert(3)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p>These functions were added in OpenSSL 1.0.2.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2013-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>
|