1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=begin comment 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncheryNB: Changes to the source code samples in this file should also be reflected in 6*e7be843bSPierre Proncherydemos/guide/quic-server-block.c 7*e7be843bSPierre Pronchery 8*e7be843bSPierre Pronchery=end comment 9*e7be843bSPierre Pronchery 10*e7be843bSPierre Pronchery=head1 NAME 11*e7be843bSPierre Pronchery 12*e7be843bSPierre Proncheryossl-guide-quic-server-block 13*e7be843bSPierre Pronchery- OpenSSL Guide: Writing a simple blocking QUIC server 14*e7be843bSPierre Pronchery 15*e7be843bSPierre Pronchery=head1 SIMPLE BLOCKING QUIC SERVER EXAMPLE 16*e7be843bSPierre Pronchery 17*e7be843bSPierre ProncheryThis page will present various source code samples demonstrating how to write a 18*e7be843bSPierre Proncherysimple, non-concurrent, QUIC "echo" server application which accepts one client 19*e7be843bSPierre Proncheryconnection at a time, echoing input from the client back to the same client. 20*e7be843bSPierre ProncheryOnce the current client disconnects, the next client connection is accepted. 21*e7be843bSPierre Pronchery 22*e7be843bSPierre ProncheryThe server only accepts HTTP/1.0 requests, which is non-standard and will not 23*e7be843bSPierre Proncherybe supported by real world servers. This is for demonstration purposes only. 24*e7be843bSPierre Pronchery 25*e7be843bSPierre ProncheryBoth the accepting socket and client connections are "blocking". A more typical 26*e7be843bSPierre Proncheryserver might use nonblocking sockets with an event loop and callbacks for I/O 27*e7be843bSPierre Proncheryevents. 28*e7be843bSPierre Pronchery 29*e7be843bSPierre ProncheryThe complete source code for this example blocking QUIC server is available in 30*e7be843bSPierre Proncherythe B<demos/guide> directory of the OpenSSL source distribution in the file 31*e7be843bSPierre ProncheryB<quic-server-block.c>. It is also available online at 32*e7be843bSPierre ProncheryL<https://github.com/openssl/openssl/blob/master/demos/guide/quic-server-block.c>. 33*e7be843bSPierre Pronchery 34*e7be843bSPierre ProncheryWe assume that you already have OpenSSL installed on your system; that you 35*e7be843bSPierre Proncheryalready have some fundamental understanding of OpenSSL concepts and QUIC (see 36*e7be843bSPierre ProncheryL<ossl-guide-libraries-introduction(7)> and L<ossl-guide-quic-introduction(7)>); 37*e7be843bSPierre Proncheryand that you know how to write and build C code and link it against the 38*e7be843bSPierre Proncherylibcrypto and libssl libraries that are provided by OpenSSL. It also assumes 39*e7be843bSPierre Proncherythat you have a basic understanding of UDP/IP and sockets. 40*e7be843bSPierre Pronchery 41*e7be843bSPierre Pronchery=head2 Creating the SSL_CTX and SSL objects 42*e7be843bSPierre Pronchery 43*e7be843bSPierre ProncheryThe first step is to create an B<SSL_CTX> object for our server. We use the 44*e7be843bSPierre ProncheryL<SSL_CTX_new(3)> function for this purpose. We pass as an argument the return 45*e7be843bSPierre Proncheryvalue of the function L<OSSL_QUIC_server_method(3)>. You should use this method 46*e7be843bSPierre Proncherywhenever you are writing a QUIC server. 47*e7be843bSPierre Pronchery 48*e7be843bSPierre Pronchery /* 49*e7be843bSPierre Pronchery * An SSL_CTX holds shared configuration information for multiple 50*e7be843bSPierre Pronchery * subsequent per-client SSL connections. We specifically load a QUIC 51*e7be843bSPierre Pronchery * server method here. 52*e7be843bSPierre Pronchery */ 53*e7be843bSPierre Pronchery ctx = SSL_CTX_new(OSSL_QUIC_server_method()); 54*e7be843bSPierre Pronchery if (ctx == NULL) 55*e7be843bSPierre Pronchery goto err; 56*e7be843bSPierre Pronchery 57*e7be843bSPierre ProncheryServers need a private key and certificate. Intermediate issuer CA 58*e7be843bSPierre Proncherycertificates are often required, and both the server (end-entity or EE) 59*e7be843bSPierre Proncherycertificate and the issuer ("chain") certificates are most easily configured in 60*e7be843bSPierre Proncherya single "chain file". Below we load such a chain file (the EE certificate 61*e7be843bSPierre Proncherymust appear first), and then load the corresponding private key, checking that 62*e7be843bSPierre Proncheryit matches the server certificate. No checks are performed to check the 63*e7be843bSPierre Proncheryintegrity of the chain (CA signatures or certificate expiration dates, for 64*e7be843bSPierre Proncheryexample), but we do verify the consistency of the private key with the 65*e7be843bSPierre Proncherycorresponding certificate. 66*e7be843bSPierre Pronchery 67*e7be843bSPierre Pronchery /* 68*e7be843bSPierre Pronchery * Load the server's certificate *chain* file (PEM format), which includes 69*e7be843bSPierre Pronchery * not only the leaf (end-entity) server certificate, but also any 70*e7be843bSPierre Pronchery * intermediate issuer-CA certificates. The leaf certificate must be the 71*e7be843bSPierre Pronchery * first certificate in the file. 72*e7be843bSPierre Pronchery * 73*e7be843bSPierre Pronchery * In advanced use-cases this can be called multiple times, once per public 74*e7be843bSPierre Pronchery * key algorithm for which the server has a corresponding certificate. 75*e7be843bSPierre Pronchery * However, the corresponding private key (see below) must be loaded first, 76*e7be843bSPierre Pronchery * *before* moving on to the next chain file. 77*e7be843bSPierre Pronchery */ 78*e7be843bSPierre Pronchery if (SSL_CTX_use_certificate_chain_file(ctx, cert_path) <= 0) { 79*e7be843bSPierre Pronchery fprintf(stderr, "couldn't load certificate file: %s\n", cert_path); 80*e7be843bSPierre Pronchery goto err; 81*e7be843bSPierre Pronchery } 82*e7be843bSPierre Pronchery 83*e7be843bSPierre Pronchery /* 84*e7be843bSPierre Pronchery * Load the corresponding private key, this also checks that the private 85*e7be843bSPierre Pronchery * key matches the just loaded end-entity certificate. It does not check 86*e7be843bSPierre Pronchery * whether the certificate chain is valid, the certificates could be 87*e7be843bSPierre Pronchery * expired, or may otherwise fail to form a chain that a client can 88*e7be843bSPierre Pronchery * validate. 89*e7be843bSPierre Pronchery */ 90*e7be843bSPierre Pronchery if (SSL_CTX_use_PrivateKey_file(ctx, key_path, SSL_FILETYPE_PEM) <= 0) { 91*e7be843bSPierre Pronchery fprintf(stderr, "couldn't load key file: %s\n", key_path); 92*e7be843bSPierre Pronchery goto err; 93*e7be843bSPierre Pronchery } 94*e7be843bSPierre Pronchery 95*e7be843bSPierre ProncheryMost servers, including this one, do not solicit client certificates. We 96*e7be843bSPierre Proncherytherefore do not need a "trust store" and allow the handshake to complete even 97*e7be843bSPierre Proncherywhen the client does not present a certificate. Note: Even if a client did 98*e7be843bSPierre Proncherypresent a trusted certificate, for it to be useful, the server application 99*e7be843bSPierre Proncherywould still need custom code to use the verified identity to grant nondefault 100*e7be843bSPierre Proncheryaccess to that particular client. Some servers grant access to all clients 101*e7be843bSPierre Proncherywith certificates from a private CA, this then requires processing of 102*e7be843bSPierre Proncherycertificate revocation lists to deauthorise a client. It is often simpler and 103*e7be843bSPierre Proncherymore secure to instead keep a list of authorised public keys. 104*e7be843bSPierre Pronchery 105*e7be843bSPierre ProncheryThough this is the default setting, we explicitly call the 106*e7be843bSPierre ProncheryL<SSL_CTX_set_verify(3)> function and pass the B<SSL_VERIFY_NONE> value to it. 107*e7be843bSPierre ProncheryThe final argument to this function is a callback that you can optionally 108*e7be843bSPierre Proncherysupply to override the default handling for certificate verification. Most 109*e7be843bSPierre Proncheryapplications do not need to do this so this can safely be set to NULL to get 110*e7be843bSPierre Proncherythe default handling. 111*e7be843bSPierre Pronchery 112*e7be843bSPierre Pronchery /* 113*e7be843bSPierre Pronchery * Clients rarely employ certificate-based authentication, and so we don't 114*e7be843bSPierre Pronchery * require "mutual" TLS authentication (indeed there's no way to know 115*e7be843bSPierre Pronchery * whether or how the client authenticated the server, so the term "mutual" 116*e7be843bSPierre Pronchery * is potentially misleading). 117*e7be843bSPierre Pronchery * 118*e7be843bSPierre Pronchery * Since we're not soliciting or processing client certificates, we don't 119*e7be843bSPierre Pronchery * need to configure a trusted-certificate store, so no call to 120*e7be843bSPierre Pronchery * SSL_CTX_set_default_verify_paths() is needed. The server's own 121*e7be843bSPierre Pronchery * certificate chain is assumed valid. 122*e7be843bSPierre Pronchery */ 123*e7be843bSPierre Pronchery SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, NULL); 124*e7be843bSPierre Pronchery 125*e7be843bSPierre ProncheryQUIC also dictates using Application-Layer Protocol Negotiation (ALPN) to select 126*e7be843bSPierre Proncheryan application protocol. We use L<SSL_CTX_set_alpn_select_cb(3)> for this 127*e7be843bSPierre Proncherypurpose. We can pass a callback which will be called for each connection to 128*e7be843bSPierre Proncheryselect an ALPN the server considers acceptable. 129*e7be843bSPierre Pronchery 130*e7be843bSPierre Pronchery /* Setup ALPN negotiation callback to decide which ALPN is accepted. */ 131*e7be843bSPierre Pronchery SSL_CTX_set_alpn_select_cb(ctx, select_alpn, NULL); 132*e7be843bSPierre Pronchery 133*e7be843bSPierre ProncheryIn this case, we only accept "http/1.0" and "hq-interop". 134*e7be843bSPierre Pronchery 135*e7be843bSPierre Pronchery /* 136*e7be843bSPierre Pronchery * ALPN strings for TLS handshake. Only 'http/1.0' and 'hq-interop' 137*e7be843bSPierre Pronchery * are accepted. 138*e7be843bSPierre Pronchery */ 139*e7be843bSPierre Pronchery static const unsigned char alpn_ossltest[] = { 140*e7be843bSPierre Pronchery 8, 'h', 't', 't', 'p', '/', '1', '.', '0', 141*e7be843bSPierre Pronchery 10, 'h', 'q', '-', 'i', 'n', 't', 'e', 'r', 'o', 'p', 142*e7be843bSPierre Pronchery }; 143*e7be843bSPierre Pronchery 144*e7be843bSPierre Pronchery static int select_alpn(SSL *ssl, const unsigned char **out, 145*e7be843bSPierre Pronchery unsigned char *out_len, const unsigned char *in, 146*e7be843bSPierre Pronchery unsigned int in_len, void *arg) 147*e7be843bSPierre Pronchery { 148*e7be843bSPierre Pronchery if (SSL_select_next_proto((unsigned char **)out, out_len, alpn_ossltest, 149*e7be843bSPierre Pronchery sizeof(alpn_ossltest), in, 150*e7be843bSPierre Pronchery in_len) == OPENSSL_NPN_NEGOTIATED) 151*e7be843bSPierre Pronchery return SSL_TLSEXT_ERR_OK; 152*e7be843bSPierre Pronchery return SSL_TLSEXT_ERR_ALERT_FATAL; 153*e7be843bSPierre Pronchery } 154*e7be843bSPierre Pronchery 155*e7be843bSPierre ProncheryThat is all the setup that we need to do for the B<SSL_CTX>. Next, we create a 156*e7be843bSPierre ProncheryUDP socket and bind to it on localhost. 157*e7be843bSPierre Pronchery 158*e7be843bSPierre Pronchery /* Retrieve the file descriptor for a new UDP socket */ 159*e7be843bSPierre Pronchery if ((fd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP)) < 0) { 160*e7be843bSPierre Pronchery fprintf(stderr, "cannot create socket"); 161*e7be843bSPierre Pronchery goto err; 162*e7be843bSPierre Pronchery } 163*e7be843bSPierre Pronchery 164*e7be843bSPierre Pronchery sa.sin_family = AF_INET; 165*e7be843bSPierre Pronchery sa.sin_port = htons(port); 166*e7be843bSPierre Pronchery 167*e7be843bSPierre Pronchery /* Bind to the new UDP socket on localhost */ 168*e7be843bSPierre Pronchery if (bind(fd, (const struct sockaddr *)&sa, sizeof(sa)) < 0) { 169*e7be843bSPierre Pronchery fprintf(stderr, "cannot bind to %u\n", port); 170*e7be843bSPierre Pronchery BIO_closesocket(fd); 171*e7be843bSPierre Pronchery goto err; 172*e7be843bSPierre Pronchery } 173*e7be843bSPierre Pronchery 174*e7be843bSPierre ProncheryTo run the QUIC server, we create an B<SSL_LISTENER> to listen for incoming 175*e7be843bSPierre Proncheryconnections. We provide it with the bound UDP port to then explicitly begin 176*e7be843bSPierre Proncherylistening for new connections. 177*e7be843bSPierre Pronchery 178*e7be843bSPierre Pronchery /* 179*e7be843bSPierre Pronchery * Create a new QUIC listener. Listeners, and other QUIC objects, default 180*e7be843bSPierre Pronchery * to operating in blocking mode. The configured behaviour is inherited by 181*e7be843bSPierre Pronchery * child objects. 182*e7be843bSPierre Pronchery */ 183*e7be843bSPierre Pronchery if ((listener = SSL_new_listener(ctx, 0)) == NULL) { 184*e7be843bSPierre Pronchery goto err; 185*e7be843bSPierre Pronchery } 186*e7be843bSPierre Pronchery 187*e7be843bSPierre Pronchery /* Provide the listener with our UDP socket. */ 188*e7be843bSPierre Pronchery if (!SSL_set_fd(listener, fd)) 189*e7be843bSPierre Pronchery goto err; 190*e7be843bSPierre Pronchery 191*e7be843bSPierre Pronchery /* Begin listening. */ 192*e7be843bSPierre Pronchery if (!SSL_listen(listener)) 193*e7be843bSPierre Pronchery goto err; 194*e7be843bSPierre Pronchery 195*e7be843bSPierre Pronchery=head2 Server loop 196*e7be843bSPierre Pronchery 197*e7be843bSPierre ProncheryThe server now enters a "forever" loop, handling one client connection at a 198*e7be843bSPierre Proncherytime. Before each connection, we clear the OpenSSL error stack so that any 199*e7be843bSPierre Proncheryerror reports are related to just the new connection. 200*e7be843bSPierre Pronchery 201*e7be843bSPierre Pronchery /* Pristine error stack for each new connection */ 202*e7be843bSPierre Pronchery ERR_clear_error(); 203*e7be843bSPierre Pronchery 204*e7be843bSPierre ProncheryAt this point, the server blocks to accept the next client. 205*e7be843bSPierre ProncheryL<SSL_accept_connection(3)> will return an accepted connection within a fresh 206*e7be843bSPierre ProncherySSL, in which the handshake will have already occurred. 207*e7be843bSPierre Pronchery 208*e7be843bSPierre Pronchery /* Block while waiting for a client connection */ 209*e7be843bSPierre Pronchery conn = SSL_accept_connection(listener, 0); 210*e7be843bSPierre Pronchery if (conn == NULL) { 211*e7be843bSPierre Pronchery fprintf(stderr, "error while accepting connection\n"); 212*e7be843bSPierre Pronchery goto err; 213*e7be843bSPierre Pronchery } 214*e7be843bSPierre Pronchery 215*e7be843bSPierre ProncheryWith the handshake complete, the server echoes client input back to the client 216*e7be843bSPierre Proncheryin a loop. 217*e7be843bSPierre Pronchery 218*e7be843bSPierre Pronchery while (SSL_read_ex(conn, buf, sizeof(buf), &nread) > 0) { 219*e7be843bSPierre Pronchery if (SSL_write_ex(conn, buf, nread, &nwritten) > 0 && 220*e7be843bSPierre Pronchery nwritten == nread) { 221*e7be843bSPierre Pronchery continue; 222*e7be843bSPierre Pronchery } 223*e7be843bSPierre Pronchery fprintf(stderr, "Error echoing client input"); 224*e7be843bSPierre Pronchery break; 225*e7be843bSPierre Pronchery } 226*e7be843bSPierre Pronchery 227*e7be843bSPierre ProncheryOnce the client closes its connection, we signal the end of the stream by using 228*e7be843bSPierre ProncheryL<SSL_stream_conclude(3)>. This will send a final Finished packet to the 229*e7be843bSPierre Proncheryclient. 230*e7be843bSPierre Pronchery 231*e7be843bSPierre Pronchery /* Signal the end of the stream. */ 232*e7be843bSPierre Pronchery if (SSL_stream_conclude(conn, 0) != 1) { 233*e7be843bSPierre Pronchery fprintf(stderr, "Unable to conclude stream\n"); 234*e7be843bSPierre Pronchery SSL_free(conn); 235*e7be843bSPierre Pronchery goto err; 236*e7be843bSPierre Pronchery } 237*e7be843bSPierre Pronchery 238*e7be843bSPierre ProncheryWe then shut down the connection with L<SSL_shutdown_ex(3)>, which may need 239*e7be843bSPierre Proncheryto be called multiple times to ensure the connection is shutdown completely. 240*e7be843bSPierre Pronchery 241*e7be843bSPierre Pronchery while (SSL_shutdown_ex(conn, 0, &shutdown_args, 242*e7be843bSPierre Pronchery sizeof(SSL_SHUTDOWN_EX_ARGS)) != 1) { 243*e7be843bSPierre Pronchery fprintf(stderr, "Re-attempting SSL shutdown\n"); 244*e7be843bSPierre Pronchery } 245*e7be843bSPierre Pronchery 246*e7be843bSPierre ProncheryFinally, we free the SSL connection, and the server is now ready to accept the 247*e7be843bSPierre Proncherynext client connection. 248*e7be843bSPierre Pronchery 249*e7be843bSPierre Pronchery SSL_free(conn); 250*e7be843bSPierre Pronchery 251*e7be843bSPierre Pronchery=head2 Final clean up 252*e7be843bSPierre Pronchery 253*e7be843bSPierre ProncheryIf the server somehow manages to break out of the infinite loop and 254*e7be843bSPierre Proncherybe ready to exit, it would deallocate the constructed B<SSL>. 255*e7be843bSPierre Pronchery 256*e7be843bSPierre Pronchery SSL_free(listener); 257*e7be843bSPierre Pronchery 258*e7be843bSPierre ProncheryAnd in the main function, it would deallocate the constructed B<SSL_CTX>. 259*e7be843bSPierre Pronchery 260*e7be843bSPierre Pronchery SSL_CTX_free(ctx); 261*e7be843bSPierre Pronchery BIO_closesocket(fd); 262*e7be843bSPierre Pronchery res = EXIT_SUCCESS; 263*e7be843bSPierre Pronchery return res; 264*e7be843bSPierre Pronchery 265*e7be843bSPierre Pronchery=head1 SEE ALSO 266*e7be843bSPierre Pronchery 267*e7be843bSPierre ProncheryL<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>, 268*e7be843bSPierre ProncheryL<ossl-guide-libssl-introduction(7)>, L<ossl-guide-quic-introduction(7)>, 269*e7be843bSPierre ProncheryL<ossl-guide-quic-client-non-block(7)>, L<ossl-guide-quic-client-block(7)>, 270*e7be843bSPierre ProncheryL<ossl-guide-tls-server-block(7)>, L<ossl-guide-quic-server-non-block(7)> 271*e7be843bSPierre Pronchery 272*e7be843bSPierre Pronchery=head1 COPYRIGHT 273*e7be843bSPierre Pronchery 274*e7be843bSPierre ProncheryCopyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 275*e7be843bSPierre Pronchery 276*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 277*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 278*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 279*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 280*e7be843bSPierre Pronchery 281*e7be843bSPierre Pronchery=cut 282