| blob | bc7d03cc195395262369287d597339f3b50e2e27 |
1 .\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.5 2017/08/20 23:18:53 schwarze Exp $
2 .\" OpenSSL e248596b Apr 8 22:49:57 2005 +0000
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
5 .\" Copyright (c) 2000, 2001, 2002, 2003, 2005 The OpenSSL Project.
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: August 20 2017 $
53 .Dt SSL_CTX_USE_CERTIFICATE 3
54 .Os
55 .Sh NAME
56 .Nm SSL_CTX_use_certificate ,
57 .Nm SSL_CTX_use_certificate_ASN1 ,
58 .Nm SSL_CTX_use_certificate_file ,
59 .Nm SSL_use_certificate ,
60 .Nm SSL_use_certificate_ASN1 ,
61 .Nm SSL_use_certificate_file ,
62 .Nm SSL_CTX_use_certificate_chain_file ,
63 .Nm SSL_CTX_use_certificate_chain_mem ,
64 .Nm SSL_CTX_use_PrivateKey ,
65 .Nm SSL_CTX_use_PrivateKey_ASN1 ,
66 .Nm SSL_CTX_use_PrivateKey_file ,
67 .Nm SSL_CTX_use_RSAPrivateKey ,
68 .Nm SSL_CTX_use_RSAPrivateKey_ASN1 ,
69 .Nm SSL_CTX_use_RSAPrivateKey_file ,
70 .Nm SSL_use_PrivateKey_file ,
71 .Nm SSL_use_PrivateKey_ASN1 ,
72 .Nm SSL_use_PrivateKey ,
73 .Nm SSL_use_RSAPrivateKey ,
74 .Nm SSL_use_RSAPrivateKey_ASN1 ,
75 .Nm SSL_use_RSAPrivateKey_file ,
76 .Nm SSL_CTX_check_private_key ,
77 .Nm SSL_check_private_key
78 .Nd load certificate and key data
79 .Sh SYNOPSIS
80 .In openssl/ssl.h
81 .Ft int
82 .Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x"
83 .Ft int
84 .Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d"
85 .Ft int
86 .Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "const char *file" "int type"
87 .Ft int
88 .Fn SSL_use_certificate "SSL *ssl" "X509 *x"
89 .Ft int
90 .Fn SSL_use_certificate_ASN1 "SSL *ssl" "unsigned char *d" "int len"
91 .Ft int
92 .Fn SSL_use_certificate_file "SSL *ssl" "const char *file" "int type"
93 .Ft int
94 .Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file"
95 .Ft int
96 .Fn SSL_CTX_use_certificate_chain_mem "SSL_CTX *ctx" "void *buf" "int len"
97 .Ft int
98 .Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey"
99 .Ft int
100 .Fo SSL_CTX_use_PrivateKey_ASN1
101 .Fa "int pk" "SSL_CTX *ctx" "unsigned char *d" "long len"
102 .Fc
103 .Ft int
104 .Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "const char *file" "int type"
105 .Ft int
106 .Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa"
107 .Ft int
108 .Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len"
109 .Ft int
110 .Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "const char *file" "int type"
111 .Ft int
112 .Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey"
113 .Ft int
114 .Fn SSL_use_PrivateKey_ASN1 "int pk" "SSL *ssl" "unsigned char *d" "long len"
115 .Ft int
116 .Fn SSL_use_PrivateKey_file "SSL *ssl" "const char *file" "int type"
117 .Ft int
118 .Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa"
119 .Ft int
120 .Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len"
121 .Ft int
122 .Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "const char *file" "int type"
123 .Ft int
124 .Fn SSL_CTX_check_private_key "const SSL_CTX *ctx"
125 .Ft int
126 .Fn SSL_check_private_key "const SSL *ssl"
127 .Sh DESCRIPTION
128 These functions load the certificates and private keys into the
129 .Vt SSL_CTX
130 or
131 .Vt SSL
132 object, respectively.
133 .Pp
134 The
135 .Fn SSL_CTX_*
136 class of functions loads the certificates and keys into the
137 .Vt SSL_CTX
138 object
139 .Fa ctx .
140 The information is passed to
141 .Vt SSL
142 objects
143 .Fa ssl
144 created from
145 .Fa ctx
146 with
147 .Xr SSL_new 3
148 by copying, so that changes applied to
149 .Fa ctx
150 do not propagate to already existing
151 .Vt SSL
152 objects.
153 .Pp
154 The
155 .Fn SSL_*
156 class of functions only loads certificates and keys into a specific
157 .Vt SSL
158 object.
159 The specific information is kept when
160 .Xr SSL_clear 3
161 is called for this
162 .Vt SSL
163 object.
164 .Pp
165 .Fn SSL_CTX_use_certificate
166 loads the certificate
167 .Fa x
168 into
169 .Fa ctx ;
170 .Fn SSL_use_certificate
171 loads
172 .Fa x
173 into
174 .Fa ssl .
175 The rest of the certificates needed to form the complete certificate chain can
176 be specified using the
177 .Xr SSL_CTX_add_extra_chain_cert 3
178 function.
179 .Pp
180 .Fn SSL_CTX_use_certificate_ASN1
181 loads the ASN1 encoded certificate from the memory location
182 .Fa d
183 (with length
184 .Fa len )
185 into
186 .Fa ctx ;
187 .Fn SSL_use_certificate_ASN1
188 loads the ASN1 encoded certificate into
189 .Fa ssl .
190 .Pp
191 .Fn SSL_CTX_use_certificate_file
192 loads the first certificate stored in
193 .Fa file
194 into
195 .Fa ctx .
196 The formatting
197 .Fa type
198 of the certificate must be specified from the known types
199 .Dv SSL_FILETYPE_PEM
200 and
201 .Dv SSL_FILETYPE_ASN1 .
202 .Fn SSL_use_certificate_file
203 loads the certificate from
204 .Fa file
205 into
206 .Fa ssl .
207 See the
208 .Sx NOTES
209 section on why
210 .Fn SSL_CTX_use_certificate_chain_file
211 should be preferred.
212 .Pp
213 The
214 .Fn SSL_CTX_use_certificate_chain*
215 functions load a certificate chain into
216 .Fa ctx .
217 The certificates must be in PEM format and must be sorted starting with the
218 subject's certificate (actual client or server certificate),
219 followed by intermediate CA certificates if applicable,
220 and ending at the highest level (root) CA.
221 There is no corresponding function working on a single
222 .Vt SSL
223 object.
224 .Pp
225 .Fn SSL_CTX_use_PrivateKey
226 adds
227 .Fa pkey
228 as private key to
229 .Fa ctx .
230 .Fn SSL_CTX_use_RSAPrivateKey
231 adds the private key
232 .Fa rsa
233 of type RSA to
234 .Fa ctx .
235 .Fn SSL_use_PrivateKey
236 adds
237 .Fa pkey
238 as private key to
239 .Fa ssl ;
240 .Fn SSL_use_RSAPrivateKey
241 adds
242 .Fa rsa
243 as private key of type RSA to
244 .Fa ssl .
245 If a certificate has already been set and the private does not belong to the
246 certificate, an error is returned.
247 To change a certificate private key pair,
248 the new certificate needs to be set with
249 .Fn SSL_use_certificate
250 or
251 .Fn SSL_CTX_use_certificate
252 before setting the private key with
253 .Fn SSL_CTX_use_PrivateKey
254 or
255 .Fn SSL_use_PrivateKey .
256 .Pp
257 .Fn SSL_CTX_use_PrivateKey_ASN1
258 adds the private key of type
259 .Fa pk
260 stored at memory location
261 .Fa d
262 (length
263 .Fa len )
264 to
265 .Fa ctx .
266 .Fn SSL_CTX_use_RSAPrivateKey_ASN1
267 adds the private key of type RSA stored at memory location
268 .Fa d
269 (length
270 .Fa len )
271 to
272 .Fa ctx .
273 .Fn SSL_use_PrivateKey_ASN1
274 and
275 .Fn SSL_use_RSAPrivateKey_ASN1
276 add the private key to
277 .Fa ssl .
278 .Pp
279 .Fn SSL_CTX_use_PrivateKey_file
280 adds the first private key found in
281 .Fa file
282 to
283 .Fa ctx .
284 The formatting
285 .Fa type
286 of the private key must be specified from the known types
287 .Dv SSL_FILETYPE_PEM
288 and
289 .Dv SSL_FILETYPE_ASN1 .
290 .Fn SSL_CTX_use_RSAPrivateKey_file
291 adds the first private RSA key found in
292 .Fa file
293 to
294 .Fa ctx .
295 .Fn SSL_use_PrivateKey_file
296 adds the first private key found in
297 .Fa file
298 to
299 .Fa ssl ;
300 .Fn SSL_use_RSAPrivateKey_file
301 adds the first private RSA key found to
302 .Fa ssl .
303 .Pp
304 The
305 .Fn SSL_CTX_check_private_key
306 function is seriously misnamed.
307 It compares the
308 .Em public
309 key components and parameters of an OpenSSL private key with the
310 corresponding certificate loaded into
311 .Fa ctx .
312 If more than one key/certificate pair (RSA/DSA) is installed,
313 the last item installed will be compared.
314 If, e.g., the last item was a RSA certificate or key,
315 the RSA key/certificate pair will be checked.
316 .Fn SSL_check_private_key
317 performs the same
318 .Em public
319 key comparison for
320 .Fa ssl .
321 If no key/certificate was explicitly added for this
322 .Fa ssl ,
323 the last item added into
324 .Fa ctx
325 will be checked.
326 .Pp
327 Despite the name, neither
328 .Fn SSL_CTX_check_private_key
329 nor
330 .Fn SSL_check_private_key
331 checks whether the private key component is indeed a private key,
332 nor whether it matches the public key component.
333 They merely compare the public materials (e.g. exponent and modulus of
334 an RSA key) and/or key parameters (e.g. EC params of an EC key) of a
335 key pair.
336 .Sh NOTES
337 The internal certificate store of OpenSSL can hold two private key/certificate
338 pairs at a time:
339 one key/certificate of type RSA and one key/certificate of type DSA.
340 The certificate used depends on the cipher select, see also
341 .Xr SSL_CTX_set_cipher_list 3 .
342 .Pp
343 When reading certificates and private keys from file, files of type
344 .Dv SSL_FILETYPE_ASN1
345 (also known as
346 .Em DER ,
347 binary encoding) can only contain one certificate or private key; consequently,
348 .Fn SSL_CTX_use_certificate_chain_file
349 is only applicable to PEM formatting.
350 Files of type
351 .Dv SSL_FILETYPE_PEM
352 can contain more than one item.
353 .Pp
354 .Fn SSL_CTX_use_certificate_chain_file
355 adds the first certificate found in the file to the certificate store.
356 The other certificates are added to the store of chain certificates using
357 .Xr SSL_CTX_add_extra_chain_cert 3 .
358 There exists only one extra chain store, so that the same chain is appended
359 to both types of certificates, RSA and DSA!
360 If it is not intended to use both type of certificate at the same time,
361 it is recommended to use the
362 .Fn SSL_CTX_use_certificate_chain_file
363 instead of the
364 .Fn SSL_CTX_use_certificate_file
365 function in order to allow the use of complete certificate chains even when no
366 trusted CA storage is used or when the CA issuing the certificate shall not be
367 added to the trusted CA storage.
368 .Pp
369 If additional certificates are needed to complete the chain during the TLS
370 negotiation, CA certificates are additionally looked up in the locations of
371 trusted CA certificates (see
372 .Xr SSL_CTX_load_verify_locations 3 ) .
373 .Pp
374 The private keys loaded from file can be encrypted.
375 In order to successfully load encrypted keys,
376 a function returning the passphrase must have been supplied (see
377 .Xr SSL_CTX_set_default_passwd_cb 3 ) .
378 (Certificate files might be encrypted as well from the technical point of view,
379 it however does not make sense as the data in the certificate is considered
380 public anyway.)
381 .Sh RETURN VALUES
382 On success, the functions return 1.
383 Otherwise check out the error stack to find out the reason.
384 .Sh SEE ALSO
385 .Xr ssl 3 ,
386 .Xr SSL_clear 3 ,
387 .Xr SSL_CTX_add_extra_chain_cert 3 ,
388 .Xr SSL_CTX_load_verify_locations 3 ,
389 .Xr SSL_CTX_set_cipher_list 3 ,
390 .Xr SSL_CTX_set_client_cert_cb 3 ,
391 .Xr SSL_CTX_set_default_passwd_cb 3 ,
392 .Xr SSL_new 3 ,
393 .Xr X509_check_private_key 3
394 .Sh HISTORY
395 Support for DER encoded private keys
396 .Pq Dv SSL_FILETYPE_ASN1
397 in
398 .Fn SSL_CTX_use_PrivateKey_file
399 and
400 .Fn SSL_use_PrivateKey_file
401 was added in 0.9.8.