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