Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-quic-server-block.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL-GUIDE-QUIC-SERVER-BLOCK 7SSL"
58 .TH OSSL-GUIDE-QUIC-SERVER-BLOCK 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ossl\-guide\-quic\-server\-block
65 \&\- OpenSSL Guide: Writing a simple blocking QUIC server
66 .SH "SIMPLE BLOCKING QUIC SERVER EXAMPLE"
67 .IX Header "SIMPLE BLOCKING QUIC SERVER EXAMPLE"
68 This page will present various source code samples demonstrating how to write a
69 simple, non-concurrent, QUIC "echo" server application which accepts one client
70 connection at a time, echoing input from the client back to the same client.
71 Once the current client disconnects, the next client connection is accepted.
72 .PP
73 The server only accepts HTTP/1.0 requests, which is non-standard and will not
74 be supported by real world servers. This is for demonstration purposes only.
75 .PP
76 Both the accepting socket and client connections are "blocking". A more typical
77 server might use nonblocking sockets with an event loop and callbacks for I/O
78 events.
79 .PP
80 The complete source code for this example blocking QUIC server is available in
81 the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file
82 \&\fBquic\-server\-block.c\fR. It is also available online at
83 <https://github.com/openssl/openssl/blob/master/demos/guide/quic\-server\-block.c>.
84 .PP
85 We assume that you already have OpenSSL installed on your system; that you
86 already have some fundamental understanding of OpenSSL concepts and QUIC (see
87 \&\fBossl\-guide\-libraries\-introduction\fR\|(7) and \fBossl\-guide\-quic\-introduction\fR\|(7));
88 and that you know how to write and build C code and link it against the
89 libcrypto and libssl libraries that are provided by OpenSSL. It also assumes
90 that you have a basic understanding of UDP/IP and sockets.
91 .SS "Creating the SSL_CTX and SSL objects"
92 .IX Subsection "Creating the SSL_CTX and SSL objects"
93 The first step is to create an \fBSSL_CTX\fR object for our server. We use the
94 \&\fBSSL_CTX_new\fR\|(3) function for this purpose. We pass as an argument the return
95 value of the function \fBOSSL_QUIC_server_method\fR\|(3). You should use this method
96 whenever you are writing a QUIC server.
97 .PP
98 .Vb 8
99 \& /*
100 \& * An SSL_CTX holds shared configuration information for multiple
101 \& * subsequent per\-client SSL connections. We specifically load a QUIC
102 \& * server method here.
103 \& */
104 \& ctx = SSL_CTX_new(OSSL_QUIC_server_method());
105 \& if (ctx == NULL)
106 \& goto err;
107 .Ve
108 .PP
109 Servers need a private key and certificate. Intermediate issuer CA
110 certificates are often required, and both the server (end-entity or EE)
111 certificate and the issuer ("chain") certificates are most easily configured in
112 a single "chain file". Below we load such a chain file (the EE certificate
113 must appear first), and then load the corresponding private key, checking that
114 it matches the server certificate. No checks are performed to check the
115 integrity of the chain (CA signatures or certificate expiration dates, for
116 example), but we do verify the consistency of the private key with the
117 corresponding certificate.
118 .PP
119 .Vb 10
120 \& /*
121 \& * Load the server\*(Aqs certificate *chain* file (PEM format), which includes
122 \& * not only the leaf (end\-entity) server certificate, but also any
123 \& * intermediate issuer\-CA certificates. The leaf certificate must be the
124 \& * first certificate in the file.
125 \& *
126 \& * In advanced use\-cases this can be called multiple times, once per public
127 \& * key algorithm for which the server has a corresponding certificate.
128 \& * However, the corresponding private key (see below) must be loaded first,
129 \& * *before* moving on to the next chain file.
130 \& */
131 \& if (SSL_CTX_use_certificate_chain_file(ctx, cert_path) <= 0) {
132 \& fprintf(stderr, "couldn\*(Aqt load certificate file: %s\en", cert_path);
133 \& goto err;
134 \& }
135 \&
136 \& /*
137 \& * Load the corresponding private key, this also checks that the private
138 \& * key matches the just loaded end\-entity certificate. It does not check
139 \& * whether the certificate chain is valid, the certificates could be
140 \& * expired, or may otherwise fail to form a chain that a client can
141 \& * validate.
142 \& */
143 \& if (SSL_CTX_use_PrivateKey_file(ctx, key_path, SSL_FILETYPE_PEM) <= 0) {
144 \& fprintf(stderr, "couldn\*(Aqt load key file: %s\en", key_path);
145 \& goto err;
146 \& }
147 .Ve
148 .PP
149 Most servers, including this one, do not solicit client certificates. We
150 therefore do not need a "trust store" and allow the handshake to complete even
151 when the client does not present a certificate. Note: Even if a client did
152 present a trusted certificate, for it to be useful, the server application
153 would still need custom code to use the verified identity to grant nondefault
154 access to that particular client. Some servers grant access to all clients
155 with certificates from a private CA, this then requires processing of
156 certificate revocation lists to deauthorise a client. It is often simpler and
157 more secure to instead keep a list of authorised public keys.
158 .PP
159 Though this is the default setting, we explicitly call the
160 \&\fBSSL_CTX_set_verify\fR\|(3) function and pass the \fBSSL_VERIFY_NONE\fR value to it.
161 The final argument to this function is a callback that you can optionally
162 supply to override the default handling for certificate verification. Most
163 applications do not need to do this so this can safely be set to NULL to get
164 the default handling.
165 .PP
166 .Vb 12
167 \& /*
168 \& * Clients rarely employ certificate\-based authentication, and so we don\*(Aqt
169 \& * require "mutual" TLS authentication (indeed there\*(Aqs no way to know
170 \& * whether or how the client authenticated the server, so the term "mutual"
171 \& * is potentially misleading).
172 \& *
173 \& * Since we\*(Aqre not soliciting or processing client certificates, we don\*(Aqt
174 \& * need to configure a trusted\-certificate store, so no call to
175 \& * SSL_CTX_set_default_verify_paths() is needed. The server\*(Aqs own
176 \& * certificate chain is assumed valid.
177 \& */
178 \& SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, NULL);
179 .Ve
180 .PP
181 QUIC also dictates using Application-Layer Protocol Negotiation (ALPN) to select
182 an application protocol. We use \fBSSL_CTX_set_alpn_select_cb\fR\|(3) for this
183 purpose. We can pass a callback which will be called for each connection to
184 select an ALPN the server considers acceptable.
185 .PP
186 .Vb 2
187 \& /* Setup ALPN negotiation callback to decide which ALPN is accepted. */
188 \& SSL_CTX_set_alpn_select_cb(ctx, select_alpn, NULL);
189 .Ve
190 .PP
191 In this case, we only accept "http/1.0" and "hq-interop".
192 .PP
193 .Vb 8
194 \& /*
195 \& * ALPN strings for TLS handshake. Only \*(Aqhttp/1.0\*(Aq and \*(Aqhq\-interop\*(Aq
196 \& * are accepted.
197 \& */
198 \& static const unsigned char alpn_ossltest[] = {
199 \& 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq0\*(Aq,
200 \& 10, \*(Aqh\*(Aq, \*(Aqq\*(Aq, \*(Aq\-\*(Aq, \*(Aqi\*(Aq, \*(Aqn\*(Aq, \*(Aqt\*(Aq, \*(Aqe\*(Aq, \*(Aqr\*(Aq, \*(Aqo\*(Aq, \*(Aqp\*(Aq,
201 \& };
202 \&
203 \& static int select_alpn(SSL *ssl, const unsigned char **out,
204 \& unsigned char *out_len, const unsigned char *in,
205 \& unsigned int in_len, void *arg)
206 \& {
207 \& if (SSL_select_next_proto((unsigned char **)out, out_len, alpn_ossltest,
208 \& sizeof(alpn_ossltest), in,
209 \& in_len) == OPENSSL_NPN_NEGOTIATED)
210 \& return SSL_TLSEXT_ERR_OK;
211 \& return SSL_TLSEXT_ERR_ALERT_FATAL;
212 \& }
213 .Ve
214 .PP
215 That is all the setup that we need to do for the \fBSSL_CTX\fR. Next, we create a
216 UDP socket and bind to it on localhost.
217 .PP
218 .Vb 5
219 \& /* Retrieve the file descriptor for a new UDP socket */
220 \& if ((fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP)) < 0) {
221 \& fprintf(stderr, "cannot create socket");
222 \& goto err;
223 \& }
224 \&
225 \& sa.sin_family = AF_INET;
226 \& sa.sin_port = htons(port);
227 \&
228 \& /* Bind to the new UDP socket on localhost */
229 \& if (bind(fd, (const struct sockaddr *)&sa, sizeof(sa)) < 0) {
230 \& fprintf(stderr, "cannot bind to %u\en", port);
231 \& BIO_closesocket(fd);
232 \& goto err;
233 \& }
234 .Ve
235 .PP
236 To run the QUIC server, we create an \fBSSL_LISTENER\fR to listen for incoming
237 connections. We provide it with the bound UDP port to then explicitly begin
238 listening for new connections.
239 .PP
240 .Vb 8
241 \& /*
242 \& * Create a new QUIC listener. Listeners, and other QUIC objects, default
243 \& * to operating in blocking mode. The configured behaviour is inherited by
244 \& * child objects.
245 \& */
246 \& if ((listener = SSL_new_listener(ctx, 0)) == NULL) {
247 \& goto err;
248 \& }
249 \&
250 \& /* Provide the listener with our UDP socket. */
251 \& if (!SSL_set_fd(listener, fd))
252 \& goto err;
253 \&
254 \& /* Begin listening. */
255 \& if (!SSL_listen(listener))
256 \& goto err;
257 .Ve
258 .SS "Server loop"
259 .IX Subsection "Server loop"
260 The server now enters a "forever" loop, handling one client connection at a
261 time. Before each connection, we clear the OpenSSL error stack so that any
262 error reports are related to just the new connection.
263 .PP
264 .Vb 2
265 \& /* Pristine error stack for each new connection */
266 \& ERR_clear_error();
267 .Ve
268 .PP
269 At this point, the server blocks to accept the next client.
270 \&\fBSSL_accept_connection\fR\|(3) will return an accepted connection within a fresh
271 SSL, in which the handshake will have already occurred.
272 .PP
273 .Vb 6
274 \& /* Block while waiting for a client connection */
275 \& conn = SSL_accept_connection(listener, 0);
276 \& if (conn == NULL) {
277 \& fprintf(stderr, "error while accepting connection\en");
278 \& goto err;
279 \& }
280 .Ve
281 .PP
282 With the handshake complete, the server echoes client input back to the client
283 in a loop.
284 .PP
285 .Vb 8
286 \& while (SSL_read_ex(conn, buf, sizeof(buf), &nread) > 0) {
287 \& if (SSL_write_ex(conn, buf, nread, &nwritten) > 0 &&
288 \& nwritten == nread) {
289 \& continue;
290 \& }
291 \& fprintf(stderr, "Error echoing client input");
292 \& break;
293 \& }
294 .Ve
295 .PP
296 Once the client closes its connection, we signal the end of the stream by using
297 \&\fBSSL_stream_conclude\fR\|(3). This will send a final Finished packet to the
298 client.
299 .PP
300 .Vb 6
301 \& /* Signal the end of the stream. */
302 \& if (SSL_stream_conclude(conn, 0) != 1) {
303 \& fprintf(stderr, "Unable to conclude stream\en");
304 \& SSL_free(conn);
305 \& goto err;
306 \& }
307 .Ve
308 .PP
309 We then shut down the connection with \fBSSL_shutdown_ex\fR\|(3), which may need
310 to be called multiple times to ensure the connection is shutdown completely.
311 .PP
312 .Vb 4
313 \& while (SSL_shutdown_ex(conn, 0, &shutdown_args,
314 \& sizeof(SSL_SHUTDOWN_EX_ARGS)) != 1) {
315 \& fprintf(stderr, "Re\-attempting SSL shutdown\en");
316 \& }
317 .Ve
318 .PP
319 Finally, we free the SSL connection, and the server is now ready to accept the
320 next client connection.
321 .PP
322 .Vb 1
323 \& SSL_free(conn);
324 .Ve
325 .SS "Final clean up"
326 .IX Subsection "Final clean up"
327 If the server somehow manages to break out of the infinite loop and
328 be ready to exit, it would deallocate the constructed \fBSSL\fR.
329 .PP
330 .Vb 1
331 \& SSL_free(listener);
332 .Ve
333 .PP
334 And in the main function, it would deallocate the constructed \fBSSL_CTX\fR.
335 .PP
336 .Vb 4
337 \& SSL_CTX_free(ctx);
338 \& BIO_closesocket(fd);
339 \& res = EXIT_SUCCESS;
340 \& return res;
341 .Ve
342 .SH "SEE ALSO"
343 .IX Header "SEE ALSO"
344 \&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
345 \&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-quic\-introduction\fR\|(7),
346 \&\fBossl\-guide\-quic\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7),
347 \&\fBossl\-guide\-tls\-server\-block\fR\|(7), \fBossl\-guide\-quic\-server\-non\-block\fR\|(7)
348 .SH COPYRIGHT
349 .IX Header "COPYRIGHT"
350 Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
351 .PP
352 Licensed under the Apache License 2.0 (the "License"). You may not use
353 this file except in compliance with the License. You can obtain a copy
354 in the file LICENSE in the source distribution or at
355 <https://www.openssl.org/source/license.html>.