228 lines
12 KiB
HTML
Executable File
228 lines
12 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_use_certificate</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="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1,
|
|
SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1,
|
|
SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file,
|
|
SSL_use_certificate_chain_file,
|
|
SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1,
|
|
SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey,
|
|
SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file,
|
|
SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey,
|
|
SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1,
|
|
SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key,
|
|
SSL_CTX_use_cert_and_key, SSL_use_cert_and_key
|
|
- load certificate and key data</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/ssl.h></pre>
|
|
<pre>
|
|
int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
|
|
int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
|
|
int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
|
|
int SSL_use_certificate(SSL *ssl, X509 *x);
|
|
int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
|
|
int SSL_use_certificate_file(SSL *ssl, const char *file, int type);</pre>
|
|
<pre>
|
|
int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
|
|
int SSL_use_certificate_chain_file(SSL *ssl, const char *file);</pre>
|
|
<pre>
|
|
int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
|
|
int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
|
|
long len);
|
|
int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
|
|
int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
|
|
int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
|
|
int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
|
|
int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
|
|
int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, unsigned char *d, long len);
|
|
int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
|
|
int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
|
|
int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
|
|
int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);</pre>
|
|
<pre>
|
|
int SSL_CTX_check_private_key(const SSL_CTX *ctx);
|
|
int SSL_check_private_key(const SSL *ssl);</pre>
|
|
<pre>
|
|
int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
|
|
int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>These functions load the certificates and private keys into the SSL_CTX
|
|
or SSL object, respectively.</p>
|
|
<p>The SSL_CTX_* class of functions loads the certificates and keys into the
|
|
SSL_CTX object <strong>ctx</strong>. The information is passed to SSL objects <strong>ssl</strong>
|
|
created from <strong>ctx</strong> with <em>SSL_new(3)</em> by copying, so that
|
|
changes applied to <strong>ctx</strong> do not propagate to already existing SSL objects.</p>
|
|
<p>The SSL_* class of functions only loads certificates and keys into a
|
|
specific SSL object. The specific information is kept, when
|
|
<em>SSL_clear(3)</em> is called for this SSL object.</p>
|
|
<p><code>SSL_CTX_use_certificate()</code> loads the certificate <strong>x</strong> into <strong>ctx</strong>,
|
|
<code>SSL_use_certificate()</code> loads <strong>x</strong> into <strong>ssl</strong>. The rest of the
|
|
certificates needed to form the complete certificate chain can be
|
|
specified using the
|
|
<em>SSL_CTX_add_extra_chain_cert(3)</em>
|
|
function.</p>
|
|
<p>SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from
|
|
the memory location <strong>d</strong> (with length <strong>len</strong>) into <strong>ctx</strong>,
|
|
SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into <strong>ssl</strong>.</p>
|
|
<p><code>SSL_CTX_use_certificate_file()</code> loads the first certificate stored in <strong>file</strong>
|
|
into <strong>ctx</strong>. The formatting <strong>type</strong> of the certificate must be specified
|
|
from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
|
|
<code>SSL_use_certificate_file()</code> loads the certificate from <strong>file</strong> into <strong>ssl</strong>.
|
|
See the NOTES section on why <code>SSL_CTX_use_certificate_chain_file()</code>
|
|
should be preferred.</p>
|
|
<p><code>SSL_CTX_use_certificate_chain_file()</code> loads a certificate chain from
|
|
<strong>file</strong> into <strong>ctx</strong>. The certificates must be in PEM format and must
|
|
be sorted starting with the subject's certificate (actual client or server
|
|
certificate), followed by intermediate CA certificates if applicable, and
|
|
ending at the highest level (root) CA. <code>SSL_use_certificate_chain_file()</code> is
|
|
similar except it loads the certificate chain into <strong>ssl</strong>.</p>
|
|
<p><code>SSL_CTX_use_PrivateKey()</code> adds <strong>pkey</strong> as private key to <strong>ctx</strong>.
|
|
<code>SSL_CTX_use_RSAPrivateKey()</code> adds the private key <strong>rsa</strong> of type RSA
|
|
to <strong>ctx</strong>. <code>SSL_use_PrivateKey()</code> adds <strong>pkey</strong> as private key to <strong>ssl</strong>;
|
|
<code>SSL_use_RSAPrivateKey()</code> adds <strong>rsa</strong> as private key of type RSA to <strong>ssl</strong>.
|
|
If a certificate has already been set and the private does not belong
|
|
to the certificate an error is returned. To change a certificate, private
|
|
key pair the new certificate needs to be set with <code>SSL_use_certificate()</code>
|
|
or <code>SSL_CTX_use_certificate()</code> before setting the private key with
|
|
<code>SSL_CTX_use_PrivateKey()</code> or <code>SSL_use_PrivateKey()</code>.</p>
|
|
<p><code>SSL_CTX_use_cert_and_key()</code> and <code>SSL_use_cert_and_key()</code> assign the X.509
|
|
certificate <strong>x</strong>, private key <strong>key</strong>, and certificate <strong>chain</strong> onto the
|
|
corresponding <strong>ssl</strong> or <strong>ctx</strong>. The <strong>pkey</strong> argument must be the private
|
|
key of the X.509 certificate <strong>x</strong>. If the <strong>override</strong> argument is 0, then
|
|
<strong>x</strong>, <strong>pkey</strong> and <strong>chain</strong> are set only if all were not previously set.
|
|
If <strong>override</strong> is non-0, then the certificate, private key and chain certs
|
|
are always set. If <strong>pkey</strong> is NULL, then the public key of <strong>x</strong> is used as
|
|
the private key. This is intended to be used with hardware (via the ENGINE
|
|
interface) that stores the private key securely, such that it cannot be
|
|
accessed by OpenSSL. The reference count of the public key is incremented
|
|
(twice if there is no private key); it is not copied nor duplicated. This
|
|
allows all private key validations checks to succeed without an actual
|
|
private key being assigned via <code>SSL_CTX_use_PrivateKey()</code>, etc.</p>
|
|
<p>SSL_CTX_use_PrivateKey_ASN1() adds the private key of type <strong>pk</strong>
|
|
stored at memory location <strong>d</strong> (length <strong>len</strong>) to <strong>ctx</strong>.
|
|
SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA
|
|
stored at memory location <strong>d</strong> (length <strong>len</strong>) to <strong>ctx</strong>.
|
|
SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private
|
|
key to <strong>ssl</strong>.</p>
|
|
<p><code>SSL_CTX_use_PrivateKey_file()</code> adds the first private key found in
|
|
<strong>file</strong> to <strong>ctx</strong>. The formatting <strong>type</strong> of the private key must be specified
|
|
from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
|
|
<code>SSL_CTX_use_RSAPrivateKey_file()</code> adds the first private RSA key found in
|
|
<strong>file</strong> to <strong>ctx</strong>. <code>SSL_use_PrivateKey_file()</code> adds the first private key found
|
|
in <strong>file</strong> to <strong>ssl</strong>; <code>SSL_use_RSAPrivateKey_file()</code> adds the first private
|
|
RSA key found to <strong>ssl</strong>.</p>
|
|
<p><code>SSL_CTX_check_private_key()</code> checks the consistency of a private key with
|
|
the corresponding certificate loaded into <strong>ctx</strong>. If more than one
|
|
key/certificate pair (RSA/DSA) is installed, the last item installed will
|
|
be checked. If e.g. the last item was a RSA certificate or key, the RSA
|
|
key/certificate pair will be checked. <code>SSL_check_private_key()</code> performs
|
|
the same check for <strong>ssl</strong>. If no key/certificate was explicitly added for
|
|
this <strong>ssl</strong>, the last item added into <strong>ctx</strong> will be checked.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>The internal certificate store of OpenSSL can hold several private
|
|
key/certificate pairs at a time. The certificate used depends on the
|
|
cipher selected, see also <em>SSL_CTX_set_cipher_list(3)</em>.</p>
|
|
<p>When reading certificates and private keys from file, files of type
|
|
SSL_FILETYPE_ASN1 (also known as <strong>DER</strong>, binary encoding) can only contain
|
|
one certificate or private key, consequently
|
|
<code>SSL_CTX_use_certificate_chain_file()</code> is only applicable to PEM formatting.
|
|
Files of type SSL_FILETYPE_PEM can contain more than one item.</p>
|
|
<p><code>SSL_CTX_use_certificate_chain_file()</code> adds the first certificate found
|
|
in the file to the certificate store. The other certificates are added
|
|
to the store of chain certificates using <em>SSL_CTX_add1_chain_cert(3)</em>. Note: versions of OpenSSL before 1.0.2 only had a single
|
|
certificate chain store for all certificate types, OpenSSL 1.0.2 and later
|
|
have a separate chain store for each type. <code>SSL_CTX_use_certificate_chain_file()</code>
|
|
should be used instead of the <code>SSL_CTX_use_certificate_file()</code> function in order
|
|
to allow the use of complete certificate chains even when no trusted CA
|
|
storage is used or when the CA issuing the certificate shall not be added to
|
|
the trusted CA storage.</p>
|
|
<p>If additional certificates are needed to complete the chain during the
|
|
TLS negotiation, CA certificates are additionally looked up in the
|
|
locations of trusted CA certificates, see
|
|
<em>SSL_CTX_load_verify_locations(3)</em>.</p>
|
|
<p>The private keys loaded from file can be encrypted. In order to successfully
|
|
load encrypted keys, a function returning the passphrase must have been
|
|
supplied, see
|
|
<em>SSL_CTX_set_default_passwd_cb(3)</em>.
|
|
(Certificate files might be encrypted as well from the technical point
|
|
of view, it however does not make sense as the data in the certificate
|
|
is considered public anyway.)</p>
|
|
<p>All of the functions to set a new certificate will replace any existing
|
|
certificate of the same type that has already been set. Similarly all of the
|
|
functions to set a new private key will replace any private key that has already
|
|
been set. Applications should call <em>SSL_CTX_check_private_key(3)</em> or
|
|
<em>SSL_check_private_key(3)</em> as appropriate after loading a new certificate and
|
|
private key to confirm that the certificate and key match.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>On success, the functions return 1.
|
|
Otherwise check out the error stack to find out the reason.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ssl(7)</em>, <em>SSL_new(3)</em>, <em>SSL_clear(3)</em>,
|
|
<em>SSL_CTX_load_verify_locations(3)</em>,
|
|
<em>SSL_CTX_set_default_passwd_cb(3)</em>,
|
|
<em>SSL_CTX_set_cipher_list(3)</em>,
|
|
<em>SSL_CTX_set_client_CA_list(3)</em>,
|
|
<em>SSL_CTX_set_client_cert_cb(3)</em>,
|
|
<em>SSL_CTX_add_extra_chain_cert(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2000-2018 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>
|