Lines Matching refs:to
5 NB: Changes to the source code samples in this file should also be reflected in
17 This page will present various source code samples demonstrating how to write
18 a simple TLS client application which connects to a server, sends an HTTP/1.0
19 request to it, and reads back the response.
22 attempting to read data from a socket that has no data available on it to read
25 waiting for the server's response. Similarly any attempts to write to a socket
26 that is not able to write at the moment will block until writing is possible.
29 not have to worry about what happens if data is not yet available. The
40 and that you know how to write and build C code and link it against the
46 The first step is to create an B<SSL_CTX> object for our client. We use the
48 L<SSL_CTX_new_ex(3)> if we want to associate the B<SSL_CTX> with a particular
49 B<OSSL_LIB_CTX> (see L<ossl-guide-libraries-introduction(7)> to learn about
52 TLS client. This method will automatically use TLS version negotiation to select
57 * Create an SSL_CTX which we can use to create SSL objects from. We
63 printf("Failed to create the SSL_CTX\n");
69 pass the B<SSL_VERIFY_PEER> value to it. The final argument to this function
70 is a callback that you can optionally supply to override the default handling
71 for certificate verification. Most applications do not need to do this so this
72 can safely be set to NULL to get the default handling.
75 * Configure the client to abort the handshake if certificate
81 In order for certificate verification to be successful you must have configured
82 where the trusted certificate store to be used is located (see
83 L<ossl-guide-tls-introduction(7)>). In most cases you just want to use the
88 printf("Failed to set the default trusted certificate store\n");
92 We would also like to restrict the TLS versions that we are willing to accept to
93 TLSv1.2 or above. TLS protocol versions earlier than that are generally to be
98 * TLSv1.1 or earlier are deprecated by IETF and are generally to be
102 printf("Failed to set the minimum TLS protocol version\n");
106 That is all the setup that we need to do for the B<SSL_CTX>, so next we need to
107 create an B<SSL> object to represent the TLS connection. In a real application
108 we might expect to be creating more than one TLS connection over time. In that
109 case we would expect to reuse the B<SSL_CTX> that we already created each time.
110 There is no need to repeat those steps. In fact it is best not to since certain
117 /* Create an SSL object to represent the TLS connection */
120 printf("Failed to create the SSL object\n");
133 How to construct a socket is platform specific - but most platforms (including
135 to create an IPv4 TCP socket:
143 Once the socket is constructed it must be connected to the remote server. Again
167 OpenSSL provides portable helper functions to do these tasks which also
168 integrate into the OpenSSL error system to log error data, e.g.
183 * we can connect to.
197 /* Connect the socket to the server's address */
217 to allow specific connections to an ipv4 or ipv6 enabled host.
222 Once the socket has been created and connected we need to associate it with a
227 /* Create a BIO to wrap the socket */
248 object to the B<SSL> object. Once ownership is passed the SSL object is
257 We have already connected our underlying socket to the server, but the client
258 still needs to know the server's hostname. It uses this information for 2 key
259 purposes and we need to set the hostname for each one.
263 important because it is common for multiple hostnames to be fronted by a single
265 have multiple hostnames associated with it and it is important to indicate which
266 one we want to connect to. Without this information we may get a handshake
267 failure, or we may get connected to the "default" server which may not be the
275 * to connect to in case the server supports multiple hosts.
278 printf("Failed to set the SNI hostname\n");
285 Secondly, we need to tell OpenSSL what hostname we expect to see in the
288 we do not verify that the hostname in the certificate is what we expect it to be
299 printf("Failed to set the certificate verification hostname");
303 All of the above steps must happen before we attempt to perform the handshake
314 printf("Failed to connect to the server\n");
316 * If the failure is due to a verification error we can get more
327 to concern ourselves with whether the call was successful or not. Anything else
328 indicates that we have failed to connect to the server.
330 A common cause of failures at this stage is due to a problem verifying the
333 L<SSL_get_verify_result(3)> function to find out more information about the
335 verification was successful (so the connection error must be due to some other
336 cause). Otherwise we use the L<X509_verify_cert_error_string(3)> function to get
341 Once the handshake is complete we are able to send and receive application data.
344 very simple request and response protocol. The client sends a request to the
348 To send data to the server we use the L<SSL_write_ex(3)> function and to receive
351 we are connecting to. For simplicity, we write the HTTP request in three
353 we are sending the request to. Finally we send the end of the request.
359 /* Write an HTTP GET request to the peer */
361 printf("Failed to write start of HTTP request\n");
365 printf("Failed to write hostname in HTTP request\n");
369 printf("Failed to write end of HTTP request\n");
374 If it is successful then we can proceed to waiting for a response from the
381 * Get up to sizeof(buf) bytes of the response. We keep reading until the
387 * that it is NUL terminated so we use fwrite() to write the exact
390 * we're going to print it to stdout anyway.
398 We use the L<SSL_read_ex(3)> function to read the response. We don't know
399 exactly how much data we are going to receive back so we enter a loop reading
400 blocks of data from the server and printing each block that we receive to the
402 failed to read any data.
404 A failure to read data could mean that there has been some error, or it could
405 simply mean that server has sent all the data that it wants to send and has
409 in a 0 return value from L<SSL_read_ex(3)> and we need to use the function
410 L<SSL_get_error(3)> to determine the cause of the 0 return value.
414 * result of an error. The 0 argument to SSL_get_error() is the return
416 * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN.
432 Once we have finished reading data from the server then we are ready to close
434 the effect of sending a TLS protocol level message (a "close_notify" alert) to
455 precisely a return value of 1 means that we have sent a "close_notify" alert to
457 that we have sent a "close_notify" alert to the server, but we have not yet
462 call to L<SSL_read_ex(3)>. So this scenario should never happen in practice. We
467 Before the application exits we have to clean up some memory that we allocated.
468 If we are exiting due to an error we might also want to display further
469 information about that error if it is available to the user:
476 * OpenSSL error stack to stderr. There might be some useful diagnostic
484 * because ownership of it was immediately transferred to the SSL object
492 simply dumps out the contents of any errors on the OpenSSL error stack to the
495 We need to free up the B<SSL> object that we created for the connection via the
496 L<SSL_free(3)> function. Also, since we are not going to be creating any more
497 TLS connections we must also free up the B<SSL_CTX> via a call to
505 =head2 Failure to connect the underlying socket
517 Verify error: unable to get local issuer certificate
525 =item Failure to correctly setup the trusted certificate store
547 not match the hostname in the certificate then this will cause verification to
552 The date that the server's certificate is valid to has passed.
556 The "unable to get local issuer certificate" we saw in the example above means
557 that we have been unable to find the issuer of the server's certificate (or one
564 See L<ossl-guide-tls-client-non-block(7)> to read a tutorial on how to modify
565 the client developed on this page to support a nonblocking socket.
567 See L<ossl-guide-tls-server-block(7)> for a tutorial on how to implement a
570 See L<ossl-guide-quic-client-block(7)> to read a tutorial on how to modify the
571 client developed on this page to support QUIC instead of TLS.
