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