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