Update per latest manual pages after running 'man-update'.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_use_certificate.3
CommitLineData
a7d27d5a
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
a7d27d5a 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
a7d27d5a 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
a7d27d5a 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
a7d27d5a 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
a7d27d5a
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
a7d27d5a
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
a7d27d5a
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
a7d27d5a
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
a7d27d5a
JR
93.nr % 0
94.rr F
984263bc 95.\}
a7d27d5a
JR
96.TH SSL_CTX_use_certificate 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
a7d27d5a
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
a7d27d5a 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
a7d27d5a
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
a7d27d5a
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
a7d27d5a 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
a7d27d5a
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
a7d27d5a
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
a7d27d5a 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
a7d27d5a
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
a7d27d5a
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
a7d27d5a 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
a7d27d5a
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191SSL_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_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 \- load certificate and key data
192.SH "SYNOPSIS"
a7d27d5a 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/ssl.h>
196.Ve
197.Vb 6
198\& int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
199\& int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
200\& int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
201\& int SSL_use_certificate(SSL *ssl, X509 *x);
202\& int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
203\& int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
204.Ve
205.Vb 1
206\& int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
207.Ve
208.Vb 13
209\& int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
210\& int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
211\& long len);
212\& int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
213\& int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
214\& int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
215\& int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
216\& int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
217\& int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);
218\& int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
219\& int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
220\& int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
221\& int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
222.Ve
223.Vb 2
224\& int SSL_CTX_check_private_key(SSL_CTX *ctx);
225\& int SSL_check_private_key(SSL *ssl);
226.Ve
227.SH "DESCRIPTION"
a7d27d5a
JR
228These functions load the certificates and private keys into the SSL_CTX
229or SSL object, respectively.
984263bc
MD
230.PP
231The SSL_CTX_* class of functions loads the certificates and keys into the
a7d27d5a 232SSL_CTX object \fBctx\fR. The information is passed to SSL objects \fBssl\fR
984263bc 233created from \fBctx\fR with SSL_new(3) by copying, so that
a7d27d5a 234changes applied to \fBctx\fR do not propagate to already existing SSL objects.
984263bc
MD
235.PP
236The SSL_* class of functions only loads certificates and keys into a
a7d27d5a
JR
237specific SSL object. The specific information is kept, when
238SSL_clear(3) is called for this SSL object.
984263bc 239.PP
a7d27d5a
JR
240\fISSL_CTX_use_certificate()\fR loads the certificate \fBx\fR into \fBctx\fR,
241\fISSL_use_certificate()\fR loads \fBx\fR into \fBssl\fR. The rest of the
984263bc
MD
242certificates needed to form the complete certificate chain can be
243specified using the
244SSL_CTX_add_extra_chain_cert(3)
245function.
246.PP
a7d27d5a 247\fISSL_CTX_use_certificate_ASN1()\fR loads the ASN1 encoded certificate from
984263bc 248the memory location \fBd\fR (with length \fBlen\fR) into \fBctx\fR,
a7d27d5a 249\fISSL_use_certificate_ASN1()\fR loads the ASN1 encoded certificate into \fBssl\fR.
984263bc 250.PP
a7d27d5a 251\fISSL_CTX_use_certificate_file()\fR loads the first certificate stored in \fBfile\fR
984263bc 252into \fBctx\fR. The formatting \fBtype\fR of the certificate must be specified
a7d27d5a
JR
253from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
254\fISSL_use_certificate_file()\fR loads the certificate from \fBfile\fR into \fBssl\fR.
255See the NOTES section on why \fISSL_CTX_use_certificate_chain_file()\fR
984263bc
MD
256should be preferred.
257.PP
a7d27d5a
JR
258\fISSL_CTX_use_certificate_chain_file()\fR loads a certificate chain from
259\fBfile\fR into \fBctx\fR. The certificates must be in PEM format and must
260be sorted starting with the subject's certificate (actual client or server
261certificate), followed by intermediate CA certificates if applicable, and
262ending at the highest level (root) CA.
263There is no corresponding function working on a single SSL object.
984263bc 264.PP
a7d27d5a
JR
265\fISSL_CTX_use_PrivateKey()\fR adds \fBpkey\fR as private key to \fBctx\fR.
266\fISSL_CTX_use_RSAPrivateKey()\fR adds the private key \fBrsa\fR of type RSA
984263bc 267to \fBctx\fR. \fISSL_use_PrivateKey()\fR adds \fBpkey\fR as private key to \fBssl\fR;
a7d27d5a 268\fISSL_use_RSAPrivateKey()\fR adds \fBrsa\fR as private key of type RSA to \fBssl\fR.
984263bc 269.PP
a7d27d5a 270\fISSL_CTX_use_PrivateKey_ASN1()\fR adds the private key of type \fBpk\fR
984263bc 271stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR.
a7d27d5a 272\fISSL_CTX_use_RSAPrivateKey_ASN1()\fR adds the private key of type RSA
984263bc 273stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR.
a7d27d5a 274\fISSL_use_PrivateKey_ASN1()\fR and \fISSL_use_RSAPrivateKey_ASN1()\fR add the private
984263bc
MD
275key to \fBssl\fR.
276.PP
a7d27d5a
JR
277\fISSL_CTX_use_PrivateKey_file()\fR adds the first private key found in
278\fBfile\fR to \fBctx\fR. The formatting \fBtype\fR of the certificate must be specified
279from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.
280\fISSL_CTX_use_RSAPrivateKey_file()\fR adds the first private RSA key found in
281\fBfile\fR to \fBctx\fR. \fISSL_use_PrivateKey_file()\fR adds the first private key found
984263bc 282in \fBfile\fR to \fBssl\fR; \fISSL_use_RSAPrivateKey_file()\fR adds the first private
a7d27d5a 283RSA key found to \fBssl\fR.
984263bc 284.PP
a7d27d5a 285\fISSL_CTX_check_private_key()\fR checks the consistency of a private key with
984263bc 286the corresponding certificate loaded into \fBctx\fR. If more than one
a7d27d5a
JR
287key/certificate pair (RSA/DSA) is installed, the last item installed will
288be checked. If e.g. the last item was a RSA certificate or key, the RSA
984263bc
MD
289key/certificate pair will be checked. \fISSL_check_private_key()\fR performs
290the same check for \fBssl\fR. If no key/certificate was explicitly added for
291this \fBssl\fR, the last item added into \fBctx\fR will be checked.
a7d27d5a 292.SH "NOTES The internal certificate store of OpenSSL can hold two private key/certificate pairs at a time: one key/certificate of type RSA and one key/certificate of type DSA. The certificate used depends on the cipher select, see also SSL_CTX_set_cipher_list(3)."
984263bc 293When reading certificates and private keys from file, files of type
a7d27d5a 294SSL_FILETYPE_ASN1 (also known as \fBDER\fR, binary encoding) can only contain
984263bc 295one certificate or private key, consequently
a7d27d5a
JR
296\fISSL_CTX_use_certificate_chain_file()\fR is only applicable to PEM formatting.
297Files of type SSL_FILETYPE_PEM can contain more than one item.
984263bc 298.PP
a7d27d5a 299\fISSL_CTX_use_certificate_chain_file()\fR adds the first certificate found
984263bc
MD
300in the file to the certificate store. The other certificates are added
301to the store of chain certificates using
302SSL_CTX_add_extra_chain_cert(3).
303There exists only one extra chain store, so that the same chain is appended
a7d27d5a 304to both types of certificates, RSA and DSA! If it is not intended to use
984263bc 305both type of certificate at the same time, it is recommended to use the
a7d27d5a
JR
306\fISSL_CTX_use_certificate_chain_file()\fR instead of the
307\fISSL_CTX_use_certificate_file()\fR function in order to allow the use of
308complete certificate chains even when no trusted CA storage is used or
309when the CA issuing the certificate shall not be added to the trusted
310CA storage.
984263bc
MD
311.PP
312If additional certificates are needed to complete the chain during the
a7d27d5a
JR
313TLS negotiation, CA certificates are additionally looked up in the
314locations of trusted CA certificates, see
984263bc
MD
315SSL_CTX_load_verify_locations(3).
316.PP
317The private keys loaded from file can be encrypted. In order to successfully
318load encrypted keys, a function returning the passphrase must have been
319supplied, see
320SSL_CTX_set_default_passwd_cb(3).
321(Certificate files might be encrypted as well from the technical point
322of view, it however does not make sense as the data in the certificate
323is considered public anyway.)
324.SH "RETURN VALUES"
984263bc
MD
325On success, the functions return 1.
326Otherwise check out the error stack to find out the reason.
327.SH "SEE ALSO"
984263bc
MD
328ssl(3), SSL_new(3), SSL_clear(3),
329SSL_CTX_load_verify_locations(3),
330SSL_CTX_set_default_passwd_cb(3),
331SSL_CTX_set_cipher_list(3),
332SSL_CTX_set_client_cert_cb(3),
333SSL_CTX_add_extra_chain_cert(3)
a7d27d5a
JR
334
335.rn }` ''
336.IX Title "SSL_CTX_use_certificate 3"
337.IX Name "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_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 - load certificate and key data"
338
339.IX Header "NAME"
340
341.IX Header "SYNOPSIS"
342
343.IX Header "DESCRIPTION"
344
345.IX Header "NOTES The internal certificate store of OpenSSL can hold two private key/certificate pairs at a time: one key/certificate of type RSA and one key/certificate of type DSA. The certificate used depends on the cipher select, see also SSL_CTX_set_cipher_list(3)."
346
347.IX Header "RETURN VALUES"
348
349.IX Header "SEE ALSO"
350