]>
Commit | Line | Data |
---|---|---|
3604a4d3 UM |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | SSL - OpenSSL SSL/TLS library | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
11b62699 | 10 | =head1 DESCRIPTION |
3604a4d3 UM |
11 | |
12 | The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and | |
13 | Transport Layer Security (TLS v1) protocols. It provides a rich API which is | |
14 | documented here. | |
15 | ||
9bd3bd22 UM |
16 | At first the library must be initialized; see |
17 | L<SSL_library_init(3)|SSL_library_init(3)>. | |
3604a4d3 | 18 | |
9bd3bd22 UM |
19 | Then an B<SSL_CTX> object is created as a framework to establish |
20 | TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>). | |
21 | Various options regarding certificates, algorithms etc. can be set | |
22 | in this object. | |
3604a4d3 | 23 | |
9bd3bd22 UM |
24 | When a network connection has been created, it can be assigned to an |
25 | B<SSL> object. After the B<SSL> object has been created using | |
26 | L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or | |
27 | L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network | |
28 | connection with the object. | |
3604a4d3 | 29 | |
9bd3bd22 UM |
30 | Then the TLS/SSL handshake is performed using |
31 | L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)> | |
32 | respectively. | |
33 | L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used | |
34 | to read and write data on the TLS/SSL connection. | |
35 | L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the | |
36 | TLS/SSL connection. | |
3604a4d3 UM |
37 | |
38 | =head1 DATA STRUCTURES | |
39 | ||
40 | Currently the OpenSSL B<ssl> library functions deals with the following data | |
41 | structures: | |
42 | ||
43 | =over 4 | |
44 | ||
45 | =item B<SSL_METHOD> (SSL Method) | |
46 | ||
47 | That's a dispatch structure describing the internal B<ssl> library | |
48 | methods/functions which implement the various protocol versions (SSLv1, SSLv2 | |
49 | and TLSv1). It's needed to create an B<SSL_CTX>. | |
50 | ||
51 | =item B<SSL_CIPHER> (SSL Cipher) | |
52 | ||
53 | This structure holds the algorithm information for a particular cipher which | |
54 | are a core part of the SSL/TLS protocol. The available ciphers are configured | |
55 | on a B<SSL_CTX> basis and the actually used ones are then part of the | |
56 | B<SSL_SESSION>. | |
57 | ||
58 | =item B<SSL_CTX> (SSL Context) | |
59 | ||
60 | That's the global context structure which is created by a server or client | |
61 | once per program life-time and which holds mainly default values for the | |
62 | B<SSL> structures which are later created for the connections. | |
63 | ||
64 | =item B<SSL_SESSION> (SSL Session) | |
65 | ||
37b08e83 | 66 | This is a structure containing the current TLS/SSL session details for a |
3604a4d3 UM |
67 | connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. |
68 | ||
69 | =item B<SSL> (SSL Connection) | |
70 | ||
71 | That's the main SSL/TLS structure which is created by a server or client per | |
72 | established connection. This actually is the core structure in the SSL API. | |
73 | Under run-time the application usually deals with this structure which has | |
74 | links to mostly all other structures. | |
75 | ||
76 | =back | |
77 | ||
9bd3bd22 UM |
78 | |
79 | =head1 HEADER FILES | |
80 | ||
81 | Currently the OpenSSL B<ssl> library provides the following C header files | |
82 | containing the prototypes for the data structures and and functions: | |
83 | ||
84 | =over 4 | |
85 | ||
86 | =item B<ssl.h> | |
87 | ||
88 | That's the common header file for the SSL/TLS API. Include it into your | |
89 | program to make the API of the B<ssl> library available. It internally | |
90 | includes both more private SSL headers and headers from the B<crypto> library. | |
91 | Whenever you need hard-core details on the internals of the SSL API, look | |
92 | inside this header file. | |
93 | ||
94 | =item B<ssl2.h> | |
95 | ||
96 | That's the sub header file dealing with the SSLv2 protocol only. | |
97 | I<Usually you don't have to include it explicitly because | |
98 | it's already included by ssl.h>. | |
99 | ||
100 | =item B<ssl3.h> | |
101 | ||
102 | That's the sub header file dealing with the SSLv3 protocol only. | |
103 | I<Usually you don't have to include it explicitly because | |
104 | it's already included by ssl.h>. | |
105 | ||
106 | =item B<ssl23.h> | |
107 | ||
108 | That's the sub header file dealing with the combined use of the SSLv2 and | |
109 | SSLv3 protocols. | |
110 | I<Usually you don't have to include it explicitly because | |
111 | it's already included by ssl.h>. | |
112 | ||
113 | =item B<tls1.h> | |
114 | ||
115 | That's the sub header file dealing with the TLSv1 protocol only. | |
116 | I<Usually you don't have to include it explicitly because | |
117 | it's already included by ssl.h>. | |
118 | ||
119 | =back | |
120 | ||
3604a4d3 UM |
121 | =head1 API FUNCTIONS |
122 | ||
123 | Currently the OpenSSL B<ssl> library exports 214 API functions. | |
124 | They are documented in the following: | |
125 | ||
126 | =head2 DEALING WITH PROTOCOL METHODS | |
127 | ||
128 | Here we document the various API functions which deal with the SSL/TLS | |
129 | protocol methods defined in B<SSL_METHOD> structures. | |
130 | ||
131 | =over 4 | |
132 | ||
4ebb342f | 133 | =item const SSL_METHOD *B<SSLv2_client_method>(void); |
3604a4d3 UM |
134 | |
135 | Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. | |
136 | ||
4ebb342f | 137 | =item const SSL_METHOD *B<SSLv2_server_method>(void); |
3604a4d3 UM |
138 | |
139 | Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. | |
140 | ||
4ebb342f | 141 | =item const SSL_METHOD *B<SSLv2_method>(void); |
3604a4d3 UM |
142 | |
143 | Constructor for the SSLv2 SSL_METHOD structure for combined client and server. | |
144 | ||
4ebb342f | 145 | =item const SSL_METHOD *B<SSLv3_client_method>(void); |
3604a4d3 UM |
146 | |
147 | Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. | |
148 | ||
4ebb342f | 149 | =item const SSL_METHOD *B<SSLv3_server_method>(void); |
3604a4d3 UM |
150 | |
151 | Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. | |
152 | ||
4ebb342f | 153 | =item const SSL_METHOD *B<SSLv3_method>(void); |
3604a4d3 UM |
154 | |
155 | Constructor for the SSLv3 SSL_METHOD structure for combined client and server. | |
156 | ||
4ebb342f | 157 | =item const SSL_METHOD *B<TLSv1_client_method>(void); |
3604a4d3 UM |
158 | |
159 | Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. | |
160 | ||
735ebc2d | 161 | =item const SSL_METHOD *B<TLSv1_server_method>(void); |
3604a4d3 UM |
162 | |
163 | Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. | |
164 | ||
4ebb342f | 165 | =item const SSL_METHOD *B<TLSv1_method>(void); |
3604a4d3 UM |
166 | |
167 | Constructor for the TLSv1 SSL_METHOD structure for combined client and server. | |
168 | ||
169 | =back | |
170 | ||
171 | =head2 DEALING WITH CIPHERS | |
172 | ||
173 | Here we document the various API functions which deal with the SSL/TLS | |
174 | ciphers defined in B<SSL_CIPHER> structures. | |
175 | ||
176 | =over 4 | |
177 | ||
178 | =item char *B<SSL_CIPHER_description>(SSL_CIPHER *cipher, char *buf, int len); | |
179 | ||
180 | Write a string to I<buf> (with a maximum size of I<len>) containing a human | |
181 | readable description of I<cipher>. Returns I<buf>. | |
182 | ||
183 | =item int B<SSL_CIPHER_get_bits>(SSL_CIPHER *cipher, int *alg_bits); | |
184 | ||
185 | Determine the number of bits in I<cipher>. Because of export crippled ciphers | |
186 | there are two bits: The bits the algorithm supports in general (stored to | |
187 | I<alg_bits>) and the bits which are actually used (the return value). | |
188 | ||
d49f3797 | 189 | =item const char *B<SSL_CIPHER_get_name>(SSL_CIPHER *cipher); |
3604a4d3 UM |
190 | |
191 | Return the internal name of I<cipher> as a string. These are the various | |
192 | strings defined by the I<SSL2_TXT_xxx>, I<SSL3_TXT_xxx> and I<TLS1_TXT_xxx> | |
193 | definitions in the header files. | |
194 | ||
195 | =item char *B<SSL_CIPHER_get_version>(SSL_CIPHER *cipher); | |
196 | ||
197 | Returns a string like "C<TLSv1/SSLv3>" or "C<SSLv2>" which indicates the | |
198 | SSL/TLS protocol version to which I<cipher> belongs (i.e. where it was defined | |
199 | in the specification the first time). | |
200 | ||
201 | =back | |
202 | ||
203 | =head2 DEALING WITH PROTOCOL CONTEXTS | |
204 | ||
205 | Here we document the various API functions which deal with the SSL/TLS | |
206 | protocol context defined in the B<SSL_CTX> structure. | |
207 | ||
208 | =over 4 | |
209 | ||
210 | =item int B<SSL_CTX_add_client_CA>(SSL_CTX *ctx, X509 *x); | |
211 | ||
212 | =item long B<SSL_CTX_add_extra_chain_cert>(SSL_CTX *ctx, X509 *x509); | |
213 | ||
214 | =item int B<SSL_CTX_add_session>(SSL_CTX *ctx, SSL_SESSION *c); | |
215 | ||
c3e64028 | 216 | =item int B<SSL_CTX_check_private_key>(const SSL_CTX *ctx); |
3604a4d3 UM |
217 | |
218 | =item long B<SSL_CTX_ctrl>(SSL_CTX *ctx, int cmd, long larg, char *parg); | |
219 | ||
220 | =item void B<SSL_CTX_flush_sessions>(SSL_CTX *s, long t); | |
221 | ||
222 | =item void B<SSL_CTX_free>(SSL_CTX *a); | |
223 | ||
224 | =item char *B<SSL_CTX_get_app_data>(SSL_CTX *ctx); | |
225 | ||
226 | =item X509_STORE *B<SSL_CTX_get_cert_store>(SSL_CTX *ctx); | |
227 | ||
c3e64028 | 228 | =item STACK *B<SSL_CTX_get_client_CA_list>(const SSL_CTX *ctx); |
3604a4d3 UM |
229 | |
230 | =item int (*B<SSL_CTX_get_client_cert_cb>(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); | |
231 | ||
c3e64028 | 232 | =item char *B<SSL_CTX_get_ex_data>(const SSL_CTX *s, int idx); |
3604a4d3 UM |
233 | |
234 | =item int B<SSL_CTX_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) | |
235 | ||
236 | =item void (*B<SSL_CTX_get_info_callback>(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); | |
237 | ||
c3e64028 | 238 | =item int B<SSL_CTX_get_quiet_shutdown>(const SSL_CTX *ctx); |
3604a4d3 UM |
239 | |
240 | =item int B<SSL_CTX_get_session_cache_mode>(SSL_CTX *ctx); | |
241 | ||
c3e64028 | 242 | =item long B<SSL_CTX_get_timeout>(const SSL_CTX *ctx); |
3604a4d3 | 243 | |
c3e64028 | 244 | =item int (*B<SSL_CTX_get_verify_callback>(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); |
3604a4d3 UM |
245 | |
246 | =item int B<SSL_CTX_get_verify_mode>(SSL_CTX *ctx); | |
247 | ||
248 | =item int B<SSL_CTX_load_verify_locations>(SSL_CTX *ctx, char *CAfile, char *CApath); | |
249 | ||
250 | =item long B<SSL_CTX_need_tmp_RSA>(SSL_CTX *ctx); | |
251 | ||
4ebb342f | 252 | =item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth); |
3604a4d3 UM |
253 | |
254 | =item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c); | |
255 | ||
256 | =item int B<SSL_CTX_sess_accept>(SSL_CTX *ctx); | |
257 | ||
258 | =item int B<SSL_CTX_sess_accept_good>(SSL_CTX *ctx); | |
259 | ||
260 | =item int B<SSL_CTX_sess_accept_renegotiate>(SSL_CTX *ctx); | |
261 | ||
262 | =item int B<SSL_CTX_sess_cache_full>(SSL_CTX *ctx); | |
263 | ||
264 | =item int B<SSL_CTX_sess_cb_hits>(SSL_CTX *ctx); | |
265 | ||
266 | =item int B<SSL_CTX_sess_connect>(SSL_CTX *ctx); | |
267 | ||
268 | =item int B<SSL_CTX_sess_connect_good>(SSL_CTX *ctx); | |
269 | ||
270 | =item int B<SSL_CTX_sess_connect_renegotiate>(SSL_CTX *ctx); | |
271 | ||
272 | =item int B<SSL_CTX_sess_get_cache_size>(SSL_CTX *ctx); | |
273 | ||
274 | =item SSL_SESSION *(*B<SSL_CTX_sess_get_get_cb>(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); | |
275 | ||
276 | =item int (*B<SSL_CTX_sess_get_new_cb>(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); | |
277 | ||
278 | =item void (*B<SSL_CTX_sess_get_remove_cb>(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); | |
279 | ||
280 | =item int B<SSL_CTX_sess_hits>(SSL_CTX *ctx); | |
281 | ||
282 | =item int B<SSL_CTX_sess_misses>(SSL_CTX *ctx); | |
283 | ||
284 | =item int B<SSL_CTX_sess_number>(SSL_CTX *ctx); | |
285 | ||
286 | =item void B<SSL_CTX_sess_set_cache_size>(SSL_CTX *ctx,t); | |
287 | ||
288 | =item void B<SSL_CTX_sess_set_get_cb>(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); | |
289 | ||
290 | =item void B<SSL_CTX_sess_set_new_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); | |
291 | ||
292 | =item void B<SSL_CTX_sess_set_remove_cb>(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); | |
293 | ||
294 | =item int B<SSL_CTX_sess_timeouts>(SSL_CTX *ctx); | |
295 | ||
296 | =item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx); | |
297 | ||
298 | =item void B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg); | |
299 | ||
300 | =item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs); | |
301 | ||
c4068186 | 302 | =item void B<SSL_CTX_set_cert_verify_cb>(SSL_CTX *ctx, int (*cb)(), char *arg) |
3604a4d3 UM |
303 | |
304 | =item int B<SSL_CTX_set_cipher_list>(SSL_CTX *ctx, char *str); | |
305 | ||
306 | =item void B<SSL_CTX_set_client_CA_list>(SSL_CTX *ctx, STACK *list); | |
307 | ||
308 | =item void B<SSL_CTX_set_client_cert_cb>(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); | |
309 | ||
310 | =item void B<SSL_CTX_set_default_passwd_cb>(SSL_CTX *ctx, int (*cb);(void)) | |
311 | ||
312 | =item void B<SSL_CTX_set_default_read_ahead>(SSL_CTX *ctx, int m); | |
313 | ||
314 | =item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx); | |
315 | ||
316 | =item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg); | |
317 | ||
318 | =item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); | |
319 | ||
65123f80 BM |
320 | =item void B<SSL_CTX_set_msg_callback>(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); |
321 | ||
322 | =item void B<SSL_CTX_set_msg_callback_arg>(SSL_CTX *ctx, void *arg); | |
323 | ||
3604a4d3 UM |
324 | =item void B<SSL_CTX_set_options>(SSL_CTX *ctx, unsigned long op); |
325 | ||
326 | =item void B<SSL_CTX_set_quiet_shutdown>(SSL_CTX *ctx, int mode); | |
327 | ||
328 | =item void B<SSL_CTX_set_session_cache_mode>(SSL_CTX *ctx, int mode); | |
329 | ||
4ebb342f | 330 | =item int B<SSL_CTX_set_ssl_version>(SSL_CTX *ctx, const SSL_METHOD *meth); |
3604a4d3 UM |
331 | |
332 | =item void B<SSL_CTX_set_timeout>(SSL_CTX *ctx, long t); | |
333 | ||
334 | =item long B<SSL_CTX_set_tmp_dh>(SSL_CTX* ctx, DH *dh); | |
335 | ||
336 | =item long B<SSL_CTX_set_tmp_dh_callback>(SSL_CTX *ctx, DH *(*cb)(void)); | |
337 | ||
338 | =item long B<SSL_CTX_set_tmp_rsa>(SSL_CTX *ctx, RSA *rsa); | |
339 | ||
340 | =item SSL_CTX_set_tmp_rsa_callback | |
341 | ||
342 | C<long B<SSL_CTX_set_tmp_rsa_callback>(SSL_CTX *B<ctx>, RSA *(*B<cb>)(SSL *B<ssl>, int B<export>, int B<keylength>));> | |
343 | ||
344 | Sets the callback which will be called when a temporary private key is | |
345 | required. The B<C<export>> flag will be set if the reason for needing | |
346 | a temp key is that an export ciphersuite is in use, in which case, | |
347 | B<C<keylength>> will contain the required keylength in bits. Generate a key of | |
348 | appropriate size (using ???) and return it. | |
349 | ||
350 | =item SSL_set_tmp_rsa_callback | |
351 | ||
352 | long B<SSL_set_tmp_rsa_callback>(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); | |
353 | ||
84d828ab | 354 | The same as B<SSL_CTX_set_tmp_rsa_callback>, except it operates on an SSL |
3604a4d3 UM |
355 | session instead of a context. |
356 | ||
357 | =item void B<SSL_CTX_set_verify>(SSL_CTX *ctx, int mode, int (*cb);(void)) | |
358 | ||
359 | =item int B<SSL_CTX_use_PrivateKey>(SSL_CTX *ctx, EVP_PKEY *pkey); | |
360 | ||
361 | =item int B<SSL_CTX_use_PrivateKey_ASN1>(int type, SSL_CTX *ctx, unsigned char *d, long len); | |
362 | ||
363 | =item int B<SSL_CTX_use_PrivateKey_file>(SSL_CTX *ctx, char *file, int type); | |
364 | ||
365 | =item int B<SSL_CTX_use_RSAPrivateKey>(SSL_CTX *ctx, RSA *rsa); | |
366 | ||
367 | =item int B<SSL_CTX_use_RSAPrivateKey_ASN1>(SSL_CTX *ctx, unsigned char *d, long len); | |
368 | ||
369 | =item int B<SSL_CTX_use_RSAPrivateKey_file>(SSL_CTX *ctx, char *file, int type); | |
370 | ||
371 | =item int B<SSL_CTX_use_certificate>(SSL_CTX *ctx, X509 *x); | |
372 | ||
373 | =item int B<SSL_CTX_use_certificate_ASN1>(SSL_CTX *ctx, int len, unsigned char *d); | |
374 | ||
375 | =item int B<SSL_CTX_use_certificate_file>(SSL_CTX *ctx, char *file, int type); | |
376 | ||
a25f9adc DSH |
377 | =item X509 *B<SSL_CTX_get0_certificate>(const SSL_CTX *ctx); |
378 | ||
379 | =item EVP_PKEY *B<SSL_CTX_get0_privatekey>(const SSL_CTX *ctx); | |
380 | ||
ddac1974 NL |
381 | =item void B<SSL_CTX_set_psk_client_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); |
382 | ||
383 | =item int B<SSL_CTX_use_psk_identity_hint>(SSL_CTX *ctx, const char *hint); | |
384 | ||
385 | =item void B<SSL_CTX_set_psk_server_callback>(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); | |
386 | ||
387 | ||
388 | ||
389 | ||
3604a4d3 UM |
390 | =back |
391 | ||
392 | =head2 DEALING WITH SESSIONS | |
393 | ||
394 | Here we document the various API functions which deal with the SSL/TLS | |
395 | sessions defined in the B<SSL_SESSION> structures. | |
396 | ||
397 | =over 4 | |
398 | ||
c3e64028 | 399 | =item int B<SSL_SESSION_cmp>(const SSL_SESSION *a, const SSL_SESSION *b); |
3604a4d3 UM |
400 | |
401 | =item void B<SSL_SESSION_free>(SSL_SESSION *ss); | |
402 | ||
403 | =item char *B<SSL_SESSION_get_app_data>(SSL_SESSION *s); | |
404 | ||
c3e64028 | 405 | =item char *B<SSL_SESSION_get_ex_data>(const SSL_SESSION *s, int idx); |
3604a4d3 UM |
406 | |
407 | =item int B<SSL_SESSION_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) | |
408 | ||
c3e64028 | 409 | =item long B<SSL_SESSION_get_time>(const SSL_SESSION *s); |
3604a4d3 | 410 | |
c3e64028 | 411 | =item long B<SSL_SESSION_get_timeout>(const SSL_SESSION *s); |
3604a4d3 | 412 | |
c3e64028 | 413 | =item unsigned long B<SSL_SESSION_hash>(const SSL_SESSION *a); |
3604a4d3 UM |
414 | |
415 | =item SSL_SESSION *B<SSL_SESSION_new>(void); | |
416 | ||
c3e64028 | 417 | =item int B<SSL_SESSION_print>(BIO *bp, const SSL_SESSION *x); |
3604a4d3 | 418 | |
c3e64028 | 419 | =item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x); |
3604a4d3 UM |
420 | |
421 | =item void B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a); | |
422 | ||
423 | =item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg); | |
424 | ||
425 | =item long B<SSL_SESSION_set_time>(SSL_SESSION *s, long t); | |
426 | ||
427 | =item long B<SSL_SESSION_set_timeout>(SSL_SESSION *s, long t); | |
428 | ||
429 | =back | |
430 | ||
431 | =head2 DEALING WITH CONNECTIONS | |
432 | ||
433 | Here we document the various API functions which deal with the SSL/TLS | |
434 | connection defined in the B<SSL> structure. | |
435 | ||
436 | =over 4 | |
437 | ||
438 | =item int B<SSL_accept>(SSL *ssl); | |
439 | ||
440 | =item int B<SSL_add_dir_cert_subjects_to_stack>(STACK *stack, const char *dir); | |
441 | ||
442 | =item int B<SSL_add_file_cert_subjects_to_stack>(STACK *stack, const char *file); | |
443 | ||
444 | =item int B<SSL_add_client_CA>(SSL *ssl, X509 *x); | |
445 | ||
446 | =item char *B<SSL_alert_desc_string>(int value); | |
447 | ||
448 | =item char *B<SSL_alert_desc_string_long>(int value); | |
449 | ||
450 | =item char *B<SSL_alert_type_string>(int value); | |
451 | ||
452 | =item char *B<SSL_alert_type_string_long>(int value); | |
453 | ||
c3e64028 | 454 | =item int B<SSL_check_private_key>(const SSL *ssl); |
3604a4d3 UM |
455 | |
456 | =item void B<SSL_clear>(SSL *ssl); | |
457 | ||
458 | =item long B<SSL_clear_num_renegotiations>(SSL *ssl); | |
459 | ||
460 | =item int B<SSL_connect>(SSL *ssl); | |
461 | ||
c3e64028 | 462 | =item void B<SSL_copy_session_id>(SSL *t, const SSL *f); |
3604a4d3 UM |
463 | |
464 | =item long B<SSL_ctrl>(SSL *ssl, int cmd, long larg, char *parg); | |
465 | ||
466 | =item int B<SSL_do_handshake>(SSL *ssl); | |
467 | ||
468 | =item SSL *B<SSL_dup>(SSL *ssl); | |
469 | ||
470 | =item STACK *B<SSL_dup_CA_list>(STACK *sk); | |
471 | ||
472 | =item void B<SSL_free>(SSL *ssl); | |
473 | ||
c3e64028 | 474 | =item SSL_CTX *B<SSL_get_SSL_CTX>(const SSL *ssl); |
3604a4d3 UM |
475 | |
476 | =item char *B<SSL_get_app_data>(SSL *ssl); | |
477 | ||
c3e64028 | 478 | =item X509 *B<SSL_get_certificate>(const SSL *ssl); |
3604a4d3 | 479 | |
c3e64028 | 480 | =item const char *B<SSL_get_cipher>(const SSL *ssl); |
3604a4d3 | 481 | |
c3e64028 | 482 | =item int B<SSL_get_cipher_bits>(const SSL *ssl, int *alg_bits); |
3604a4d3 | 483 | |
c3e64028 | 484 | =item char *B<SSL_get_cipher_list>(const SSL *ssl, int n); |
3604a4d3 | 485 | |
c3e64028 | 486 | =item char *B<SSL_get_cipher_name>(const SSL *ssl); |
3604a4d3 | 487 | |
c3e64028 | 488 | =item char *B<SSL_get_cipher_version>(const SSL *ssl); |
3604a4d3 | 489 | |
c3e64028 | 490 | =item STACK *B<SSL_get_ciphers>(const SSL *ssl); |
3604a4d3 | 491 | |
c3e64028 | 492 | =item STACK *B<SSL_get_client_CA_list>(const SSL *ssl); |
3604a4d3 UM |
493 | |
494 | =item SSL_CIPHER *B<SSL_get_current_cipher>(SSL *ssl); | |
495 | ||
c3e64028 | 496 | =item long B<SSL_get_default_timeout>(const SSL *ssl); |
3604a4d3 | 497 | |
c3e64028 | 498 | =item int B<SSL_get_error>(const SSL *ssl, int i); |
3604a4d3 | 499 | |
c3e64028 | 500 | =item char *B<SSL_get_ex_data>(const SSL *ssl, int idx); |
3604a4d3 UM |
501 | |
502 | =item int B<SSL_get_ex_data_X509_STORE_CTX_idx>(void); | |
503 | ||
504 | =item int B<SSL_get_ex_new_index>(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) | |
505 | ||
c3e64028 | 506 | =item int B<SSL_get_fd>(const SSL *ssl); |
3604a4d3 | 507 | |
c3e64028 | 508 | =item void (*B<SSL_get_info_callback>(const SSL *ssl);)() |
3604a4d3 | 509 | |
c3e64028 | 510 | =item STACK *B<SSL_get_peer_cert_chain>(const SSL *ssl); |
3604a4d3 | 511 | |
c3e64028 | 512 | =item X509 *B<SSL_get_peer_certificate>(const SSL *ssl); |
3604a4d3 | 513 | |
a25f9adc | 514 | =item EVP_PKEY *B<SSL_get_privatekey>(const SSL *ssl); |
3604a4d3 | 515 | |
c3e64028 | 516 | =item int B<SSL_get_quiet_shutdown>(const SSL *ssl); |
3604a4d3 | 517 | |
c3e64028 | 518 | =item BIO *B<SSL_get_rbio>(const SSL *ssl); |
3604a4d3 | 519 | |
c3e64028 | 520 | =item int B<SSL_get_read_ahead>(const SSL *ssl); |
3604a4d3 | 521 | |
c3e64028 | 522 | =item SSL_SESSION *B<SSL_get_session>(const SSL *ssl); |
3604a4d3 | 523 | |
c3e64028 | 524 | =item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len); |
3604a4d3 | 525 | |
c3e64028 | 526 | =item int B<SSL_get_shutdown>(const SSL *ssl); |
3604a4d3 | 527 | |
4ebb342f | 528 | =item const SSL_METHOD *B<SSL_get_ssl_method>(SSL *ssl); |
3604a4d3 | 529 | |
c3e64028 | 530 | =item int B<SSL_get_state>(const SSL *ssl); |
3604a4d3 | 531 | |
c3e64028 | 532 | =item long B<SSL_get_time>(const SSL *ssl); |
3604a4d3 | 533 | |
c3e64028 | 534 | =item long B<SSL_get_timeout>(const SSL *ssl); |
3604a4d3 | 535 | |
c3e64028 | 536 | =item int (*B<SSL_get_verify_callback>(const SSL *ssl))(int,X509_STORE_CTX *) |
3604a4d3 | 537 | |
c3e64028 | 538 | =item int B<SSL_get_verify_mode>(const SSL *ssl); |
3604a4d3 | 539 | |
c3e64028 | 540 | =item long B<SSL_get_verify_result>(const SSL *ssl); |
3604a4d3 | 541 | |
c3e64028 | 542 | =item char *B<SSL_get_version>(const SSL *ssl); |
3604a4d3 | 543 | |
c3e64028 | 544 | =item BIO *B<SSL_get_wbio>(const SSL *ssl); |
3604a4d3 UM |
545 | |
546 | =item int B<SSL_in_accept_init>(SSL *ssl); | |
547 | ||
548 | =item int B<SSL_in_before>(SSL *ssl); | |
549 | ||
550 | =item int B<SSL_in_connect_init>(SSL *ssl); | |
551 | ||
552 | =item int B<SSL_in_init>(SSL *ssl); | |
553 | ||
554 | =item int B<SSL_is_init_finished>(SSL *ssl); | |
555 | ||
556 | =item STACK *B<SSL_load_client_CA_file>(char *file); | |
557 | ||
558 | =item void B<SSL_load_error_strings>(void); | |
559 | ||
560 | =item SSL *B<SSL_new>(SSL_CTX *ctx); | |
561 | ||
562 | =item long B<SSL_num_renegotiations>(SSL *ssl); | |
563 | ||
e34cfcf7 | 564 | =item int B<SSL_peek>(SSL *ssl, void *buf, int num); |
3604a4d3 | 565 | |
c3e64028 | 566 | =item int B<SSL_pending>(const SSL *ssl); |
3604a4d3 | 567 | |
e34cfcf7 | 568 | =item int B<SSL_read>(SSL *ssl, void *buf, int num); |
3604a4d3 UM |
569 | |
570 | =item int B<SSL_renegotiate>(SSL *ssl); | |
571 | ||
572 | =item char *B<SSL_rstate_string>(SSL *ssl); | |
573 | ||
574 | =item char *B<SSL_rstate_string_long>(SSL *ssl); | |
575 | ||
576 | =item long B<SSL_session_reused>(SSL *ssl); | |
577 | ||
578 | =item void B<SSL_set_accept_state>(SSL *ssl); | |
579 | ||
580 | =item void B<SSL_set_app_data>(SSL *ssl, char *arg); | |
581 | ||
582 | =item void B<SSL_set_bio>(SSL *ssl, BIO *rbio, BIO *wbio); | |
583 | ||
584 | =item int B<SSL_set_cipher_list>(SSL *ssl, char *str); | |
585 | ||
586 | =item void B<SSL_set_client_CA_list>(SSL *ssl, STACK *list); | |
587 | ||
588 | =item void B<SSL_set_connect_state>(SSL *ssl); | |
589 | ||
590 | =item int B<SSL_set_ex_data>(SSL *ssl, int idx, char *arg); | |
591 | ||
592 | =item int B<SSL_set_fd>(SSL *ssl, int fd); | |
593 | ||
594 | =item void B<SSL_set_info_callback>(SSL *ssl, void (*cb);(void)) | |
595 | ||
65123f80 BM |
596 | =item void B<SSL_set_msg_callback>(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); |
597 | ||
598 | =item void B<SSL_set_msg_callback_arg>(SSL *ctx, void *arg); | |
599 | ||
3604a4d3 UM |
600 | =item void B<SSL_set_options>(SSL *ssl, unsigned long op); |
601 | ||
602 | =item void B<SSL_set_quiet_shutdown>(SSL *ssl, int mode); | |
603 | ||
604 | =item void B<SSL_set_read_ahead>(SSL *ssl, int yes); | |
605 | ||
606 | =item int B<SSL_set_rfd>(SSL *ssl, int fd); | |
607 | ||
608 | =item int B<SSL_set_session>(SSL *ssl, SSL_SESSION *session); | |
609 | ||
610 | =item void B<SSL_set_shutdown>(SSL *ssl, int mode); | |
611 | ||
4ebb342f | 612 | =item int B<SSL_set_ssl_method>(SSL *ssl, const SSL_METHOD *meth); |
3604a4d3 UM |
613 | |
614 | =item void B<SSL_set_time>(SSL *ssl, long t); | |
615 | ||
616 | =item void B<SSL_set_timeout>(SSL *ssl, long t); | |
617 | ||
618 | =item void B<SSL_set_verify>(SSL *ssl, int mode, int (*callback);(void)) | |
619 | ||
620 | =item void B<SSL_set_verify_result>(SSL *ssl, long arg); | |
621 | ||
622 | =item int B<SSL_set_wfd>(SSL *ssl, int fd); | |
623 | ||
624 | =item int B<SSL_shutdown>(SSL *ssl); | |
625 | ||
c3e64028 | 626 | =item int B<SSL_state>(const SSL *ssl); |
3604a4d3 | 627 | |
c3e64028 | 628 | =item char *B<SSL_state_string>(const SSL *ssl); |
3604a4d3 | 629 | |
c3e64028 | 630 | =item char *B<SSL_state_string_long>(const SSL *ssl); |
3604a4d3 UM |
631 | |
632 | =item long B<SSL_total_renegotiations>(SSL *ssl); | |
633 | ||
634 | =item int B<SSL_use_PrivateKey>(SSL *ssl, EVP_PKEY *pkey); | |
635 | ||
636 | =item int B<SSL_use_PrivateKey_ASN1>(int type, SSL *ssl, unsigned char *d, long len); | |
637 | ||
638 | =item int B<SSL_use_PrivateKey_file>(SSL *ssl, char *file, int type); | |
639 | ||
640 | =item int B<SSL_use_RSAPrivateKey>(SSL *ssl, RSA *rsa); | |
641 | ||
642 | =item int B<SSL_use_RSAPrivateKey_ASN1>(SSL *ssl, unsigned char *d, long len); | |
643 | ||
644 | =item int B<SSL_use_RSAPrivateKey_file>(SSL *ssl, char *file, int type); | |
645 | ||
646 | =item int B<SSL_use_certificate>(SSL *ssl, X509 *x); | |
647 | ||
648 | =item int B<SSL_use_certificate_ASN1>(SSL *ssl, int len, unsigned char *d); | |
649 | ||
650 | =item int B<SSL_use_certificate_file>(SSL *ssl, char *file, int type); | |
651 | ||
c3e64028 | 652 | =item int B<SSL_version>(const SSL *ssl); |
3604a4d3 | 653 | |
c3e64028 | 654 | =item int B<SSL_want>(const SSL *ssl); |
3604a4d3 | 655 | |
c3e64028 | 656 | =item int B<SSL_want_nothing>(const SSL *ssl); |
3604a4d3 | 657 | |
c3e64028 | 658 | =item int B<SSL_want_read>(const SSL *ssl); |
3604a4d3 | 659 | |
c3e64028 | 660 | =item int B<SSL_want_write>(const SSL *ssl); |
3604a4d3 | 661 | |
c3e64028 | 662 | =item int B<SSL_want_x509_lookup>(const SSL *ssl); |
3604a4d3 | 663 | |
e34cfcf7 | 664 | =item int B<SSL_write>(SSL *ssl, const void *buf, int num); |
3604a4d3 | 665 | |
ddac1974 NL |
666 | =item void B<SSL_set_psk_client_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); |
667 | ||
668 | =item int B<SSL_use_psk_identity_hint>(SSL *ssl, const char *hint); | |
669 | ||
670 | =item void B<SSL_set_psk_server_callback>(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); | |
671 | ||
672 | =item const char *B<SSL_get_psk_identity_hint>(SSL *ssl); | |
673 | ||
674 | =item const char *B<SSL_get_psk_identity>(SSL *ssl); | |
675 | ||
3604a4d3 UM |
676 | =back |
677 | ||
678 | =head1 SEE ALSO | |
679 | ||
20ead2c6 | 680 | L<openssl(1)|openssl(1)>, L<crypto(3)|crypto(3)>, |
53e44d90 | 681 | L<SSL_accept(3)|SSL_accept(3)>, L<SSL_clear(3)|SSL_clear(3)>, |
356c06c7 | 682 | L<SSL_connect(3)|SSL_connect(3)>, |
553615f5 | 683 | L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>, |
336736ef | 684 | L<SSL_COMP_add_compression_method(3)|SSL_COMP_add_compression_method(3)>, |
66ebbb6a | 685 | L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, |
0bc6597d | 686 | L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>, |
d59c3e50 | 687 | L<SSL_CTX_ctrl(3)|SSL_CTX_ctrl(3)>, |
0bc6597d | 688 | L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, |
e58d808a | 689 | L<SSL_CTX_get_ex_new_index(3)|SSL_CTX_get_ex_new_index(3)>, |
553615f5 | 690 | L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, |
356c06c7 RL |
691 | L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)> |
692 | L<SSL_CTX_new(3)|SSL_CTX_new(3)>, | |
41ecaba9 | 693 | L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, |
0bc6597d | 694 | L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>, |
8cbceba6 | 695 | L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>, |
7b9cb4a2 | 696 | L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>, |
141e5849 | 697 | L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>, |
c4068186 | 698 | L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, |
397ba0f0 | 699 | L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, |
66ebbb6a | 700 | L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, |
f0d6ee6b | 701 | L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, |
66ebbb6a | 702 | L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, |
3cdc8ad0 | 703 | L<SSL_CTX_set_generate_session_id(3)|SSL_CTX_set_generate_session_id(3)>, |
f1b28074 | 704 | L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>, |
c0f5dd07 | 705 | L<SSL_CTX_set_max_cert_list(3)|SSL_CTX_set_max_cert_list(3)>, |
f282ca74 | 706 | L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, |
65123f80 | 707 | L<SSL_CTX_set_msg_callback(3)|SSL_CTX_set_msg_callback(3)>, |
7b9cb4a2 | 708 | L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, |
cdd7c3ce | 709 | L<SSL_CTX_set_quiet_shutdown(3)|SSL_CTX_set_quiet_shutdown(3)>, |
8cbceba6 | 710 | L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, |
cd6aa710 | 711 | L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>, |
69431c29 | 712 | L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>, |
0bc6597d | 713 | L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>, |
4db48ec0 LJ |
714 | L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, |
715 | L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, | |
553615f5 | 716 | L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, |
66ebbb6a | 717 | L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, |
a403188f | 718 | L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>, |
02b7ec88 | 719 | L<SSL_do_handshake(3)|SSL_do_handshake(3)>, |
a52877a2 | 720 | L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, |
69431c29 | 721 | L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, |
356c06c7 | 722 | L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, |
52129c0b | 723 | L<SSL_get_default_timeout(3)|SSL_get_default_timeout(3)>, |
751b5e8f LJ |
724 | L<SSL_get_error(3)|SSL_get_error(3)>, |
725 | L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, | |
726 | L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, | |
727 | L<SSL_get_fd(3)|SSL_get_fd(3)>, | |
69431c29 | 728 | L<SSL_get_peer_cert_chain(3)|SSL_get_peer_cert_chain(3)>, |
53e44d90 | 729 | L<SSL_get_rbio(3)|SSL_get_rbio(3)>, |
69431c29 UM |
730 | L<SSL_get_session(3)|SSL_get_session(3)>, |
731 | L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, | |
2c1571b4 | 732 | L<SSL_get_version(3)|SSL_get_version(3)>, |
356c06c7 RL |
733 | L<SSL_library_init(3)|SSL_library_init(3)>, |
734 | L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, | |
735 | L<SSL_new(3)|SSL_new(3)>, | |
2d3b6a5b LJ |
736 | L<SSL_pending(3)|SSL_pending(3)>, |
737 | L<SSL_read(3)|SSL_read(3)>, | |
11c8f0b7 | 738 | L<SSL_rstate_string(3)|SSL_rstate_string(3)>, |
2d3b6a5b LJ |
739 | L<SSL_session_reused(3)|SSL_session_reused(3)>, |
740 | L<SSL_set_bio(3)|SSL_set_bio(3)>, | |
b72ff470 | 741 | L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, |
2d3b6a5b | 742 | L<SSL_set_fd(3)|SSL_set_fd(3)>, |
53e44d90 | 743 | L<SSL_set_session(3)|SSL_set_session(3)>, |
8e495e4a | 744 | L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, |
2d3b6a5b | 745 | L<SSL_shutdown(3)|SSL_shutdown(3)>, |
11c8f0b7 | 746 | L<SSL_state_string(3)|SSL_state_string(3)>, |
c1497b4d | 747 | L<SSL_want(3)|SSL_want(3)>, |
2d3b6a5b | 748 | L<SSL_write(3)|SSL_write(3)>, |
e58d808a | 749 | L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, |
8cbceba6 | 750 | L<SSL_SESSION_get_ex_new_index(3)|SSL_SESSION_get_ex_new_index(3)>, |
0bc6597d | 751 | L<SSL_SESSION_get_time(3)|SSL_SESSION_get_time(3)>, |
ddac1974 NL |
752 | L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, |
753 | L<SSL_CTX_set_psk_client_callback(3)|SSL_CTX_set_psk_client_callback(3)>, | |
754 | L<SSL_CTX_use_psk_identity_hint(3)|SSL_CTX_use_psk_identity_hint(3)>, | |
755 | L<SSL_get_psk_identity(3)|SSL_get_psk_identity(3)> | |
3604a4d3 UM |
756 | |
757 | =head1 HISTORY | |
758 | ||
bb075f88 | 759 | The L<ssl(3)|ssl(3)> document appeared in OpenSSL 0.9.2 |
3604a4d3 UM |
760 | |
761 | =cut | |
762 |