]>
Commit | Line | Data |
---|---|---|
32751b8a DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, | |
6 | BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, | |
7 | BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, | |
8 | BIO_ssl_shutdown - SSL BIO | |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/bio.h> | |
13 | #include <openssl/ssl.h> | |
14 | ||
15 | BIO_METHOD *BIO_f_ssl(void); | |
16 | ||
17 | #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) | |
18 | #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) | |
19 | #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) | |
20 | #define BIO_set_ssl_renegotiate_bytes(b,num) \ | |
21 | BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); | |
22 | #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ | |
23 | BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); | |
24 | #define BIO_get_num_renegotiates(b) \ | |
25 | BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); | |
26 | ||
27 | BIO *BIO_new_ssl(SSL_CTX *ctx,int client); | |
28 | BIO *BIO_new_ssl_connect(SSL_CTX *ctx); | |
29 | BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); | |
30 | int BIO_ssl_copy_session_id(BIO *to,BIO *from); | |
31 | void BIO_ssl_shutdown(BIO *bio); | |
32 | ||
33 | =head1 DESCRIPTION | |
34 | ||
35 | BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which | |
36 | is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to | |
37 | SSL I/O. | |
38 | ||
39 | I/O performed on an SSL BIO communicates using the SSL protocol with | |
40 | the SSLs read and write BIOs. | |
41 | ||
42 | If a BIO is appended to an SSL BIO using BIO_push() it is automatically | |
43 | used as the SSL BIOs read and write BIOs. | |
44 | ||
45 | Calling BIO_reset() on an SSL BIO closes down any current SSL connection | |
46 | by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in | |
47 | the chain: this will typically disconnect the underlying transport. | |
48 | The SSL BIO is then reset to the initial accept or connect state. | |
49 | ||
50 | If the close flag is set when an SSL BIO is freed then the internal | |
51 | SSL structure is also freed using SSL_free(). | |
52 | ||
53 | BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using | |
54 | the close flag B<c>. | |
55 | ||
56 | BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be | |
57 | manipulated using the standard SSL library functions. | |
58 | ||
59 | BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> | |
60 | is 1 client mode is set. If B<client> is 0 server mode is set. | |
61 | ||
62 | BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count | |
63 | to B<num>. When set after every B<num> bytes of I/O (read and write) | |
64 | the SSL session is automatically renegotiated. B<num> must be at | |
65 | least 512 bytes. | |
66 | ||
67 | BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to | |
68 | B<seconds>. When the renegotiate timeout elapses the sesssion is | |
69 | automatically renegotiated. | |
70 | ||
71 | BIO_get_num_renegotiates() returns the total number of session | |
72 | renegotiations due to I/O or timeout. | |
73 | ||
74 | BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using | |
75 | client mode if B<client> is non zero. | |
76 | ||
77 | BIO_new_ssl_connect() creates a new BIO chain consisting of an | |
78 | SSL BIO (using B<ctx>) followed by a connect BIO. | |
79 | ||
80 | BIO_new_buffer_ssl_connect() creates a new BIO chain consisting | |
81 | of a buffering BIO, an SSL BIO (using B<ctx>) and a connect | |
82 | BIO. | |
83 | ||
84 | BIO_ssl_copy_session_id() copies an SSL session id between | |
85 | BIO chains B<from> and B<to>. It does this by locating the | |
86 | SSL BIOs in each chain and calling SSL_copy_session_id() on | |
87 | the internal SSL pointer. | |
88 | ||
89 | BIO_ssl_shutdown() closes down an SSL connection on BIO | |
90 | chain B<bio>. It does this by locating the SSL BIO in the | |
91 | chain and calling SSL_shutdown() on its internal SSL | |
92 | pointer. | |
93 | ||
94 | =head1 NOTES | |
95 | ||
96 | SSL BIOs are exceptional in that if the underlying transport | |
97 | is non blocking they can still request a retry in exceptional | |
98 | circumstances. Specifically this will happen if a session | |
99 | renegotiation takes place during a BIO_read() operation, one | |
100 | case where this happens is when SGC or step up occurs. | |
101 | ||
102 | In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be | |
103 | set to disable this behaviour. That is when this flag is set | |
104 | an SSL BIO using a blocking transport will never request a | |
105 | retry. | |
106 | ||
107 | Since unknown BIO_ctrl() operations are sent through filter | |
108 | BIOs the servers name and port can be set using BIO_set_host() | |
109 | on the BIO returned by BIO_new_ssl_connect() without having | |
110 | to locate the connect BIO first. | |
111 | ||
112 | =head1 RETURN VALUES | |
113 | ||
114 | TBA | |
115 | ||
116 | =head1 EXAMPLE | |
117 | ||
118 | This SSL/TLS client example, attempts to retrieve a page from an | |
119 | SSL/TLS web server. The I/O routines are identical to those of the | |
120 | unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. | |
121 | ||
122 | BIO *sbio, *out; | |
123 | int len; | |
124 | char tmpbuf[1024]; | |
125 | SSL_CTX *ctx; | |
126 | SSL *ssl; | |
127 | ||
128 | ERR_load_crypto_strings(); | |
129 | ERR_load_SSL_strings(); | |
130 | OpenSSL_add_all_algorithms(); | |
131 | ||
132 | ctx = SSL_CTX_new(SSLv23_client_method()); | |
133 | ||
134 | /* We'd normally set some stuff like the verify paths and | |
135 | * mode here because as things stand this will connect to | |
136 | * any server whose certificate is signed by any CA. | |
137 | */ | |
138 | ||
139 | sbio = BIO_new_ssl_connect(ctx); | |
140 | ||
141 | BIO_get_ssl(sbio, &ssl); | |
142 | ||
143 | if(!ssl) { | |
144 | fprintf(stderr, "Can't locate SSL pointer\n"); | |
145 | /* whatever ... */ | |
146 | } | |
147 | ||
148 | /* Don't want any retries */ | |
149 | SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); | |
150 | ||
151 | /* We might want to do other things with ssl here */ | |
152 | ||
153 | BIO_set_conn_hostname(sbio, "localhost:https"); | |
154 | ||
155 | out = BIO_new_fp(stdout, BIO_NOCLOSE); | |
156 | if(BIO_do_connect(sbio) <= 0) { | |
157 | fprintf(stderr, "Error connecting to server\n"); | |
158 | ERR_print_errors_fp(stderr); | |
159 | /* whatever ... */ | |
160 | } | |
161 | ||
162 | /* Could examine ssl here to get connection info */ | |
163 | ||
164 | BIO_puts(sbio, "GET / HTTP/1.0\n\n"); | |
165 | for(;;) { | |
166 | len = BIO_read(sbio, tmpbuf, 1024); | |
167 | if(len <= 0) break; | |
168 | BIO_write(out, tmpbuf, len); | |
169 | } | |
170 | BIO_free_all(sbio); | |
171 | BIO_free(out); | |
172 | ||
173 | =head1 SEE ALSO | |
174 | ||
175 | TBA |