]>
Commit | Line | Data |
---|---|---|
f282ca74 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); | |
12 | long SSL_set_mode(SSL *ssl, long mode); | |
13 | ||
14 | long SSL_CTX_get_mode(SSL_CTX *ctx); | |
15 | long SSL_get_mode(SSL *ssl); | |
16 | ||
17 | =head1 DESCRIPTION | |
18 | ||
19 | SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>. | |
20 | Options already set before are not cleared. | |
21 | ||
22 | SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>. | |
23 | Options already set before are not cleared. | |
24 | ||
25 | SSL_CTX_get_mode() returns the mode set for B<ctx>. | |
26 | ||
27 | SSL_get_mode() returns the mode set for B<ssl>. | |
28 | ||
29 | =head1 NOTES | |
30 | ||
31 | The following mode changes are available: | |
32 | ||
33 | =over 4 | |
34 | ||
35 | =item SSL_MODE_ENABLE_PARTIAL_WRITE | |
36 | ||
37 | Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success | |
38 | when just a single record has been written). When not set (the default), | |
39 | SSL_write() will only report success once the complete chunk was written. | |
a1a63a42 LJ |
40 | Once SSL_write() returns with r, r bytes have been successfully written |
41 | and the next call to SSL_write() must only send the n-r bytes left, | |
42 | imitating the behaviour of write(). | |
f282ca74 LJ |
43 | |
44 | =item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER | |
45 | ||
46 | Make it possible to retry SSL_write() with changed buffer location | |
47 | (the buffer contents must stay the same). This is not the default to avoid | |
48 | the misconception that non-blocking SSL_write() behaves like | |
49 | non-blocking write(). | |
50 | ||
51 | =item SSL_MODE_AUTO_RETRY | |
52 | ||
53 | Never bother the application with retries if the transport is blocking. | |
54 | If a renegotiation take place during normal operation, a | |
9b86974e | 55 | L<SSL_read(3)> or L<SSL_write(3)> would return |
f282ca74 LJ |
56 | with -1 and indicate the need to retry with SSL_ERROR_WANT_READ. |
57 | In a non-blocking environment applications must be prepared to handle | |
58 | incomplete read/write operations. | |
59 | In a blocking environment, applications are not always prepared to | |
60 | deal with read/write operations returning without success report. The | |
61 | flag SSL_MODE_AUTO_RETRY will cause read/write operations to only | |
62 | return after the handshake and successful completion. | |
63 | ||
8671b898 BL |
64 | =item SSL_MODE_RELEASE_BUFFERS |
65 | ||
66 | When we no longer need a read buffer or a write buffer for a given SSL, | |
63c574f6 RS |
67 | then release the memory we were using to hold it. |
68 | Using this flag can | |
8671b898 BL |
69 | save around 34k per idle SSL connection. |
70 | This flag has no effect on SSL v2 connections, or on DTLS connections. | |
71 | ||
98f1ac7d | 72 | =item SSL_MODE_SEND_FALLBACK_SCSV |
fb0e87fb BM |
73 | |
74 | Send TLS_FALLBACK_SCSV in the ClientHello. | |
98f1ac7d | 75 | To be set only by applications that reconnect with a downgraded protocol |
fb0e87fb BM |
76 | version; see draft-ietf-tls-downgrade-scsv-00 for details. |
77 | ||
98f1ac7d BM |
78 | DO NOT ENABLE THIS if your application attempts a normal handshake. |
79 | Only use this in explicit fallback retries, following the guidance | |
80 | in draft-ietf-tls-downgrade-scsv-00. | |
81 | ||
f282ca74 LJ |
82 | =back |
83 | ||
84 | =head1 RETURN VALUES | |
85 | ||
86 | SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask | |
87 | after adding B<mode>. | |
88 | ||
89 | SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. | |
90 | ||
91 | =head1 SEE ALSO | |
92 | ||
9b86974e | 93 | L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)> |
f282ca74 | 94 | |
f282ca74 | 95 | =cut |