600 lines
27 KiB
Plaintext
600 lines
27 KiB
Plaintext
|
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.de Vb \" Begin verbatim text
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
.ne \\$1
|
||
|
|
..
|
||
|
|
.de Ve \" End verbatim text
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
..
|
||
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
||
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
|
|
.\" nothing in troff, for use with C<>.
|
||
|
|
.tr \(*W-
|
||
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
|
|
.ie n \{\
|
||
|
|
. ds -- \(*W-
|
||
|
|
. ds PI pi
|
||
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
|
|
. ds L" ""
|
||
|
|
. ds R" ""
|
||
|
|
. ds C` ""
|
||
|
|
. ds C' ""
|
||
|
|
'br\}
|
||
|
|
.el\{\
|
||
|
|
. ds -- \|\(em\|
|
||
|
|
. ds PI \(*p
|
||
|
|
. ds L" ``
|
||
|
|
. ds R" ''
|
||
|
|
. ds C`
|
||
|
|
. ds C'
|
||
|
|
'br\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.\"
|
||
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
||
|
|
.de IX
|
||
|
|
..
|
||
|
|
.nr rF 0
|
||
|
|
.if \n(.g .if rF .nr rF 1
|
||
|
|
.if (\n(rF:(\n(.g==0)) \{
|
||
|
|
. if \nF \{
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. if !\nF==2 \{
|
||
|
|
. nr % 0
|
||
|
|
. nr F 2
|
||
|
|
. \}
|
||
|
|
. \}
|
||
|
|
.\}
|
||
|
|
.rr rF
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" fudge factors for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds #H 0
|
||
|
|
. ds #V .8m
|
||
|
|
. ds #F .3m
|
||
|
|
. ds #[ \f1
|
||
|
|
. ds #] \fP
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||
|
|
. ds #V .6m
|
||
|
|
. ds #F 0
|
||
|
|
. ds #[ \&
|
||
|
|
. ds #] \&
|
||
|
|
.\}
|
||
|
|
. \" simple accents for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds ' \&
|
||
|
|
. ds ` \&
|
||
|
|
. ds ^ \&
|
||
|
|
. ds , \&
|
||
|
|
. ds ~ ~
|
||
|
|
. ds /
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||
|
|
.\}
|
||
|
|
. \" troff and (daisy-wheel) nroff accents
|
||
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
||
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||
|
|
. \" corrections for vroff
|
||
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||
|
|
. \" for low resolution devices (crt and lpr)
|
||
|
|
.if \n(.H>23 .if \n(.V>19 \
|
||
|
|
\{\
|
||
|
|
. ds : e
|
||
|
|
. ds 8 ss
|
||
|
|
. ds o a
|
||
|
|
. ds d- d\h'-1'\(ga
|
||
|
|
. ds D- D\h'-1'\(hy
|
||
|
|
. ds th \o'bp'
|
||
|
|
. ds Th \o'LP'
|
||
|
|
. ds ae ae
|
||
|
|
. ds Ae AE
|
||
|
|
.\}
|
||
|
|
.rm #[ #] #H #V #F C
|
||
|
|
.\" ========================================================================
|
||
|
|
.\"
|
||
|
|
.IX Title "OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7ossl"
|
||
|
|
.TH OSSL-GUIDE-QUIC-CLIENT-NON-BLOCK 7ossl "2024-01-30" "3.2.1" "OpenSSL"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.SH "NAME"
|
||
|
|
ossl\-guide\-quic\-client\-non\-block
|
||
|
|
\&\- OpenSSL Guide: Writing a simple nonblocking QUIC client
|
||
|
|
.SH "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE"
|
||
|
|
.IX Header "SIMPLE NONBLOCKING QUIC CLIENT EXAMPLE"
|
||
|
|
This page will build on the example developed on the
|
||
|
|
\&\fIossl\-guide\-quic\-client\-block\fR\|(7) page which demonstrates how to write a simple
|
||
|
|
blocking \s-1QUIC\s0 client. On this page we will amend that demo code so that it
|
||
|
|
supports nonblocking functionality.
|
||
|
|
.PP
|
||
|
|
The complete source code for this example nonblocking \s-1QUIC\s0 client is available
|
||
|
|
in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file
|
||
|
|
\&\fBquic\-client\-non\-block.c\fR. It is also available online at
|
||
|
|
<https://github.com/openssl/openssl/blob/master/demos/guide/quic\-client\-non\-block.c>.
|
||
|
|
.PP
|
||
|
|
As we saw in the previous example an OpenSSL \s-1QUIC\s0 application always uses a
|
||
|
|
nonblocking socket. However, despite this, the \fB\s-1SSL\s0\fR object still has blocking
|
||
|
|
behaviour. When the \fB\s-1SSL\s0\fR object has blocking behaviour then this means that
|
||
|
|
it waits (blocks) until data is available to read if you attempt to read from
|
||
|
|
it when there is no data yet. Similarly it waits when writing if the \fB\s-1SSL\s0\fR
|
||
|
|
object is currently unable to write at the moment. This can simplify the
|
||
|
|
development of code because you do not have to worry about what to do in these
|
||
|
|
cases. The execution of the code will simply stop until it is able to continue.
|
||
|
|
However in many cases you do not want this behaviour. Rather than stopping and
|
||
|
|
waiting your application may need to go and do other tasks whilst the \fB\s-1SSL\s0\fR
|
||
|
|
object is unable to read/write, for example updating a \s-1GUI\s0 or performing
|
||
|
|
operations on some other connection or stream.
|
||
|
|
.PP
|
||
|
|
We will see later in this tutorial how to change the \fB\s-1SSL\s0\fR object so that it
|
||
|
|
has nonblocking behaviour. With a nonblocking \fB\s-1SSL\s0\fR object, functions such as
|
||
|
|
\&\fISSL_read_ex\fR\|(3) or \fISSL_write_ex\fR\|(3) will return immediately with a non-fatal
|
||
|
|
error if they are currently unable to read or write respectively.
|
||
|
|
.PP
|
||
|
|
Since this page is building on the example developed on the
|
||
|
|
\&\fIossl\-guide\-quic\-client\-block\fR\|(7) page we assume that you are familiar with it
|
||
|
|
and we only explain how this example differs.
|
||
|
|
.SS "Performing work while waiting for the socket"
|
||
|
|
.IX Subsection "Performing work while waiting for the socket"
|
||
|
|
In a nonblocking application you will need work to perform in the event that
|
||
|
|
we want to read or write to the \fB\s-1SSL\s0\fR object but we are currently unable to.
|
||
|
|
In fact this is the whole point of using a nonblocking \fB\s-1SSL\s0\fR object, i.e. to
|
||
|
|
give the application the opportunity to do something else. Whatever it is that
|
||
|
|
the application has to do, it must also be prepared to come back and retry the
|
||
|
|
operation that it previously attempted periodically to see if it can now
|
||
|
|
complete. Ideally it would only do this in the event that something has changed
|
||
|
|
such that it might succeed on the retry attempt, but this does not have to be
|
||
|
|
the case. It can retry at any time.
|
||
|
|
.PP
|
||
|
|
Note that it is important that you retry exactly the same operation that you
|
||
|
|
tried last time. You cannot start something new. For example if you were
|
||
|
|
attempting to write the text \*(L"Hello World\*(R" and the operation failed because the
|
||
|
|
\&\fB\s-1SSL\s0\fR object is currently unable to write, then you cannot then attempt to
|
||
|
|
write some other text when you retry the operation.
|
||
|
|
.PP
|
||
|
|
In this demo application we will create a helper function which simulates doing
|
||
|
|
other work. In fact, for the sake of simplicity, it will do nothing except wait
|
||
|
|
for the state of the underlying socket to change or until a timeout expires
|
||
|
|
after which the state of the \fB\s-1SSL\s0\fR object might have changed. We will call our
|
||
|
|
function \f(CW\*(C`wait_for_activity()\*(C'\fR.
|
||
|
|
.PP
|
||
|
|
.Vb 6
|
||
|
|
\& static void wait_for_activity(SSL *ssl)
|
||
|
|
\& {
|
||
|
|
\& fd_set wfds, rfds;
|
||
|
|
\& int width, sock, isinfinite;
|
||
|
|
\& struct timeval tv;
|
||
|
|
\& struct timeval *tvp = NULL;
|
||
|
|
\&
|
||
|
|
\& /* Get hold of the underlying file descriptor for the socket */
|
||
|
|
\& sock = SSL_get_fd(ssl);
|
||
|
|
\&
|
||
|
|
\& FD_ZERO(&wfds);
|
||
|
|
\& FD_ZERO(&rfds);
|
||
|
|
\&
|
||
|
|
\& /*
|
||
|
|
\& * Find out if we would like to write to the socket, or read from it (or
|
||
|
|
\& * both)
|
||
|
|
\& */
|
||
|
|
\& if (SSL_net_write_desired(ssl))
|
||
|
|
\& FD_SET(sock, &wfds);
|
||
|
|
\& if (SSL_net_read_desired(ssl))
|
||
|
|
\& FD_SET(sock, &rfds);
|
||
|
|
\& width = sock + 1;
|
||
|
|
\&
|
||
|
|
\& /*
|
||
|
|
\& * Find out when OpenSSL would next like to be called, regardless of
|
||
|
|
\& * whether the state of the underlying socket has changed or not.
|
||
|
|
\& */
|
||
|
|
\& if (SSL_get_event_timeout(ssl, &tv, &isinfinite) && !isinfinite)
|
||
|
|
\& tvp = &tv;
|
||
|
|
\&
|
||
|
|
\& /*
|
||
|
|
\& * Wait until the socket is writeable or readable. We use select here
|
||
|
|
\& * for the sake of simplicity and portability, but you could equally use
|
||
|
|
\& * poll/epoll or similar functions
|
||
|
|
\& *
|
||
|
|
\& * NOTE: For the purposes of this demonstration code this effectively
|
||
|
|
\& * makes this demo block until it has something more useful to do. In a
|
||
|
|
\& * real application you probably want to go and do other work here (e.g.
|
||
|
|
\& * update a GUI, or service other connections).
|
||
|
|
\& *
|
||
|
|
\& * Let\*(Aqs say for example that you want to update the progress counter on
|
||
|
|
\& * a GUI every 100ms. One way to do that would be to use the timeout in
|
||
|
|
\& * the last parameter to "select" below. If the tvp value is greater
|
||
|
|
\& * than 100ms then use 100ms instead. Then, when select returns, you
|
||
|
|
\& * check if it did so because of activity on the file descriptors or
|
||
|
|
\& * because of the timeout. If the 100ms GUI timeout has expired but the
|
||
|
|
\& * tvp timeout has not then go and update the GUI and then restart the
|
||
|
|
\& * "select" (with updated timeouts).
|
||
|
|
\& */
|
||
|
|
\&
|
||
|
|
\& select(width, &rfds, &wfds, NULL, tvp);
|
||
|
|
\&}
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
If you are familiar with how to write nonblocking applications in OpenSSL for
|
||
|
|
\&\s-1TLS \s0(see \fIossl\-guide\-tls\-client\-non\-block\fR\|(7)) then you should note that there
|
||
|
|
is an important difference here between the way a \s-1QUIC\s0 application and a \s-1TLS\s0
|
||
|
|
application works. With a \s-1TLS\s0 application if we try to read or write something
|
||
|
|
to the \fB\s-1SSL\s0\fR object and we get a \*(L"retry\*(R" response (\fB\s-1SSL_ERROR_WANT_READ\s0\fR or
|
||
|
|
\&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR) then we can assume that is because OpenSSL attempted to
|
||
|
|
read or write to the underlying socket and the socket signalled the \*(L"retry\*(R".
|
||
|
|
With \s-1QUIC\s0 that is not the case. OpenSSL may signal retry as a result of an
|
||
|
|
\&\fISSL_read_ex\fR\|(3) or \fISSL_write_ex\fR\|(3) (or similar) call which indicates the
|
||
|
|
state of the stream. This is entirely independent of whether the underlying
|
||
|
|
socket needs to retry or not.
|
||
|
|
.PP
|
||
|
|
To determine whether OpenSSL currently wants to read or write to the underlying
|
||
|
|
socket for a \s-1QUIC\s0 application we must call the \fISSL_net_read_desired\fR\|(3) and
|
||
|
|
\&\fISSL_net_write_desired\fR\|(3) functions.
|
||
|
|
.PP
|
||
|
|
It is also important with \s-1QUIC\s0 that we periodically call an I/O function (or
|
||
|
|
otherwise call the \fISSL_handle_events\fR\|(3) function) to ensure that the \s-1QUIC\s0
|
||
|
|
connection remains healthy. This is particularly important with a nonblocking
|
||
|
|
application because you are likely to leave the \fB\s-1SSL\s0\fR object idle for a while
|
||
|
|
while the application goes off to do other work. The \fISSL_get_event_timeout\fR\|(3)
|
||
|
|
function can be used to determine what the deadline is for the next time we need
|
||
|
|
to call an I/O function (or call \fISSL_handle_events\fR\|(3)).
|
||
|
|
.PP
|
||
|
|
An alternative to using \fISSL_get_event_timeout\fR\|(3) to find the next deadline
|
||
|
|
that OpenSSL must be called again by is to use \*(L"thread assisted\*(R" mode. In
|
||
|
|
\&\*(L"thread assisted\*(R" mode OpenSSL spawns an additional thread which will
|
||
|
|
periodically call \fISSL_handle_events\fR\|(3) automatically, meaning that the
|
||
|
|
application can leave the connection idle safe in the knowledge that the
|
||
|
|
connection will still be maintained in a healthy state. See
|
||
|
|
\&\*(L"Creating the \s-1SSL_CTX\s0 and \s-1SSL\s0 objects\*(R" below for further details about this.
|
||
|
|
.PP
|
||
|
|
In this example we are using the \f(CW\*(C`select\*(C'\fR function to check the
|
||
|
|
readability/writeability of the socket because it is very simple to use and is
|
||
|
|
available on most Operating Systems. However you could use any other similar
|
||
|
|
function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of the underlying
|
||
|
|
socket(s) to become readable/writeable or until the timeout has expired before
|
||
|
|
returning.
|
||
|
|
.SS "Handling errors from OpenSSL I/O functions"
|
||
|
|
.IX Subsection "Handling errors from OpenSSL I/O functions"
|
||
|
|
A \s-1QUIC\s0 application that has been configured for nonblocking behaviour will need
|
||
|
|
to be prepared to handle errors returned from OpenSSL I/O functions such as
|
||
|
|
\&\fISSL_read_ex\fR\|(3) or \fISSL_write_ex\fR\|(3). Errors may be fatal for the stream (for
|
||
|
|
example because the stream has been reset or because the underlying connection
|
||
|
|
has failed), or non-fatal (for example because we are trying to read from the
|
||
|
|
stream but no data has not yet arrived from the peer for that stream).
|
||
|
|
.PP
|
||
|
|
\&\fISSL_read_ex\fR\|(3) and \fISSL_write_ex\fR\|(3) will return 0 to indicate an error and
|
||
|
|
\&\fISSL_read\fR\|(3) and \fISSL_write\fR\|(3) will return 0 or a negative value to indicate
|
||
|
|
an error. \fISSL_shutdown\fR\|(3) will return a negative value to incidate an error.
|
||
|
|
.PP
|
||
|
|
In the event of an error an application should call \fISSL_get_error\fR\|(3) to find
|
||
|
|
out what type of error has occurred. If the error is non-fatal and can be
|
||
|
|
retried then \fISSL_get_error\fR\|(3) will return \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
|
||
|
|
\&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR depending on whether OpenSSL wanted to read to or write
|
||
|
|
from the stream but was unable to. Note that a call to \fISSL_read_ex\fR\|(3) or
|
||
|
|
\&\fISSL_read\fR\|(3) can still generate \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. Similarly calls to
|
||
|
|
\&\fISSL_write_ex\fR\|(3) or \fISSL_write\fR\|(3) might generate \fB\s-1SSL_ERROR_WANT_READ\s0\fR.
|
||
|
|
.PP
|
||
|
|
Another type of non-fatal error that may occur is \fB\s-1SSL_ERROR_ZERO_RETURN\s0\fR. This
|
||
|
|
indicates an \s-1EOF \s0(End-Of-File) which can occur if you attempt to read data from
|
||
|
|
an \fB\s-1SSL\s0\fR object but the peer has indicated that it will not send any more data
|
||
|
|
on the stream. In this case you may still want to write data to the stream but
|
||
|
|
you will not receive any more data.
|
||
|
|
.PP
|
||
|
|
Fatal errors that may occur are \fB\s-1SSL_ERROR_SYSCALL\s0\fR and \fB\s-1SSL_ERROR_SSL\s0\fR. These
|
||
|
|
indicate that the stream is no longer usable. For example, this could be because
|
||
|
|
the stream has been reset by the peer, or because the underlying connection has
|
||
|
|
failed. You can consult the OpenSSL error stack for further details (for example
|
||
|
|
by calling \fIERR_print_errors\fR\|(3) to print out details of errors that have
|
||
|
|
occurred). You can also consult the return value of
|
||
|
|
\&\fISSL_get_stream_read_state\fR\|(3) to determine whether the error is local to the
|
||
|
|
stream, or whether the underlying connection has also failed. A return value
|
||
|
|
of \fB\s-1SSL_STREAM_STATE_RESET_REMOTE\s0\fR tells you that the stream has been reset by
|
||
|
|
the peer and \fB\s-1SSL_STREAM_STATE_CONN_CLOSED\s0\fR tells you that the underlying
|
||
|
|
connection has closed.
|
||
|
|
.PP
|
||
|
|
In our demo application we will write a function to handle these errors from
|
||
|
|
OpenSSL I/O functions:
|
||
|
|
.PP
|
||
|
|
.Vb 8
|
||
|
|
\& static int handle_io_failure(SSL *ssl, int res)
|
||
|
|
\& {
|
||
|
|
\& switch (SSL_get_error(ssl, res)) {
|
||
|
|
\& case SSL_ERROR_WANT_READ:
|
||
|
|
\& case SSL_ERROR_WANT_WRITE:
|
||
|
|
\& /* Temporary failure. Wait until we can read/write and try again */
|
||
|
|
\& wait_for_activity(ssl);
|
||
|
|
\& return 1;
|
||
|
|
\&
|
||
|
|
\& case SSL_ERROR_ZERO_RETURN:
|
||
|
|
\& /* EOF */
|
||
|
|
\& return 0;
|
||
|
|
\&
|
||
|
|
\& case SSL_ERROR_SYSCALL:
|
||
|
|
\& return \-1;
|
||
|
|
\&
|
||
|
|
\& case SSL_ERROR_SSL:
|
||
|
|
\& /*
|
||
|
|
\& * Some stream fatal error occurred. This could be because of a
|
||
|
|
\& * stream reset \- or some failure occurred on the underlying
|
||
|
|
\& * connection.
|
||
|
|
\& */
|
||
|
|
\& switch (SSL_get_stream_read_state(ssl)) {
|
||
|
|
\& case SSL_STREAM_STATE_RESET_REMOTE:
|
||
|
|
\& printf("Stream reset occurred\en");
|
||
|
|
\& /*
|
||
|
|
\& * The stream has been reset but the connection is still
|
||
|
|
\& * healthy.
|
||
|
|
\& */
|
||
|
|
\& break;
|
||
|
|
\&
|
||
|
|
\& case SSL_STREAM_STATE_CONN_CLOSED:
|
||
|
|
\& printf("Connection closed\en");
|
||
|
|
\& /* Connection is already closed. */
|
||
|
|
\& break;
|
||
|
|
\&
|
||
|
|
\& default:
|
||
|
|
\& printf("Unknown stream failure\en");
|
||
|
|
\& break;
|
||
|
|
\& }
|
||
|
|
\& /*
|
||
|
|
\& * If the failure is due to a verification error we can get more
|
||
|
|
\& * information about it from SSL_get_verify_result().
|
||
|
|
\& */
|
||
|
|
\& if (SSL_get_verify_result(ssl) != X509_V_OK)
|
||
|
|
\& printf("Verify error: %s\en",
|
||
|
|
\& X509_verify_cert_error_string(SSL_get_verify_result(ssl)));
|
||
|
|
\& return \-1;
|
||
|
|
\&
|
||
|
|
\& default:
|
||
|
|
\& return \-1;
|
||
|
|
\& }
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
This function takes as arguments the \fB\s-1SSL\s0\fR object that represents the
|
||
|
|
connection, as well as the return code from the I/O function that failed. In
|
||
|
|
the event of a non-fatal failure, it waits until a retry of the I/O operation
|
||
|
|
might succeed (by using the \f(CW\*(C`wait_for_activity()\*(C'\fR function that we developed
|
||
|
|
in the previous section). It returns 1 in the event of a non-fatal error
|
||
|
|
(except \s-1EOF\s0), 0 in the event of \s-1EOF,\s0 or \-1 if a fatal error occurred.
|
||
|
|
.SS "Creating the \s-1SSL_CTX\s0 and \s-1SSL\s0 objects"
|
||
|
|
.IX Subsection "Creating the SSL_CTX and SSL objects"
|
||
|
|
In order to connect to a server we must create \fB\s-1SSL_CTX\s0\fR and \fB\s-1SSL\s0\fR objects for
|
||
|
|
this. Most of the steps to do this are the same as for a blocking client and are
|
||
|
|
explained on the \fIossl\-guide\-quic\-client\-block\fR\|(7) page. We won't repeat that
|
||
|
|
information here.
|
||
|
|
.PP
|
||
|
|
One key difference is that we must put the \fB\s-1SSL\s0\fR object into nonblocking mode
|
||
|
|
(the default is blocking mode). To do that we use the
|
||
|
|
\&\fISSL_set_blocking_mode\fR\|(3) function:
|
||
|
|
.PP
|
||
|
|
.Vb 9
|
||
|
|
\& /*
|
||
|
|
\& * The underlying socket is always nonblocking with QUIC, but the default
|
||
|
|
\& * behaviour of the SSL object is still to block. We set it for nonblocking
|
||
|
|
\& * mode in this demo.
|
||
|
|
\& */
|
||
|
|
\& if (!SSL_set_blocking_mode(ssl, 0)) {
|
||
|
|
\& printf("Failed to turn off blocking mode\en");
|
||
|
|
\& goto end;
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
Although the demo application that we are developing here does not use it, it is
|
||
|
|
possible to use \*(L"thread assisted mode\*(R" when developing \s-1QUIC\s0 applications.
|
||
|
|
Normally, when writing an OpenSSL \s-1QUIC\s0 application, it is important that
|
||
|
|
\&\fISSL_handle_events\fR\|(3) (or alternatively any I/O function) is called on the
|
||
|
|
connection \fB\s-1SSL\s0\fR object periodically to maintain the connection in a healthy
|
||
|
|
state. See \*(L"Performing work while waiting for the socket\*(R" for more discussion
|
||
|
|
on this. This is particularly important to keep in mind when writing a
|
||
|
|
nonblocking \s-1QUIC\s0 application because it is common to leave the \fB\s-1SSL\s0\fR connection
|
||
|
|
object idle for some time when using nonblocking mode. By using \*(L"thread assisted
|
||
|
|
mode\*(R" a separate thread is created by OpenSSL to do this automatically which
|
||
|
|
means that the application developer does not need to handle this aspect. To do
|
||
|
|
this we must use \fIOSSL_QUIC_client_thread_method\fR\|(3) when we construct the
|
||
|
|
\&\fB\s-1SSL_CTX\s0\fR as shown below:
|
||
|
|
.PP
|
||
|
|
.Vb 5
|
||
|
|
\& ctx = SSL_CTX_new(OSSL_QUIC_client_thread_method());
|
||
|
|
\& if (ctx == NULL) {
|
||
|
|
\& printf("Failed to create the SSL_CTX\en");
|
||
|
|
\& goto end;
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.SS "Performing the handshake"
|
||
|
|
.IX Subsection "Performing the handshake"
|
||
|
|
As in the demo for a blocking \s-1QUIC\s0 client we use the \fISSL_connect\fR\|(3) function
|
||
|
|
to perform the handshake with the server. Since we are using a nonblocking
|
||
|
|
\&\fB\s-1SSL\s0\fR object it is very likely that calls to this function will fail with a
|
||
|
|
non-fatal error while we are waiting for the server to respond to our handshake
|
||
|
|
messages. In such a case we must retry the same \fISSL_connect\fR\|(3) call at a
|
||
|
|
later time. In this demo we do this in a loop:
|
||
|
|
.PP
|
||
|
|
.Vb 7
|
||
|
|
\& /* Do the handshake with the server */
|
||
|
|
\& while ((ret = SSL_connect(ssl)) != 1) {
|
||
|
|
\& if (handle_io_failure(ssl, ret) == 1)
|
||
|
|
\& continue; /* Retry */
|
||
|
|
\& printf("Failed to connect to server\en");
|
||
|
|
\& goto end; /* Cannot retry: error */
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
We continually call \fISSL_connect\fR\|(3) until it gives us a success response.
|
||
|
|
Otherwise we use the \f(CW\*(C`handle_io_failure()\*(C'\fR function that we created earlier to
|
||
|
|
work out what we should do next. Note that we do not expect an \s-1EOF\s0 to occur at
|
||
|
|
this stage, so such a response is treated in the same way as a fatal error.
|
||
|
|
.SS "Sending and receiving data"
|
||
|
|
.IX Subsection "Sending and receiving data"
|
||
|
|
As with the blocking \s-1QUIC\s0 client demo we use the \fISSL_write_ex\fR\|(3) function to
|
||
|
|
send data to the server. As with \fISSL_connect\fR\|(3) above, because we are using
|
||
|
|
a nonblocking \fB\s-1SSL\s0\fR object, this call could fail with a non-fatal error. In
|
||
|
|
that case we should retry exactly the same \fISSL_write_ex\fR\|(3) call again. Note
|
||
|
|
that the parameters must be \fIexactly\fR the same, i.e. the same pointer to the
|
||
|
|
buffer to write with the same length. You must not attempt to send different
|
||
|
|
data on a retry. An optional mode does exist
|
||
|
|
(\fB\s-1SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\s0\fR) which will configure OpenSSL to allow
|
||
|
|
the buffer being written to change from one retry to the next. However, in this
|
||
|
|
case, you must still retry exactly the same data \- even though the buffer that
|
||
|
|
contains that data may change location. See \fISSL_CTX_set_mode\fR\|(3) for further
|
||
|
|
details. As in the \s-1TLS\s0 tutorials (\fIossl\-guide\-tls\-client\-block\fR\|(7)) we write
|
||
|
|
the request in three chunks.
|
||
|
|
.PP
|
||
|
|
.Vb 10
|
||
|
|
\& /* Write an HTTP GET request to the peer */
|
||
|
|
\& while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) {
|
||
|
|
\& if (handle_io_failure(ssl, 0) == 1)
|
||
|
|
\& continue; /* Retry */
|
||
|
|
\& printf("Failed to write start of HTTP request\en");
|
||
|
|
\& goto end; /* Cannot retry: error */
|
||
|
|
\& }
|
||
|
|
\& while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) {
|
||
|
|
\& if (handle_io_failure(ssl, 0) == 1)
|
||
|
|
\& continue; /* Retry */
|
||
|
|
\& printf("Failed to write hostname in HTTP request\en");
|
||
|
|
\& goto end; /* Cannot retry: error */
|
||
|
|
\& }
|
||
|
|
\& while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) {
|
||
|
|
\& if (handle_io_failure(ssl, 0) == 1)
|
||
|
|
\& continue; /* Retry */
|
||
|
|
\& printf("Failed to write end of HTTP request\en");
|
||
|
|
\& goto end; /* Cannot retry: error */
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
On a write we do not expect to see an \s-1EOF\s0 response so we treat that case in the
|
||
|
|
same way as a fatal error.
|
||
|
|
.PP
|
||
|
|
Reading a response back from the server is similar:
|
||
|
|
.PP
|
||
|
|
.Vb 10
|
||
|
|
\& do {
|
||
|
|
\& /*
|
||
|
|
\& * Get up to sizeof(buf) bytes of the response. We keep reading until
|
||
|
|
\& * the server closes the connection.
|
||
|
|
\& */
|
||
|
|
\& while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) {
|
||
|
|
\& switch (handle_io_failure(ssl, 0)) {
|
||
|
|
\& case 1:
|
||
|
|
\& continue; /* Retry */
|
||
|
|
\& case 0:
|
||
|
|
\& eof = 1;
|
||
|
|
\& continue;
|
||
|
|
\& case \-1:
|
||
|
|
\& default:
|
||
|
|
\& printf("Failed reading remaining data\en");
|
||
|
|
\& goto end; /* Cannot retry: error */
|
||
|
|
\& }
|
||
|
|
\& }
|
||
|
|
\& /*
|
||
|
|
\& * OpenSSL does not guarantee that the returned data is a string or
|
||
|
|
\& * that it is NUL terminated so we use fwrite() to write the exact
|
||
|
|
\& * number of bytes that we read. The data could be non\-printable or
|
||
|
|
\& * have NUL characters in the middle of it. For this simple example
|
||
|
|
\& * we\*(Aqre going to print it to stdout anyway.
|
||
|
|
\& */
|
||
|
|
\& if (!eof)
|
||
|
|
\& fwrite(buf, 1, readbytes, stdout);
|
||
|
|
\& } while (!eof);
|
||
|
|
\& /* In case the response didn\*(Aqt finish with a newline we add one now */
|
||
|
|
\& printf("\en");
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
The main difference this time is that it is valid for us to receive an \s-1EOF\s0
|
||
|
|
response when trying to read data from the server. This will occur when the
|
||
|
|
server closes down the connection after sending all the data in its response.
|
||
|
|
.PP
|
||
|
|
In this demo we just print out all the data we've received back in the response
|
||
|
|
from the server. We continue going around the loop until we either encounter a
|
||
|
|
fatal error, or we receive an \s-1EOF \s0(indicating a graceful finish).
|
||
|
|
.SS "Shutting down the connection"
|
||
|
|
.IX Subsection "Shutting down the connection"
|
||
|
|
As in the \s-1QUIC\s0 blocking example we must shutdown the connection when we are
|
||
|
|
finished with it.
|
||
|
|
.PP
|
||
|
|
Even though we have received \s-1EOF\s0 on the stream that we were reading from above,
|
||
|
|
this tell us nothing about the state of the underlying connection. Our demo
|
||
|
|
application will initiate the connection shutdown process via
|
||
|
|
\&\fISSL_shutdown\fR\|(3).
|
||
|
|
.PP
|
||
|
|
Since our application is initiating the shutdown then we might expect to see
|
||
|
|
\&\fISSL_shutdown\fR\|(3) give a return value of 0, and then we should continue to call
|
||
|
|
it until we receive a return value of 1 (meaning we have successfully completed
|
||
|
|
the shutdown). Since we are using a nonblocking \fB\s-1SSL\s0\fR object we might expect to
|
||
|
|
have to retry this operation several times. If \fISSL_shutdown\fR\|(3) returns a
|
||
|
|
negative result then we must call \fISSL_get_error\fR\|(3) to work out what to do
|
||
|
|
next. We use our \fIhandle_io_failure()\fR function that we developed earlier for
|
||
|
|
this:
|
||
|
|
.PP
|
||
|
|
.Vb 8
|
||
|
|
\& /*
|
||
|
|
\& * Repeatedly call SSL_shutdown() until the connection is fully
|
||
|
|
\& * closed.
|
||
|
|
\& */
|
||
|
|
\& while ((ret = SSL_shutdown(ssl)) != 1) {
|
||
|
|
\& if (ret < 0 && handle_io_failure(ssl, ret) == 1)
|
||
|
|
\& continue; /* Retry */
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.SS "Final clean up"
|
||
|
|
.IX Subsection "Final clean up"
|
||
|
|
As with the blocking \s-1QUIC\s0 client example, once our connection is finished with
|
||
|
|
we must free it. The steps to do this for this example are the same as for the
|
||
|
|
blocking example, so we won't repeat it here.
|
||
|
|
.SH "FURTHER READING"
|
||
|
|
.IX Header "FURTHER READING"
|
||
|
|
See \fIossl\-guide\-quic\-client\-block\fR\|(7) to read a tutorial on how to write a
|
||
|
|
blocking \s-1QUIC\s0 client. See \fIossl\-guide\-quic\-multi\-stream\fR\|(7) to see how to write
|
||
|
|
a multi-stream \s-1QUIC\s0 client.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fIossl\-guide\-introduction\fR\|(7), \fIossl\-guide\-libraries\-introduction\fR\|(7),
|
||
|
|
\&\fIossl\-guide\-libssl\-introduction\fR\|(7), \fIossl\-guide\-quic\-introduction\fR\|(7),
|
||
|
|
\&\fIossl\-guide\-quic\-client\-block\fR\|(7), \fIossl\-guide\-quic\-multi\-stream\fR\|(7)
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
.PP
|
||
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
||
|
|
<https://www.openssl.org/source/license.html>.
|