1=pod 2 3=begin comment 4 5NB: Changes to the source code samples in this file should also be reflected in 6demos/guide/tls-client-block.c 7 8=end comment 9 10=head1 NAME 11 12ossl-guide-tls-client-block 13- OpenSSL Guide: Writing a simple blocking TLS client 14 15=head1 SIMPLE BLOCKING TLS CLIENT EXAMPLE 16 17This page will present various source code samples demonstrating how to write 18a simple TLS client application which connects to a server, sends an HTTP/1.0 19request to it, and reads back the response. 20 21We use a blocking socket for the purposes of this example. This means that 22attempting to read data from a socket that has no data available on it to read 23will block (and the function will not return), until data becomes available. 24For example, this can happen if we have sent our request, but we are still 25waiting for the server's response. Similarly any attempts to write to a socket 26that is not able to write at the moment will block until writing is possible. 27 28This blocking behaviour simplifies the implementation of a client because you do 29not have to worry about what happens if data is not yet available. The 30application will simply wait until it is available. 31 32The complete source code for this example blocking TLS client is available in 33the B<demos/guide> directory of the OpenSSL source distribution in the file 34B<tls-client-block.c>. It is also available online at 35L<https://github.com/openssl/openssl/blob/master/demos/guide/tls-client-block.c>. 36 37We assume that you already have OpenSSL installed on your system; that you 38already have some fundamental understanding of OpenSSL concepts and TLS (see 39L<ossl-guide-libraries-introduction(7)> and L<ossl-guide-tls-introduction(7)>); 40and that you know how to write and build C code and link it against the 41libcrypto and libssl libraries that are provided by OpenSSL. It also assumes 42that you have a basic understanding of TCP/IP and sockets. 43 44=head2 Creating the SSL_CTX and SSL objects 45 46The first step is to create an B<SSL_CTX> object for our client. We use the 47L<SSL_CTX_new(3)> function for this purpose. We could alternatively use 48L<SSL_CTX_new_ex(3)> if we want to associate the B<SSL_CTX> with a particular 49B<OSSL_LIB_CTX> (see L<ossl-guide-libraries-introduction(7)> to learn about 50B<OSSL_LIB_CTX>). We pass as an argument the return value of the function 51L<TLS_client_method(3)>. You should use this method whenever you are writing a 52TLS client. This method will automatically use TLS version negotiation to select 53the highest version of the protocol that is mutually supported by both the 54client and the server. 55 56 /* 57 * Create an SSL_CTX which we can use to create SSL objects from. We 58 * want an SSL_CTX for creating clients so we use TLS_client_method() 59 * here. 60 */ 61 ctx = SSL_CTX_new(TLS_client_method()); 62 if (ctx == NULL) { 63 printf("Failed to create the SSL_CTX\n"); 64 goto end; 65 } 66 67Since we are writing a client we must ensure that we verify the server's 68certificate. We do this by calling the L<SSL_CTX_set_verify(3)> function and 69pass the B<SSL_VERIFY_PEER> value to it. The final argument to this function 70is a callback that you can optionally supply to override the default handling 71for certificate verification. Most applications do not need to do this so this 72can safely be set to NULL to get the default handling. 73 74 /* 75 * Configure the client to abort the handshake if certificate 76 * verification fails. Virtually all clients should do this unless you 77 * really know what you are doing. 78 */ 79 SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, NULL); 80 81In order for certificate verification to be successful you must have configured 82where the trusted certificate store to be used is located (see 83L<ossl-guide-tls-introduction(7)>). In most cases you just want to use the 84default store so we call L<SSL_CTX_set_default_verify_paths(3)>. 85 86 /* Use the default trusted certificate store */ 87 if (!SSL_CTX_set_default_verify_paths(ctx)) { 88 printf("Failed to set the default trusted certificate store\n"); 89 goto end; 90 } 91 92We would also like to restrict the TLS versions that we are willing to accept to 93TLSv1.2 or above. TLS protocol versions earlier than that are generally to be 94avoided where possible. We can do that using 95L<SSL_CTX_set_min_proto_version(3)>: 96 97 /* 98 * TLSv1.1 or earlier are deprecated by IETF and are generally to be 99 * avoided if possible. We require a minimum TLS version of TLSv1.2. 100 */ 101 if (!SSL_CTX_set_min_proto_version(ctx, TLS1_2_VERSION)) { 102 printf("Failed to set the minimum TLS protocol version\n"); 103 goto end; 104 } 105 106That is all the setup that we need to do for the B<SSL_CTX>, so next we need to 107create an B<SSL> object to represent the TLS connection. In a real application 108we might expect to be creating more than one TLS connection over time. In that 109case we would expect to reuse the B<SSL_CTX> that we already created each time. 110There is no need to repeat those steps. In fact it is best not to since certain 111internal resources are cached in the B<SSL_CTX>. You will get better performance 112by reusing an existing B<SSL_CTX> instead of creating a new one each time. 113 114Creating the B<SSL> object is a simple matter of calling the B<SSL_new(3)> 115function and passing the B<SSL_CTX> we created as an argument. 116 117 /* Create an SSL object to represent the TLS connection */ 118 ssl = SSL_new(ctx); 119 if (ssl == NULL) { 120 printf("Failed to create the SSL object\n"); 121 goto end; 122 } 123 124=head2 Creating the socket and BIO 125 126TLS data is transmitted over an underlying transport layer. Normally a TCP 127socket. It is the application's responsibility for ensuring that the socket is 128created and associated with an SSL object (via a BIO). 129 130Socket creation for use by a client is typically a 2 step process, i.e. 131constructing the socket; and connecting the socket. 132 133How to construct a socket is platform specific - but most platforms (including 134Windows) provide a POSIX compatible interface via the I<socket> function, e.g. 135to create an IPv4 TCP socket: 136 137 int sock; 138 139 sock = socket(AF_INET, SOCK_STREAM, 0); 140 if (sock == -1) 141 return NULL; 142 143Once the socket is constructed it must be connected to the remote server. Again 144the details are platform specific but most platforms (including Windows) 145provide the POSIX compatible I<connect> function. For example: 146 147 struct sockaddr_in serveraddr; 148 struct hostent *server; 149 150 server = gethostbyname("www.openssl.org"); 151 if (server == NULL) { 152 close(sock); 153 return NULL; 154 } 155 156 memset(&serveraddr, 0, sizeof(serveraddr)); 157 serveraddr.sin_family = server->h_addrtype; 158 serveraddr.sin_port = htons(443); 159 memcpy(&serveraddr.sin_addr.s_addr, server->h_addr, server->h_length); 160 161 if (connect(sock, (struct sockaddr *)&serveraddr, 162 sizeof(serveraddr)) == -1) { 163 close(sock); 164 return NULL; 165 } 166 167OpenSSL provides portable helper functions to do these tasks which also 168integrate into the OpenSSL error system to log error data, e.g. 169 170 int sock = -1; 171 BIO_ADDRINFO *res; 172 const BIO_ADDRINFO *ai = NULL; 173 174 /* 175 * Lookup IP address info for the server. 176 */ 177 if (!BIO_lookup_ex(hostname, port, BIO_LOOKUP_CLIENT, family, SOCK_STREAM, 0, 178 &res)) 179 return NULL; 180 181 /* 182 * Loop through all the possible addresses for the server and find one 183 * we can connect to. 184 */ 185 for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { 186 /* 187 * Create a TCP socket. We could equally use non-OpenSSL calls such 188 * as "socket" here for this and the subsequent connect and close 189 * functions. But for portability reasons and also so that we get 190 * errors on the OpenSSL stack in the event of a failure we use 191 * OpenSSL's versions of these functions. 192 */ 193 sock = BIO_socket(BIO_ADDRINFO_family(ai), SOCK_STREAM, 0, 0); 194 if (sock == -1) 195 continue; 196 197 /* Connect the socket to the server's address */ 198 if (!BIO_connect(sock, BIO_ADDRINFO_address(ai), BIO_SOCK_NODELAY)) { 199 BIO_closesocket(sock); 200 sock = -1; 201 continue; 202 } 203 204 /* We have a connected socket so break out of the loop */ 205 break; 206 } 207 208 /* Free the address information resources we allocated earlier */ 209 BIO_ADDRINFO_free(res); 210 211See L<BIO_lookup_ex(3)>, L<BIO_socket(3)>, L<BIO_connect(3)>, 212L<BIO_closesocket(3)>, L<BIO_ADDRINFO_next(3)>, L<BIO_ADDRINFO_address(3)> and 213L<BIO_ADDRINFO_free(3)> for further information on the functions used here. In 214the above example code the B<hostname> and B<port> variables are strings, e.g. 215"www.example.com" and "443". Note also the use of the family variable, which 216can take the values of AF_INET or AF_INET6 based on the command line -6 option, 217to allow specific connections to an ipv4 or ipv6 enabled host. 218 219Sockets created using the methods described above will automatically be blocking 220sockets - which is exactly what we want for this example. 221 222Once the socket has been created and connected we need to associate it with a 223BIO object: 224 225 BIO *bio; 226 227 /* Create a BIO to wrap the socket */ 228 bio = BIO_new(BIO_s_socket()); 229 if (bio == NULL) { 230 BIO_closesocket(sock); 231 return NULL; 232 } 233 234 /* 235 * Associate the newly created BIO with the underlying socket. By 236 * passing BIO_CLOSE here the socket will be automatically closed when 237 * the BIO is freed. Alternatively you can use BIO_NOCLOSE, in which 238 * case you must close the socket explicitly when it is no longer 239 * needed. 240 */ 241 BIO_set_fd(bio, sock, BIO_CLOSE); 242 243See L<BIO_new(3)>, L<BIO_s_socket(3)> and L<BIO_set_fd(3)> for further 244information on these functions. 245 246Finally we associate the B<SSL> object we created earlier with the B<BIO> using 247the L<SSL_set_bio(3)> function. Note that this passes ownership of the B<BIO> 248object to the B<SSL> object. Once ownership is passed the SSL object is 249responsible for its management and will free it automatically when the B<SSL> is 250freed. So, once L<SSL_set_bio(3)> has been been called, you should not call 251L<BIO_free(3)> on the B<BIO>. 252 253 SSL_set_bio(ssl, bio, bio); 254 255=head2 Setting the server's hostname 256 257We have already connected our underlying socket to the server, but the client 258still needs to know the server's hostname. It uses this information for 2 key 259purposes and we need to set the hostname for each one. 260 261Firstly, the server's hostname is included in the initial ClientHello message 262sent by the client. This is known as the Server Name Indication (SNI). This is 263important because it is common for multiple hostnames to be fronted by a single 264server that handles requests for all of them. In other words a single server may 265have multiple hostnames associated with it and it is important to indicate which 266one we want to connect to. Without this information we may get a handshake 267failure, or we may get connected to the "default" server which may not be the 268one we were expecting. 269 270To set the SNI hostname data we call the L<SSL_set_tlsext_host_name(3)> function 271like this: 272 273 /* 274 * Tell the server during the handshake which hostname we are attempting 275 * to connect to in case the server supports multiple hosts. 276 */ 277 if (!SSL_set_tlsext_host_name(ssl, hostname)) { 278 printf("Failed to set the SNI hostname\n"); 279 goto end; 280 } 281 282Here the C<hostname> argument is a string representing the hostname of the 283server, e.g. "www.example.com". 284 285Secondly, we need to tell OpenSSL what hostname we expect to see in the 286certificate coming back from the server. This is almost always the same one that 287we asked for in the original request. This is important because, without this, 288we do not verify that the hostname in the certificate is what we expect it to be 289and any certificate is acceptable unless your application explicitly checks this 290itself. We do this via the L<SSL_set1_host(3)> function: 291 292 /* 293 * Ensure we check during certificate verification that the server has 294 * supplied a certificate for the hostname that we were expecting. 295 * Virtually all clients should do this unless you really know what you 296 * are doing. 297 */ 298 if (!SSL_set1_host(ssl, hostname)) { 299 printf("Failed to set the certificate verification hostname"); 300 goto end; 301 } 302 303All of the above steps must happen before we attempt to perform the handshake 304otherwise they will have no effect. 305 306=head2 Performing the handshake 307 308Before we can start sending or receiving application data over a TLS connection 309the TLS handshake must be performed. We can do this explicitly via the 310L<SSL_connect(3)> function. 311 312 /* Do the handshake with the server */ 313 if (SSL_connect(ssl) < 1) { 314 printf("Failed to connect to the server\n"); 315 /* 316 * If the failure is due to a verification error we can get more 317 * information about it from SSL_get_verify_result(). 318 */ 319 if (SSL_get_verify_result(ssl) != X509_V_OK) 320 printf("Verify error: %s\n", 321 X509_verify_cert_error_string(SSL_get_verify_result(ssl))); 322 goto end; 323 } 324 325The L<SSL_connect(3)> function can return 1, 0 or less than 0. Only a return 326value of 1 is considered a success. For a simple blocking client we only need 327to concern ourselves with whether the call was successful or not. Anything else 328indicates that we have failed to connect to the server. 329 330A common cause of failures at this stage is due to a problem verifying the 331server's certificate. For example if the certificate has expired, or it is not 332signed by a CA in our trusted certificate store. We can use the 333L<SSL_get_verify_result(3)> function to find out more information about the 334verification failure. A return value of B<X509_V_OK> indicates that the 335verification was successful (so the connection error must be due to some other 336cause). Otherwise we use the L<X509_verify_cert_error_string(3)> function to get 337a human readable error message. 338 339=head2 Sending and receiving data 340 341Once the handshake is complete we are able to send and receive application data. 342Exactly what data is sent and in what order is usually controlled by some 343application level protocol. In this example we are using HTTP 1.0 which is a 344very simple request and response protocol. The client sends a request to the 345server. The server sends the response data and then immediately closes down the 346connection. 347 348To send data to the server we use the L<SSL_write_ex(3)> function and to receive 349data from the server we use the L<SSL_read_ex(3)> function. In HTTP 1.0 the 350client always writes data first. Our HTTP request will include the hostname that 351we are connecting to. For simplicity, we write the HTTP request in three 352chunks. First we write the start of the request. Secondly we write the hostname 353we are sending the request to. Finally we send the end of the request. 354 355 size_t written; 356 const char *request_start = "GET / HTTP/1.0\r\nConnection: close\r\nHost: "; 357 const char *request_end = "\r\n\r\n"; 358 359 /* Write an HTTP GET request to the peer */ 360 if (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) { 361 printf("Failed to write start of HTTP request\n"); 362 goto end; 363 } 364 if (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) { 365 printf("Failed to write hostname in HTTP request\n"); 366 goto end; 367 } 368 if (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) { 369 printf("Failed to write end of HTTP request\n"); 370 goto end; 371 } 372 373The L<SSL_write_ex(3)> function returns 0 if it fails and 1 if it is successful. 374If it is successful then we can proceed to waiting for a response from the 375server. 376 377 size_t readbytes; 378 char buf[160]; 379 380 /* 381 * Get up to sizeof(buf) bytes of the response. We keep reading until the 382 * server closes the connection. 383 */ 384 while (SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) { 385 /* 386 * OpenSSL does not guarantee that the returned data is a string or 387 * that it is NUL terminated so we use fwrite() to write the exact 388 * number of bytes that we read. The data could be non-printable or 389 * have NUL characters in the middle of it. For this simple example 390 * we're going to print it to stdout anyway. 391 */ 392 fwrite(buf, 1, readbytes, stdout); 393 } 394 /* In case the response didn't finish with a newline we add one now */ 395 printf("\n"); 396 397 398We use the L<SSL_read_ex(3)> function to read the response. We don't know 399exactly how much data we are going to receive back so we enter a loop reading 400blocks of data from the server and printing each block that we receive to the 401screen. The loop ends as soon as L<SSL_read_ex(3)> returns 0 - meaning that it 402failed to read any data. 403 404A failure to read data could mean that there has been some error, or it could 405simply mean that server has sent all the data that it wants to send and has 406indicated that it has finished by sending a "close_notify" alert. This alert is 407a TLS protocol level message indicating that the endpoint has finished sending 408all of its data and it will not send any more. Both of these conditions result 409in a 0 return value from L<SSL_read_ex(3)> and we need to use the function 410L<SSL_get_error(3)> to determine the cause of the 0 return value. 411 412 /* 413 * Check whether we finished the while loop above normally or as the 414 * result of an error. The 0 argument to SSL_get_error() is the return 415 * code we received from the SSL_read_ex() call. It must be 0 in order 416 * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. 417 */ 418 if (SSL_get_error(ssl, 0) != SSL_ERROR_ZERO_RETURN) { 419 /* 420 * Some error occurred other than a graceful close down by the 421 * peer 422 */ 423 printf ("Failed reading remaining data\n"); 424 goto end; 425 } 426 427If L<SSL_get_error(3)> returns B<SSL_ERROR_ZERO_RETURN> then we know that the 428server has finished sending its data. Otherwise an error has occurred. 429 430=head2 Shutting down the connection 431 432Once we have finished reading data from the server then we are ready to close 433the connection down. We do this via the L<SSL_shutdown(3)> function which has 434the effect of sending a TLS protocol level message (a "close_notify" alert) to 435the server saying that we have finished writing data: 436 437 /* 438 * The peer already shutdown gracefully (we know this because of the 439 * SSL_ERROR_ZERO_RETURN above). We should do the same back. 440 */ 441 ret = SSL_shutdown(ssl); 442 if (ret < 1) { 443 /* 444 * ret < 0 indicates an error. ret == 0 would be unexpected here 445 * because that means "we've sent a close_notify and we're waiting 446 * for one back". But we already know we got one from the peer 447 * because of the SSL_ERROR_ZERO_RETURN above. 448 */ 449 printf("Error shutting down\n"); 450 goto end; 451 } 452 453The L<SSL_shutdown(3)> function will either return 1, 0, or less than 0. A 454return value of 1 is a success, and a return value less than 0 is an error. More 455precisely a return value of 1 means that we have sent a "close_notify" alert to 456the server, and that we have also received one back. A return value of 0 means 457that we have sent a "close_notify" alert to the server, but we have not yet 458received one back. Usually in this scenario you would call L<SSL_shutdown(3)> 459again which (with a blocking socket) would block until the "close_notify" is 460received. However in this case we already know that the server has sent us a 461"close_notify" because of the SSL_ERROR_ZERO_RETURN that we received from the 462call to L<SSL_read_ex(3)>. So this scenario should never happen in practice. We 463just treat it as an error in this example. 464 465=head2 Final clean up 466 467Before the application exits we have to clean up some memory that we allocated. 468If we are exiting due to an error we might also want to display further 469information about that error if it is available to the user: 470 471 /* Success! */ 472 res = EXIT_SUCCESS; 473 end: 474 /* 475 * If something bad happened then we will dump the contents of the 476 * OpenSSL error stack to stderr. There might be some useful diagnostic 477 * information there. 478 */ 479 if (res == EXIT_FAILURE) 480 ERR_print_errors_fp(stderr); 481 482 /* 483 * Free the resources we allocated. We do not free the BIO object here 484 * because ownership of it was immediately transferred to the SSL object 485 * via SSL_set_bio(). The BIO will be freed when we free the SSL object. 486 */ 487 SSL_free(ssl); 488 SSL_CTX_free(ctx); 489 return res; 490 491To display errors we make use of the L<ERR_print_errors_fp(3)> function which 492simply dumps out the contents of any errors on the OpenSSL error stack to the 493specified location (in this case I<stderr>). 494 495We need to free up the B<SSL> object that we created for the connection via the 496L<SSL_free(3)> function. Also, since we are not going to be creating any more 497TLS connections we must also free up the B<SSL_CTX> via a call to 498L<SSL_CTX_free(3)>. 499 500=head1 TROUBLESHOOTING 501 502There are a number of things that might go wrong when running the demo 503application. This section describes some common things you might encounter. 504 505=head2 Failure to connect the underlying socket 506 507This could occur for numerous reasons. For example if there is a problem in the 508network route between the client and the server; or a firewall is blocking the 509communication; or the server is not in DNS. Check the network configuration. 510 511=head2 Verification failure of the server certificate 512 513A verification failure of the server certificate would result in a failure when 514running the L<SSL_connect(3)> function. L<ERR_print_errors_fp(3)> would display 515an error which would look something like this: 516 517 Verify error: unable to get local issuer certificate 518 40E74AF1F47F0000:error:0A000086:SSL routines:tls_post_process_server_certificate:certificate verify failed:ssl/statem/statem_clnt.c:2069: 519 520A server certificate verification failure could be caused for a number of 521reasons. For example 522 523=over 4 524 525=item Failure to correctly setup the trusted certificate store 526 527See the page L<ossl-guide-tls-introduction(7)> and check that your trusted 528certificate store is correctly configured 529 530=item Unrecognised CA 531 532If the CA used by the server's certificate is not in the trusted certificate 533store for the client then this will cause a verification failure during 534connection. Often this can occur if the server is using a self-signed 535certificate (i.e. a test certificate that has not been signed by a CA at all). 536 537=item Missing intermediate CAs 538 539This is a server misconfiguration where the client has the relevant root CA in 540its trust store, but the server has not supplied all of the intermediate CA 541certificates between that root CA and the server's own certificate. Therefore 542a trust chain cannot be established. 543 544=item Mismatched hostname 545 546If for some reason the hostname of the server that the client is expecting does 547not match the hostname in the certificate then this will cause verification to 548fail. 549 550=item Expired certificate 551 552The date that the server's certificate is valid to has passed. 553 554=back 555 556The "unable to get local issuer certificate" we saw in the example above means 557that we have been unable to find the issuer of the server's certificate (or one 558of its intermediate CA certificates) in our trusted certificate store (e.g. 559because the trusted certificate store is misconfigured, or there are missing 560intermediate CAs, or the issuer is simply unrecognised). 561 562=head1 FURTHER READING 563 564See L<ossl-guide-tls-client-non-block(7)> to read a tutorial on how to modify 565the client developed on this page to support a nonblocking socket. 566 567See L<ossl-guide-tls-server-block(7)> for a tutorial on how to implement a 568simple TLS server handling one client at a time over a blocking socket. 569 570See L<ossl-guide-quic-client-block(7)> to read a tutorial on how to modify the 571client developed on this page to support QUIC instead of TLS. 572 573=head1 SEE ALSO 574 575L<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>, 576L<ossl-guide-libssl-introduction(7)>, L<ossl-guide-tls-introduction(7)>, 577L<ossl-guide-tls-client-non-block(7)>, L<ossl-guide-quic-client-block(7)> 578 579=head1 COPYRIGHT 580 581Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved. 582 583Licensed under the Apache License 2.0 (the "License"). You may not use 584this file except in compliance with the License. You can obtain a copy 585in the file LICENSE in the source distribution or at 586L<https://www.openssl.org/source/license.html>. 587 588=cut 589