Regenerate manual pages.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_use_certificate.3
CommitLineData
e056f0e0
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
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
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
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
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
e056f0e0
JR
59. nr % 0
60. rr F
984263bc 61.\}
e056f0e0
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
e056f0e0
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
e056f0e0
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
e056f0e0
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
e056f0e0 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
e056f0e0
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
e056f0e0
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
e056f0e0 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
e056f0e0 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
e056f0e0 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
e056f0e0
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
e056f0e0
JR
129.\" ========================================================================
130.\"
131.IX Title "SSL_CTX_use_certificate 3"
132.TH SSL_CTX_use_certificate 3 "2004-12-22" "0.9.7e" "OpenSSL"
984263bc
MD
133.SH "NAME"
134SSL_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
135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
139.Ve
e056f0e0 140.PP
984263bc
MD
141.Vb 6
142\& int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);
143\& int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);
144\& int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);
145\& int SSL_use_certificate(SSL *ssl, X509 *x);
146\& int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);
147\& int SSL_use_certificate_file(SSL *ssl, const char *file, int type);
148.Ve
e056f0e0 149.PP
984263bc
MD
150.Vb 1
151\& int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);
152.Ve
e056f0e0 153.PP
984263bc
MD
154.Vb 13
155\& int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);
156\& int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,
157\& long len);
158\& int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);
159\& int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);
160\& int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);
161\& int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);
162\& int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);
163\& int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);
164\& int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);
165\& int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);
166\& int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);
167\& int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);
168.Ve
e056f0e0 169.PP
984263bc
MD
170.Vb 2
171\& int SSL_CTX_check_private_key(SSL_CTX *ctx);
172\& int SSL_check_private_key(SSL *ssl);
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
e056f0e0
JR
201from the known types \s-1SSL_FILETYPE_PEM\s0, \s-1SSL_FILETYPE_ASN1\s0.
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
JR
209certificate), followed by intermediate \s-1CA\s0 certificates if applicable, and
210ending at the highest level (root) \s-1CA\s0.
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.
984263bc 217.PP
e056f0e0 218\&\fISSL_CTX_use_PrivateKey_ASN1()\fR adds the private key of type \fBpk\fR
984263bc 219stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR.
e056f0e0 220\&\fISSL_CTX_use_RSAPrivateKey_ASN1()\fR adds the private key of type \s-1RSA\s0
984263bc 221stored at memory location \fBd\fR (length \fBlen\fR) to \fBctx\fR.
e056f0e0 222\&\fISSL_use_PrivateKey_ASN1()\fR and \fISSL_use_RSAPrivateKey_ASN1()\fR add the private
984263bc
MD
223key to \fBssl\fR.
224.PP
e056f0e0
JR
225\&\fISSL_CTX_use_PrivateKey_file()\fR adds the first private key found in
226\&\fBfile\fR to \fBctx\fR. The formatting \fBtype\fR of the certificate must be specified
227from the known types \s-1SSL_FILETYPE_PEM\s0, \s-1SSL_FILETYPE_ASN1\s0.
228\&\fISSL_CTX_use_RSAPrivateKey_file()\fR adds the first private \s-1RSA\s0 key found in
229\&\fBfile\fR to \fBctx\fR. \fISSL_use_PrivateKey_file()\fR adds the first private key found
984263bc 230in \fBfile\fR to \fBssl\fR; \fISSL_use_RSAPrivateKey_file()\fR adds the first private
e056f0e0 231\&\s-1RSA\s0 key found to \fBssl\fR.
984263bc 232.PP
e056f0e0 233\&\fISSL_CTX_check_private_key()\fR checks the consistency of a private key with
984263bc 234the corresponding certificate loaded into \fBctx\fR. If more than one
e056f0e0
JR
235key/certificate pair (\s-1RSA/DSA\s0) is installed, the last item installed will
236be checked. If e.g. the last item was a \s-1RSA\s0 certificate or key, the \s-1RSA\s0
984263bc
MD
237key/certificate pair will be checked. \fISSL_check_private_key()\fR performs
238the same check for \fBssl\fR. If no key/certificate was explicitly added for
239this \fBssl\fR, the last item added into \fBctx\fR will be checked.
e056f0e0
JR
240.SH "NOTES"
241.IX Header "NOTES"
242The internal certificate store of OpenSSL can hold two private key/certificate
243pairs at a time: one key/certificate of type \s-1RSA\s0 and one key/certificate
244of type \s-1DSA\s0. The certificate used depends on the cipher select, see
245also \fISSL_CTX_set_cipher_list\fR\|(3).
246.PP
984263bc 247When reading certificates and private keys from file, files of type
e056f0e0 248\&\s-1SSL_FILETYPE_ASN1\s0 (also known as \fB\s-1DER\s0\fR, binary encoding) can only contain
984263bc 249one certificate or private key, consequently
e056f0e0
JR
250\&\fISSL_CTX_use_certificate_chain_file()\fR is only applicable to \s-1PEM\s0 formatting.
251Files of type \s-1SSL_FILETYPE_PEM\s0 can contain more than one item.
984263bc 252.PP
e056f0e0 253\&\fISSL_CTX_use_certificate_chain_file()\fR adds the first certificate found
984263bc
MD
254in the file to the certificate store. The other certificates are added
255to the store of chain certificates using
e056f0e0 256\&\fISSL_CTX_add_extra_chain_cert\fR\|(3).
984263bc 257There exists only one extra chain store, so that the same chain is appended
e056f0e0 258to both types of certificates, \s-1RSA\s0 and \s-1DSA\s0! If it is not intended to use
984263bc 259both type of certificate at the same time, it is recommended to use the
e056f0e0
JR
260\&\fISSL_CTX_use_certificate_chain_file()\fR instead of the
261\&\fISSL_CTX_use_certificate_file()\fR function in order to allow the use of
262complete certificate chains even when no trusted \s-1CA\s0 storage is used or
263when the \s-1CA\s0 issuing the certificate shall not be added to the trusted
264\&\s-1CA\s0 storage.
984263bc
MD
265.PP
266If additional certificates are needed to complete the chain during the
e056f0e0
JR
267\&\s-1TLS\s0 negotiation, \s-1CA\s0 certificates are additionally looked up in the
268locations of trusted \s-1CA\s0 certificates, see
269\&\fISSL_CTX_load_verify_locations\fR\|(3).
984263bc
MD
270.PP
271The private keys loaded from file can be encrypted. In order to successfully
272load encrypted keys, a function returning the passphrase must have been
273supplied, see
e056f0e0 274\&\fISSL_CTX_set_default_passwd_cb\fR\|(3).
984263bc
MD
275(Certificate files might be encrypted as well from the technical point
276of view, it however does not make sense as the data in the certificate
277is considered public anyway.)
278.SH "RETURN VALUES"
e056f0e0 279.IX Header "RETURN VALUES"
984263bc
MD
280On success, the functions return 1.
281Otherwise check out the error stack to find out the reason.
282.SH "SEE ALSO"
a7d27d5a 283.IX Header "SEE ALSO"
e056f0e0
JR
284\&\fIssl\fR\|(3), \fISSL_new\fR\|(3), \fISSL_clear\fR\|(3),
285\&\fISSL_CTX_load_verify_locations\fR\|(3),
286\&\fISSL_CTX_set_default_passwd_cb\fR\|(3),
287\&\fISSL_CTX_set_cipher_list\fR\|(3),
288\&\fISSL_CTX_set_client_cert_cb\fR\|(3),
289\&\fISSL_CTX_add_extra_chain_cert\fR\|(3)