Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_use_certificate.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
e056f0e0
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
e056f0e0 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
e056f0e0 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
e056f0e0 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
e056f0e0
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
e056f0e0 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
e056f0e0
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
e056f0e0
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
e056f0e0 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
e056f0e0 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
e056f0e0
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
e056f0e0
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
e056f0e0
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
e056f0e0
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
e056f0e0
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
e056f0e0
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
e056f0e0 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
e056f0e0
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
e056f0e0
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
e056f0e0 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
e056f0e0
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
e056f0e0
JR
124.\" ========================================================================
125.\"
126.IX Title "SSL_CTX_use_certificate 3"
e3261593 127.TH SSL_CTX_use_certificate 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133SSL_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
134.SH "SYNOPSIS"
e056f0e0 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/ssl.h>
e257b235 138\&
984263bc
MD
139\& int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
140\& int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
141\& int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
142\& int SSL_use_certificate(SSL *ssl, X509 *x);
143\& int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
144\& int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
e257b235 145\&
984263bc 146\& int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
e257b235 147\&
984263bc
MD
148\& int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
149\& int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
150\& long len);
151\& int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
152\& int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
153\& int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
154\& int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
155\& int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
156\& int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);
157\& int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
158\& int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
159\& int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
160\& int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
e257b235 161\&
a561f9ff
SS
162\& int SSL_CTX_check_private_key(const SSL_CTX *ctx);
163\& int SSL_check_private_key(const SSL *ssl);
984263bc
MD
164.Ve
165.SH "DESCRIPTION"
e056f0e0
JR
166.IX Header "DESCRIPTION"
167These functions load the certificates and private keys into the \s-1SSL_CTX\s0
168or \s-1SSL\s0 object, respectively.
984263bc
MD
169.PP
170The SSL_CTX_* class of functions loads the certificates and keys into the
e056f0e0
JR
171\&\s-1SSL_CTX\s0 object \fBctx\fR. The information is passed to \s-1SSL\s0 objects \fBssl\fR
172created from \fBctx\fR with \fISSL_new\fR\|(3) by copying, so that
173changes applied to \fBctx\fR do not propagate to already existing \s-1SSL\s0 objects.
984263bc
MD
174.PP
175The SSL_* class of functions only loads certificates and keys into a
e056f0e0
JR
176specific \s-1SSL\s0 object. The specific information is kept, when
177\&\fISSL_clear\fR\|(3) is called for this \s-1SSL\s0 object.
984263bc 178.PP
e056f0e0
JR
179\&\fISSL_CTX_use_certificate()\fR loads the certificate \fBx\fR into \fBctx\fR,
180\&\fISSL_use_certificate()\fR loads \fBx\fR into \fBssl\fR. The rest of the
984263bc
MD
181certificates needed to form the complete certificate chain can be
182specified using the
e056f0e0 183\&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
984263bc
MD
184function.
185.PP
e056f0e0 186\&\fISSL_CTX_use_certificate_ASN1()\fR loads the \s-1ASN1\s0 encoded certificate from
984263bc 187the memory location \fBd\fR (with length \fBlen\fR) into \fBctx\fR,
e056f0e0 188\&\fISSL_use_certificate_ASN1()\fR loads the \s-1ASN1\s0 encoded certificate into \fBssl\fR.
984263bc 189.PP
e056f0e0 190\&\fISSL_CTX_use_certificate_file()\fR loads the first certificate stored in \fBfile\fR
984263bc 191into \fBctx\fR. The formatting \fBtype\fR of the certificate must be specified
e056f0e0
JR
192from the known types \s-1SSL_FILETYPE_PEM\s0, \s-1SSL_FILETYPE_ASN1\s0.
193\&\fISSL_use_certificate_file()\fR loads the certificate from \fBfile\fR into \fBssl\fR.
194See the \s-1NOTES\s0 section on why \fISSL_CTX_use_certificate_chain_file()\fR
984263bc
MD
195should be preferred.
196.PP
e056f0e0
JR
197\&\fISSL_CTX_use_certificate_chain_file()\fR loads a certificate chain from
198\&\fBfile\fR into \fBctx\fR. The certificates must be in \s-1PEM\s0 format and must
a7d27d5a 199be sorted starting with the subject's certificate (actual client or server
e056f0e0
JR
200certificate), followed by intermediate \s-1CA\s0 certificates if applicable, and
201ending at the highest level (root) \s-1CA\s0.
202There is no corresponding function working on a single \s-1SSL\s0 object.
984263bc 203.PP
e056f0e0
JR
204\&\fISSL_CTX_use_PrivateKey()\fR adds \fBpkey\fR as private key to \fBctx\fR.
205\&\fISSL_CTX_use_RSAPrivateKey()\fR adds the private key \fBrsa\fR of type \s-1RSA\s0
984263bc 206to \fBctx\fR. \fISSL_use_PrivateKey()\fR adds \fBpkey\fR as private key to \fBssl\fR;
e056f0e0 207\&\fISSL_use_RSAPrivateKey()\fR adds \fBrsa\fR as private key of type \s-1RSA\s0 to \fBssl\fR.
a561f9ff
SS
208If a certificate has already been set and the private does not belong
209to the certificate an error is returned. To change a certificate, private
210key pair the new certificate needs to be set with \fISSL_use_certificate()\fR
211or \fISSL_CTX_use_certificate()\fR before setting the private key with
e257b235 212\&\fISSL_CTX_use_PrivateKey()\fR or \fISSL_use_PrivateKey()\fR.
984263bc 213.PP
e056f0e0 214\&\fISSL_CTX_use_PrivateKey_ASN1()\fR adds the private key of type \fBpk\fR
984263bc 215stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR.
e056f0e0 216\&\fISSL_CTX_use_RSAPrivateKey_ASN1()\fR adds the private key of type \s-1RSA\s0
984263bc 217stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR.
e056f0e0 218\&\fISSL_use_PrivateKey_ASN1()\fR and \fISSL_use_RSAPrivateKey_ASN1()\fR add the private
984263bc
MD
219key to \fBssl\fR.
220.PP
e056f0e0
JR
221\&\fISSL_CTX_use_PrivateKey_file()\fR adds the first private key found in
222\&\fBfile\fR to \fBctx\fR. The formatting \fBtype\fR of the certificate must be specified
223from the known types \s-1SSL_FILETYPE_PEM\s0, \s-1SSL_FILETYPE_ASN1\s0.
224\&\fISSL_CTX_use_RSAPrivateKey_file()\fR adds the first private \s-1RSA\s0 key found in
225\&\fBfile\fR to \fBctx\fR. \fISSL_use_PrivateKey_file()\fR adds the first private key found
984263bc 226in \fBfile\fR to \fBssl\fR; \fISSL_use_RSAPrivateKey_file()\fR adds the first private
e056f0e0 227\&\s-1RSA\s0 key found to \fBssl\fR.
984263bc 228.PP
e056f0e0 229\&\fISSL_CTX_check_private_key()\fR checks the consistency of a private key with
984263bc 230the corresponding certificate loaded into \fBctx\fR. If more than one
e056f0e0
JR
231key/certificate pair (\s-1RSA/DSA\s0) is installed, the last item installed will
232be checked. If e.g. the last item was a \s-1RSA\s0 certificate or key, the \s-1RSA\s0
984263bc
MD
233key/certificate pair will be checked. \fISSL_check_private_key()\fR performs
234the same check for \fBssl\fR. If no key/certificate was explicitly added for
235this \fBssl\fR, the last item added into \fBctx\fR will be checked.
e056f0e0
JR
236.SH "NOTES"
237.IX Header "NOTES"
238The internal certificate store of OpenSSL can hold two private key/certificate
239pairs at a time: one key/certificate of type \s-1RSA\s0 and one key/certificate
240of type \s-1DSA\s0. The certificate used depends on the cipher select, see
241also \fISSL_CTX_set_cipher_list\fR\|(3).
242.PP
984263bc 243When reading certificates and private keys from file, files of type
e056f0e0 244\&\s-1SSL_FILETYPE_ASN1\s0 (also known as \fB\s-1DER\s0\fR, binary encoding) can only contain
984263bc 245one certificate or private key, consequently
e056f0e0
JR
246\&\fISSL_CTX_use_certificate_chain_file()\fR is only applicable to \s-1PEM\s0 formatting.
247Files of type \s-1SSL_FILETYPE_PEM\s0 can contain more than one item.
984263bc 248.PP
e056f0e0 249\&\fISSL_CTX_use_certificate_chain_file()\fR adds the first certificate found
984263bc
MD
250in the file to the certificate store. The other certificates are added
251to the store of chain certificates using
e056f0e0 252\&\fISSL_CTX_add_extra_chain_cert\fR\|(3).
984263bc 253There exists only one extra chain store, so that the same chain is appended
e056f0e0 254to both types of certificates, \s-1RSA\s0 and \s-1DSA\s0! If it is not intended to use
984263bc 255both type of certificate at the same time, it is recommended to use the
e056f0e0
JR
256\&\fISSL_CTX_use_certificate_chain_file()\fR instead of the
257\&\fISSL_CTX_use_certificate_file()\fR function in order to allow the use of
258complete certificate chains even when no trusted \s-1CA\s0 storage is used or
259when the \s-1CA\s0 issuing the certificate shall not be added to the trusted
260\&\s-1CA\s0 storage.
984263bc
MD
261.PP
262If additional certificates are needed to complete the chain during the
e056f0e0
JR
263\&\s-1TLS\s0 negotiation, \s-1CA\s0 certificates are additionally looked up in the
264locations of trusted \s-1CA\s0 certificates, see
265\&\fISSL_CTX_load_verify_locations\fR\|(3).
984263bc
MD
266.PP
267The private keys loaded from file can be encrypted. In order to successfully
268load encrypted keys, a function returning the passphrase must have been
269supplied, see
e056f0e0 270\&\fISSL_CTX_set_default_passwd_cb\fR\|(3).
984263bc
MD
271(Certificate files might be encrypted as well from the technical point
272of view, it however does not make sense as the data in the certificate
273is considered public anyway.)
274.SH "RETURN VALUES"
e056f0e0 275.IX Header "RETURN VALUES"
984263bc
MD
276On success, the functions return 1.
277Otherwise check out the error stack to find out the reason.
278.SH "SEE ALSO"
a7d27d5a 279.IX Header "SEE ALSO"
e056f0e0
JR
280\&\fIssl\fR\|(3), \fISSL_new\fR\|(3), \fISSL_clear\fR\|(3),
281\&\fISSL_CTX_load_verify_locations\fR\|(3),
282\&\fISSL_CTX_set_default_passwd_cb\fR\|(3),
283\&\fISSL_CTX_set_cipher_list\fR\|(3),
284\&\fISSL_CTX_set_client_cert_cb\fR\|(3),
285\&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
a561f9ff
SS
286.SH "HISTORY"
287.IX Header "HISTORY"
288Support for \s-1DER\s0 encoded private keys (\s-1SSL_FILETYPE_ASN1\s0) in
289\&\fISSL_CTX_use_PrivateKey_file()\fR and \fISSL_use_PrivateKey_file()\fR was added
290in 0.9.8 .