| blob | b4b885d98b9cc5a3dbdb9d43dfa7f4251a1fe77f |
1 .\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.2 2016/12/01 22:17:32 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: December 1 2016 $
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 certificate 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 .Fn SSL_CTX_check_private_key
305 checks the consistency of a private key with the corresponding certificate
306 loaded into
307 .Fa ctx .
308 If more than one key/certificate pair (RSA/DSA) is installed,
309 the last item installed will be checked.
310 If, e.g., the last item was a RSA certificate or key,
311 the RSA key/certificate pair will be checked.
312 .Fn SSL_check_private_key
313 performs the same check for
314 .Fa ssl .
315 If no key/certificate was explicitly added for this
316 .Fa ssl ,
317 the last item added into
318 .Fa ctx
319 will be checked.
320 .Sh NOTES
321 The internal certificate store of OpenSSL can hold two private key/certificate
322 pairs at a time:
323 one key/certificate of type RSA and one key/certificate of type DSA.
324 The certificate used depends on the cipher select, see also
325 .Xr SSL_CTX_set_cipher_list 3 .
326 .Pp
327 When reading certificates and private keys from file, files of type
328 .Dv SSL_FILETYPE_ASN1
329 (also known as
330 .Em DER ,
331 binary encoding) can only contain one certificate or private key; consequently,
332 .Fn SSL_CTX_use_certificate_chain_file
333 is only applicable to PEM formatting.
334 Files of type
335 .Dv SSL_FILETYPE_PEM
336 can contain more than one item.
337 .Pp
338 .Fn SSL_CTX_use_certificate_chain_file
339 adds the first certificate found in the file to the certificate store.
340 The other certificates are added to the store of chain certificates using
341 .Xr SSL_CTX_add_extra_chain_cert 3 .
342 There exists only one extra chain store, so that the same chain is appended
343 to both types of certificates, RSA and DSA!
344 If it is not intended to use both type of certificate at the same time,
345 it is recommended to use the
346 .Fn SSL_CTX_use_certificate_chain_file
347 instead of the
348 .Fn SSL_CTX_use_certificate_file
349 function in order to allow the use of complete certificate chains even when no
350 trusted CA storage is used or when the CA issuing the certificate shall not be
351 added to the trusted CA storage.
352 .Pp
353 If additional certificates are needed to complete the chain during the TLS
354 negotiation, CA certificates are additionally looked up in the locations of
355 trusted CA certificates (see
356 .Xr SSL_CTX_load_verify_locations 3 ) .
357 .Pp
358 The private keys loaded from file can be encrypted.
359 In order to successfully load encrypted keys,
360 a function returning the passphrase must have been supplied (see
361 .Xr SSL_CTX_set_default_passwd_cb 3 ) .
362 (Certificate files might be encrypted as well from the technical point of view,
363 it however does not make sense as the data in the certificate is considered
364 public anyway.)
365 .Sh RETURN VALUES
366 On success, the functions return 1.
367 Otherwise check out the error stack to find out the reason.
368 .Sh SEE ALSO
369 .Xr ssl 3 ,
370 .Xr SSL_clear 3 ,
371 .Xr SSL_CTX_add_extra_chain_cert 3 ,
372 .Xr SSL_CTX_load_verify_locations 3 ,
373 .Xr SSL_CTX_set_cipher_list 3 ,
374 .Xr SSL_CTX_set_client_cert_cb 3 ,
375 .Xr SSL_CTX_set_default_passwd_cb 3 ,
376 .Xr SSL_new 3
377 .Sh HISTORY
378 Support for DER encoded private keys
379 .Pq Dv SSL_FILETYPE_ASN1
380 in
381 .Fn SSL_CTX_use_PrivateKey_file
382 and
383 .Fn SSL_use_PrivateKey_file
384 was added in 0.9.8.