]>
Commit | Line | Data |
---|---|---|
66ebbb6a LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
5 | SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, |
6 | SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, | |
7 | SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, | |
8 | SSL_use_certificate_chain_file, | |
9 | SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, | |
10 | SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, | |
11 | SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, | |
12 | SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, | |
13 | SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, | |
37933acb TS |
14 | SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key, |
15 | SSL_CTX_use_cert_and_key, SSL_use_cert_and_key | |
c952780c | 16 | - load certificate and key data |
66ebbb6a LJ |
17 | |
18 | =head1 SYNOPSIS | |
19 | ||
20 | #include <openssl/ssl.h> | |
21 | ||
22 | int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); | |
23 | int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); | |
24 | int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); | |
25 | int SSL_use_certificate(SSL *ssl, X509 *x); | |
26 | int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); | |
27 | int SSL_use_certificate_file(SSL *ssl, const char *file, int type); | |
28 | ||
29 | int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); | |
fae4772c | 30 | int SSL_use_certificate_chain_file(SSL *ssl, const char *file); |
66ebbb6a LJ |
31 | |
32 | int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); | |
33 | int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d, | |
1bc74519 | 34 | long len); |
66ebbb6a LJ |
35 | int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); |
36 | int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); | |
37 | int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); | |
38 | int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); | |
39 | int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); | |
aebb9aac | 40 | int SSL_use_PrivateKey_ASN1(int pk, SSL *ssl, unsigned char *d, long len); |
66ebbb6a LJ |
41 | int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); |
42 | int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); | |
43 | int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); | |
44 | int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); | |
45 | ||
c3e64028 NL |
46 | int SSL_CTX_check_private_key(const SSL_CTX *ctx); |
47 | int SSL_check_private_key(const SSL *ssl); | |
cc93ae3e | 48 | |
37933acb TS |
49 | int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override); |
50 | int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override); | |
51 | ||
66ebbb6a LJ |
52 | =head1 DESCRIPTION |
53 | ||
54 | These functions load the certificates and private keys into the SSL_CTX | |
55 | or SSL object, respectively. | |
56 | ||
57 | The SSL_CTX_* class of functions loads the certificates and keys into the | |
58 | SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl> | |
9b86974e | 59 | created from B<ctx> with L<SSL_new(3)> by copying, so that |
66ebbb6a LJ |
60 | changes applied to B<ctx> do not propagate to already existing SSL objects. |
61 | ||
62 | The SSL_* class of functions only loads certificates and keys into a | |
63 | specific SSL object. The specific information is kept, when | |
9b86974e | 64 | L<SSL_clear(3)> is called for this SSL object. |
66ebbb6a LJ |
65 | |
66 | SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>, | |
7403c34b LJ |
67 | SSL_use_certificate() loads B<x> into B<ssl>. The rest of the |
68 | certificates needed to form the complete certificate chain can be | |
69 | specified using the | |
9b86974e | 70 | L<SSL_CTX_add_extra_chain_cert(3)> |
7403c34b | 71 | function. |
66ebbb6a LJ |
72 | |
73 | SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from | |
74 | the memory location B<d> (with length B<len>) into B<ctx>, | |
75 | SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>. | |
76 | ||
77 | SSL_CTX_use_certificate_file() loads the first certificate stored in B<file> | |
78 | into B<ctx>. The formatting B<type> of the certificate must be specified | |
79 | from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. | |
80 | SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>. | |
7403c34b LJ |
81 | See the NOTES section on why SSL_CTX_use_certificate_chain_file() |
82 | should be preferred. | |
66ebbb6a | 83 | |
1bc74519 | 84 | SSL_CTX_use_certificate_chain_file() loads a certificate chain from |
66ebbb6a | 85 | B<file> into B<ctx>. The certificates must be in PEM format and must |
02b95b74 LJ |
86 | be sorted starting with the subject's certificate (actual client or server |
87 | certificate), followed by intermediate CA certificates if applicable, and | |
fae4772c | 88 | ending at the highest level (root) CA. SSL_use_certificate_chain_file() is |
24c2cd39 | 89 | similar except it loads the certificate chain into B<ssl>. |
66ebbb6a LJ |
90 | |
91 | SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>. | |
92 | SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA | |
93 | to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>; | |
94 | SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>. | |
e248596b NL |
95 | If a certificate has already been set and the private does not belong |
96 | to the certificate an error is returned. To change a certificate, private | |
97 | key pair the new certificate needs to be set with SSL_use_certificate() | |
98 | or SSL_CTX_use_certificate() before setting the private key with | |
1bc74519 | 99 | SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey(). |
e248596b | 100 | |
37933acb TS |
101 | SSL_CTX_use_cert_and_key() and SSL_use_cert_and_key() assign the X.509 |
102 | certificate B<x>, private key B<key>, and certificate B<chain> onto the | |
103 | corresponding B<ssl> or B<ctx>. The B<pkey> argument must be the private | |
104 | key of the X.509 certificate B<x>. If the B<override> argument is 0, then | |
105 | B<x>, B<pkey> and B<chain> are set only if all were not previously set. | |
106 | If B<override> is non-0, then the certificate, private key and chain certs | |
107 | are always set. If B<pkey> is NULL, then the public key of B<x> is used as | |
108 | the private key. This is intended to be used with hardware (via the ENGINE | |
109 | inteface) that stores the private key securely, such that it cannot be | |
110 | accessed by OpenSSL. The reference count of the public key is incremented | |
111 | (twice if there is no private key); it is not copied nor duplicated. This | |
112 | allows all private key validations checks to succeed without an actual | |
113 | private key being assigned via SSL_CTX_use_PrivateKey(), etc. | |
66ebbb6a LJ |
114 | |
115 | SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk> | |
116 | stored at memory location B<d> (length B<len>) to B<ctx>. | |
117 | SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA | |
118 | stored at memory location B<d> (length B<len>) to B<ctx>. | |
119 | SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private | |
120 | key to B<ssl>. | |
121 | ||
122 | SSL_CTX_use_PrivateKey_file() adds the first private key found in | |
3aaa1bd0 | 123 | B<file> to B<ctx>. The formatting B<type> of the private key must be specified |
66ebbb6a LJ |
124 | from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. |
125 | SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in | |
126 | B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found | |
127 | in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private | |
128 | RSA key found to B<ssl>. | |
129 | ||
cc93ae3e LJ |
130 | SSL_CTX_check_private_key() checks the consistency of a private key with |
131 | the corresponding certificate loaded into B<ctx>. If more than one | |
132 | key/certificate pair (RSA/DSA) is installed, the last item installed will | |
133 | be checked. If e.g. the last item was a RSA certificate or key, the RSA | |
134 | key/certificate pair will be checked. SSL_check_private_key() performs | |
135 | the same check for B<ssl>. If no key/certificate was explicitly added for | |
136 | this B<ssl>, the last item added into B<ctx> will be checked. | |
137 | ||
66ebbb6a | 138 | =head1 NOTES |
1bc74519 | 139 | |
a4339ea3 DSH |
140 | The internal certificate store of OpenSSL can hold several private |
141 | key/certificate pairs at a time. The certificate used depends on the | |
9b86974e | 142 | cipher selected, see also L<SSL_CTX_set_cipher_list(3)>. |
66ebbb6a LJ |
143 | |
144 | When reading certificates and private keys from file, files of type | |
145 | SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain | |
1bc74519 | 146 | one certificate or private key, consequently |
66ebbb6a LJ |
147 | SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. |
148 | Files of type SSL_FILETYPE_PEM can contain more than one item. | |
149 | ||
150 | SSL_CTX_use_certificate_chain_file() adds the first certificate found | |
151 | in the file to the certificate store. The other certificates are added | |
9b86974e | 152 | to the store of chain certificates using L<SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single |
a4339ea3 | 153 | certificate chain store for all certificate types, OpenSSL 1.0.2 and later |
1bc74519 | 154 | have a separate chain store for each type. SSL_CTX_use_certificate_chain_file() |
a4339ea3 DSH |
155 | should be used instead of the SSL_CTX_use_certificate_file() function in order |
156 | to allow the use of complete certificate chains even when no trusted CA | |
157 | storage is used or when the CA issuing the certificate shall not be added to | |
158 | the trusted CA storage. | |
66ebbb6a LJ |
159 | |
160 | If additional certificates are needed to complete the chain during the | |
161 | TLS negotiation, CA certificates are additionally looked up in the | |
162 | locations of trusted CA certificates, see | |
9b86974e | 163 | L<SSL_CTX_load_verify_locations(3)>. |
66ebbb6a LJ |
164 | |
165 | The private keys loaded from file can be encrypted. In order to successfully | |
166 | load encrypted keys, a function returning the passphrase must have been | |
167 | supplied, see | |
9b86974e | 168 | L<SSL_CTX_set_default_passwd_cb(3)>. |
66ebbb6a LJ |
169 | (Certificate files might be encrypted as well from the technical point |
170 | of view, it however does not make sense as the data in the certificate | |
171 | is considered public anyway.) | |
172 | ||
173 | =head1 RETURN VALUES | |
174 | ||
175 | On success, the functions return 1. | |
176 | Otherwise check out the error stack to find out the reason. | |
177 | ||
178 | =head1 SEE ALSO | |
179 | ||
b97fdb57 | 180 | L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, |
9b86974e RS |
181 | L<SSL_CTX_load_verify_locations(3)>, |
182 | L<SSL_CTX_set_default_passwd_cb(3)>, | |
183 | L<SSL_CTX_set_cipher_list(3)>, | |
e0b5108c | 184 | L<SSL_CTX_set_client_CA_list(3)>, |
9b86974e RS |
185 | L<SSL_CTX_set_client_cert_cb(3)>, |
186 | L<SSL_CTX_add_extra_chain_cert(3)> | |
66ebbb6a | 187 | |
e2f92610 RS |
188 | =head1 COPYRIGHT |
189 | ||
37933acb | 190 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
191 | |
192 | Licensed under the OpenSSL license (the "License"). You may not use | |
193 | this file except in compliance with the License. You can obtain a copy | |
194 | in the file LICENSE in the source distribution or at | |
195 | L<https://www.openssl.org/source/license.html>. | |
196 | ||
197 | =cut |