Lines Matching refs:to
5 NB: Changes to the source code samples in this file should also be reflected in
18 L<ossl-guide-quic-client-block(7)> page which demonstrates how to write a simple
30 it waits (blocks) until data is available to read if you attempt to read from
32 object is currently unable to write at the moment. This can simplify the
33 development of code because you do not have to worry about what to do in these
34 cases. The execution of the code will simply stop until it is able to continue.
36 waiting your application may need to go and do other tasks whilst the B<SSL>
37 object is unable to read/write, for example updating a GUI or performing
40 We will see later in this tutorial how to change the B<SSL> object so that it
43 error if they are currently unable to read or write respectively.
51 In a nonblocking application you will need work to perform in the event that
52 we want to read or write to the B<SSL> object but we are currently unable to.
53 In fact this is the whole point of using a nonblocking B<SSL> object, i.e. to
54 give the application the opportunity to do something else. Whatever it is that
55 the application has to do, it must also be prepared to come back and retry the
56 operation that it previously attempted periodically to see if it can now
58 such that it might succeed on the retry attempt, but this does not have to be
63 attempting to write the text "Hello World" and the operation failed because the
64 B<SSL> object is currently unable to write, then you cannot then attempt to
69 for the state of the underlying socket to change or until a timeout expires
87 * Find out if we would like to write to the socket, or read from it (or
97 * Find out when OpenSSL would next like to be called, regardless of
109 * makes this demo block until it has something more useful to do. In a
110 * real application you probably want to go and do other work here (e.g.
113 * Let's say for example that you want to update the progress counter on
114 * a GUI every 100ms. One way to do that would be to use the timeout in
115 * the last parameter to "select" below. If the tvp value is greater
126 If you are familiar with how to write nonblocking applications in OpenSSL for
129 application works. With a TLS application if we try to read or write something
130 to the B<SSL> object and we get a "retry" response (B<SSL_ERROR_WANT_READ> or
131 B<SSL_ERROR_WANT_WRITE>) then we can assume that is because OpenSSL attempted to
132 read or write to the underlying socket and the socket signalled the "retry".
136 socket needs to retry or not.
138 To determine whether OpenSSL currently wants to read or write to the underlying
143 otherwise call the L<SSL_handle_events(3)> function) to ensure that the QUIC
145 application because you are likely to leave the B<SSL> object idle for a while
146 while the application goes off to do other work. The L<SSL_get_event_timeout(3)>
147 function can be used to determine what the deadline is for the next time we need
148 to call an I/O function (or call L<SSL_handle_events(3)>).
150 An alternative to using L<SSL_get_event_timeout(3)> to find the next deadline
151 that OpenSSL must be called again by is to use "thread assisted" mode. In
158 In this example we are using the C<select> function to check the
159 readability/writeability of the socket because it is very simple to use and is
161 function to do the same thing. C<select> waits for the state of the underlying
162 socket(s) to become readable/writeable or until the timeout has expired before
168 to be prepared to handle errors returned from OpenSSL I/O functions such as
171 has failed), or non-fatal (for example because we are trying to read from the
174 L<SSL_read_ex(3)> and L<SSL_write_ex(3)> will return 0 to indicate an error and
175 L<SSL_read(3)> and L<SSL_write(3)> will return 0 or a negative value to indicate
176 an error. L<SSL_shutdown(3)> will return a negative value to incidate an error.
178 In the event of an error an application should call L<SSL_get_error(3)> to find
181 B<SSL_ERROR_WANT_WRITE> depending on whether OpenSSL wanted to read to or write
182 from the stream but was unable to. Note that a call to L<SSL_read_ex(3)> or
183 L<SSL_read(3)> can still generate B<SSL_ERROR_WANT_WRITE>. Similarly calls to
187 indicates an EOF (End-Of-File) which can occur if you attempt to read data from
189 on the stream. In this case you may still want to write data to the stream but
196 by calling L<ERR_print_errors(3)> to print out details of errors that have
198 L<SSL_get_stream_read_state(3)> to determine whether the error is local to the
204 In our demo application we will write a function to handle these errors from
248 * If the failure is due to a verification error we can get more
270 In order to connect to a server we must create B<SSL_CTX> and B<SSL> objects for
271 this. Most of the steps to do this are the same as for a blocking client and are
281 * behaviour of the SSL object is still to block. We set it for nonblocking
285 printf("Failed to turn off blocking mode\n");
290 possible to use "thread assisted mode" when developing QUIC applications.
293 connection B<SSL> object periodically to maintain the connection in a healthy
295 on this. This is particularly important to keep in mind when writing a
296 nonblocking QUIC application because it is common to leave the B<SSL> connection
298 mode" a separate thread is created by OpenSSL to do this automatically which
299 means that the application developer does not need to handle this aspect. To do
305 printf("Failed to create the SSL_CTX\n");
312 to perform the handshake with the server. Since we are using a nonblocking
313 B<SSL> object it is very likely that calls to this function will fail with a
314 non-fatal error while we are waiting for the server to respond to our handshake
322 printf("Failed to connect to server\n");
327 Otherwise we use the C<handle_io_failure()> function that we created earlier to
328 work out what we should do next. Note that we do not expect an EOF to occur at
333 As with the blocking QUIC client demo we use the L<SSL_write_ex(3)> function to
334 send data to the server. As with L<SSL_connect(3)> above, because we are using
337 that the parameters must be I<exactly> the same, i.e. the same pointer to the
338 buffer to write with the same length. You must not attempt to send different
340 (B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER>) which will configure OpenSSL to allow
341 the buffer being written to change from one retry to the next. However, in this
347 /* Write an HTTP GET request to the peer */
351 printf("Failed to write start of HTTP request\n");
357 printf("Failed to write hostname in HTTP request\n");
363 printf("Failed to write end of HTTP request\n");
367 On a write we do not expect to see an EOF response so we treat that case in the
374 * Get up to sizeof(buf) bytes of the response. We keep reading until
392 * that it is NUL terminated so we use fwrite() to write the exact
395 * we're going to print it to stdout anyway.
403 The main difference this time is that it is valid for us to receive an EOF
404 response when trying to read data from the server. This will occur when the
421 Since our application is initiating the shutdown then we might expect to see
422 L<SSL_shutdown(3)> give a return value of 0, and then we should continue to call
424 the shutdown). Since we are using a nonblocking B<SSL> object we might expect to
425 have to retry this operation several times. If L<SSL_shutdown(3)> returns a
426 negative result then we must call L<SSL_get_error(3)> to work out what to do
442 we must free it. The steps to do this for this example are the same as for the
447 See L<ossl-guide-quic-client-block(7)> to read a tutorial on how to write a
448 blocking QUIC client. See L<ossl-guide-quic-multi-stream(7)> to see how to write
