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