1=pod 2 3=head1 NAME 4 5ossl-guide-tls-introduction 6- OpenSSL Guide: An introduction to SSL/TLS in OpenSSL 7 8=head1 INTRODUCTION 9 10This page will provide an introduction to some basic SSL/TLS concepts and 11background and how it is used within OpenSSL. It assumes that you have a basic 12understanding of TCP/IP and sockets. 13 14=head1 WHAT IS TLS? 15 16TLS stands for Transport Layer Security. TLS allows applications to securely 17communicate with each other across a network such that the confidentiality of 18the information exchanged is protected (i.e. it prevents eavesdroppers from 19listening in to the communication). Additionally it protects the integrity of 20the information exchanged to prevent an attacker from changing it. Finally it 21provides authentication so that one or both parties can be sure that they are 22talking to who they think they are talking to and not some imposter. 23 24Sometimes TLS is referred to by its predecessor's name SSL (Secure Sockets 25Layer). OpenSSL dates from a time when the SSL name was still in common use and 26hence many of the functions and names used by OpenSSL contain the "SSL" 27abbreviation. Nonetheless OpenSSL contains a fully fledged TLS implementation. 28 29TLS is based on a client/server model. The application that initiates a 30communication is known as the client. The application that responds to a 31remotely initiated communication is the server. The term "endpoint" refers to 32either of the client or the server in a communication. The term "peer" refers to 33the endpoint at the other side of the communication that we are currently 34referring to. So if we are currently talking about the client then the peer 35would be the server. 36 37TLS is a standardised protocol and there are numerous different implementations 38of it. Due to the standards an OpenSSL client or server is able to communicate 39seamlessly with an application using some different implementation of TLS. TLS 40(and its predecessor SSL) have been around for a significant period of time and 41the protocol has undergone various changes over the years. Consequently there 42are different versions of the protocol available. TLS includes the ability to 43perform version negotiation so that the highest protocol version that the client 44and server share in common is used. 45 46TLS acts as a security layer over some lower level transport protocol. Typically 47the transport layer will be TCP. 48 49=head1 SSL AND TLS VERSIONS 50 51SSL was initially developed by Netscape Communications and its first publicly 52released version was SSLv2 in 1995. Note that SSLv1 was never publicly released. 53SSLv3 came along quickly afterwards in 1996. Subsequently development of the 54protocol moved to the IETF which released the first version of TLS (TLSv1.0) in 551999 as RFC2246. TLSv1.1 was released in 2006 as RFC4346 and TLSv1.2 came along 56in 2008 as RFC5246. The most recent version of the standard is TLSv1.3 which 57was released in 2018 as RFC8446. 58 59Today TLSv1.3 and TLSv1.2 are the most commonly deployed versions of the 60protocol. The IETF have formally deprecated TLSv1.1 and TLSv1.0, so anything 61below TLSv1.2 should be avoided since the older protocol versions are 62susceptible to security problems. 63 64OpenSSL does not support SSLv2 (it was removed in OpenSSL 1.1.0). Support for 65SSLv3 is available as a compile time option - but it is not built by default. 66Support for TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3 are all available by default 67in a standard build of OpenSSL. However special run-time configuration is 68required in order to make TLSv1.0 and TLSv1.1 work successfully. 69 70OpenSSL will always try to negotiate the highest protocol version that it has 71been configured to support. In most cases this will mean either TLSv1.3 or 72TLSv1.2 is chosen. 73 74=head1 CERTIFICATES 75 76In order for a client to establish a connection to a server it must authenticate 77the identify of that server, i.e. it needs to confirm that the server is really 78the server that it claims to be and not some imposter. In order to do this the 79server will send to the client a digital certificate (also commonly referred to 80as an X.509 certificate). The certificate contains various information about the 81server including its full DNS hostname. Also within the certificate is the 82server's public key. The server operator will have a private key which is 83linked to the public key and must not be published. 84 85Along with the certificate the server will also send to the client proof that it 86knows the private key associated with the public key in the certificate. It does 87this by digitally signing a message to the client using that private key. The 88client can verify the signature using the public key from the certificate. If 89the signature verifies successfully then the client knows that the server is in 90possession of the correct private key. 91 92The certificate that the server sends will also be signed by a Certificate 93Authority. The Certificate Authority (commonly known as a CA) is a third party 94organisation that is responsible for verifying the information in the server's 95certificate (including its DNS hostname). The CA should only sign the 96certificate if it has been able to confirm that the server operator does indeed 97have control of the server associated with its DNS hostname and that the server 98operator has control of the private key. 99 100In this way, if the client trusts the CA that has signed the server's 101certificate and it can verify that the server has the right private key then it 102can trust that the server truly does represent the DNS hostname given in the 103certificate. The client must also verify that the hostname given in the 104certificate matches the hostname that it originally sent the request to. 105 106Once all of these checks have been done the client has successfully verified the 107identify of the server. OpenSSL can perform all of these checks automatically 108but it must be provided with certain information in order to do so, i.e. the set 109of CAs that the client trusts as well as the DNS hostname for the server that 110this client is trying to connect to. 111 112Note that it is common for certificates to be built up into a chain. For example 113a server's certificate may be signed by a key owned by a an intermediate CA. 114That intermediate CA also has a certificate containing its public key which is 115in turn signed by a key owned by a root CA. The client may only trust the root 116CA, but if the server sends both its own certificate and the certificate for the 117intermediate CA then the client can still successfully verify the identity of 118the server. There is a chain of trust between the root CA and the server. 119 120By default it is only the client that authenticates the server using this 121method. However it is also possible to set things up such that the server 122additionally authenticates the client. This is known as "client authentication". 123In this approach the client will still authenticate the server in the same way, 124but the server will request a certificate from the client. The client sends the 125server its certificate and the server authenticates it in the same way that the 126client does. 127 128=head1 TRUSTED CERTIFICATE STORE 129 130The system described above only works if a chain of trust can be built between 131the set of CAs that the endpoint trusts and the certificate that the peer is 132using. The endpoint must therefore have a set of certificates for CAs that it 133trusts before any communication can take place. OpenSSL itself does not provide 134such a set of certificates. Therefore you will need to make sure you have them 135before you start if you are going to be verifying certificates (i.e. always if 136the endpoint is a client, and only if client authentication is in use for a 137server). 138 139Fortunately other organisations do maintain such a set of certificates. If you 140have obtained your copy of OpenSSL from an Operating System (OS) vendor (e.g. a 141Linux distribution) then normally the set of CA certificates will also be 142distributed with that copy. 143 144You can check this by running the OpenSSL command line application like this: 145 146 openssl version -d 147 148This will display a value for B<OPENSSLDIR>. Look in the B<certs> sub directory 149of B<OPENSSLDIR> and check its contents. For example if B<OPENSSLDIR> is 150"/usr/local/ssl", then check the contents of the "/usr/local/ssl/certs" 151directory. 152 153You are expecting to see a list of files, typically with the suffix ".pem" or 154".0". If they exist then you already have a suitable trusted certificate store. 155 156If you are running your version of OpenSSL on Windows then OpenSSL (from version 1573.2 onwards) will use the default Windows set of trusted CAs. 158 159If you have built your version of OpenSSL from source, or obtained it from some 160other location and it does not have a set of trusted CA certificates then you 161will have to obtain them yourself. One such source is the Curl project. See the 162page L<https://curl.se/docs/caextract.html> where you can download trusted 163certificates in a single file. Rename the file to "cert.pem" and store it 164directly in B<OPENSSLDIR>. For example if B<OPENSSLDIR> is "/usr/local/ssl", 165then save it as "/usr/local/ssl/cert.pem". 166 167You can also use environment variables to override the default location that 168OpenSSL will look for its trusted certificate store. Set the B<SSL_CERT_PATH> 169environment variable to give the directory where OpenSSL should looks for its 170certificates or the B<SSL_CERT_FILE> environment variable to give the name of 171a single file containing all of the certificates. See L<openssl-env(7)> for 172further details about OpenSSL environment variables. For example you could use 173this capability to have multiple versions of OpenSSL all installed on the same 174system using different values for B<OPENSSLDIR> but all using the same 175trusted certificate store. 176 177You can test that your trusted certificate store is setup correctly by using it 178via the OpenSSL command line. Use the following command to connect to a TLS 179server: 180 181 openssl s_client www.openssl.org:443 182 183Once the command has connected type the letter "Q" followed by "<enter>" to exit 184the session. This will print a lot of information on the screen about the 185connection. Look for a block of text like this: 186 187 SSL handshake has read 4584 bytes and written 403 bytes 188 Verification: OK 189 190Hopefully if everything has worked then the "Verification" line will say "OK". 191If its not working as expected then you might see output like this instead: 192 193 SSL handshake has read 4584 bytes and written 403 bytes 194 Verification error: unable to get local issuer certificate 195 196The "unable to get local issuer certificate" error means that OpenSSL has been 197unable to find a trusted CA for the chain of certificates provided by the server 198in its trusted certificate store. Check your trusted certificate store 199configuration again. 200 201Note that s_client is a testing tool and will still allow you to connect to the 202TLS server regardless of the verification error. Most applications should not do 203this and should abort the connection in the event of a verification error. 204 205=head1 IMPORTANT OBJECTS FOR AN OPENSSL TLS APPLICATION 206 207A TLS connection is represented by the B<SSL> object in an OpenSSL based 208application. Once a connection with a remote peer has been established an 209endpoint can "write" data to the B<SSL> object to send data to the peer, or 210"read" data from it to receive data from the server. 211 212A new B<SSL> object is created from an B<SSL_CTX> object. Think of an B<SSL_CTX> 213as a "factory" for creating B<SSL> objects. You can create a single B<SSL_CTX> 214object and then create multiple connections (i.e. B<SSL> objects) from it. 215Typically you can set up common configuration options on the B<SSL_CTX> so that 216all the B<SSL> object created from it inherit the same configuration options. 217 218Note that internally to OpenSSL various items that are shared between multiple 219B<SSL> objects are cached in the B<SSL_CTX> for performance reasons. Therefore 220it is considered best practice to create one B<SSL_CTX> for use by multiple 221B<SSL> objects instead of having one B<SSL_CTX> for each B<SSL> object that you 222create. 223 224Each B<SSL> object is also associated with two B<BIO> objects. A B<BIO> object 225is used for sending or receiving data from the underlying transport layer. For 226example you might create a B<BIO> to represent a TCP socket. The B<SSL> object 227uses one B<BIO> for reading data and one B<BIO> for writing data. In most cases 228you would use the same B<BIO> for each direction but there could be some 229circumstances where you want them to be different. 230 231It is up to the application programmer to create the B<BIO> objects that are 232needed and supply them to the B<SSL> object. See 233L<ossl-guide-tls-client-block(7)> and L<ossl-guide-tls-server-block(7)> for 234usage examples. 235 236Finally, an endpoint can establish a "session" with its peer. The session holds 237various TLS parameters about the connection between the client and the server. 238The session details can then be reused in a subsequent connection attempt to 239speed up the process of connecting. This is known as "resumption". Sessions are 240represented in OpenSSL by the B<SSL_SESSION> object. In TLSv1.2 there is always 241exactly one session per connection. In TLSv1.3 there can be any number per 242connection including none. 243 244=head1 PHASES OF A TLS CONNECTION 245 246A TLS connection starts with an initial "set up" phase. The endpoint creates the 247B<SSL_CTX> (if one has not already been created) and configures it. 248 249A client then creates an B<SSL> object to represent the new TLS connection. Any 250connection specific configuration parameters are then applied and the underlying 251socket is created and associated with the B<SSL> via B<BIO> objects. 252 253A server will create a socket for listening for incoming connection attempts 254from clients. Once a connection attempt is made the server will create an B<SSL> 255object in the same way as for a client and associate it with a B<BIO> for the 256newly created incoming socket. 257 258After set up is complete the TLS "handshake" phase begins. A TLS handshake 259consists of the client and server exchanging a series of TLS handshake messages 260to establish the connection. The client starts by sending a "ClientHello" 261handshake message and the server responds with a "ServerHello". The handshake is 262complete once an endpoint has sent its last message (known as the "Finished" 263message) and received a Finished message from its peer. Note that this might 264occur at slightly different times for each peer. For example in TLSv1.3 the 265server always sends its Finished message before the client. The client later 266responds with its Finished message. At this point the client has completed the 267handshake because it has both sent and received a Finished message. The server 268has sent its Finished message but the Finished message from the client may still 269be in-flight, so the server is still in the handshake phase. It is even possible 270that the server will fail to complete the handshake (if it considers there is 271some problem with the messages sent from the client), even though the client may 272have already progressed to sending application data. In TLSv1.2 this can happen 273the other way around, i.e. the server finishes first and the client finishes 274second. 275 276Once the handshake is complete the application data transfer phase begins. 277Strictly speaking there are some situations where the client can start sending 278application data even earlier (using the TLSv1.3 "early data" capability) - but 279we're going to skip over that for this basic introduction. 280 281During application data transfer the client and server can read and write data 282to the connection freely. The details of this are typically left to some higher 283level application protocol (for example HTTP). Not all information exchanged 284during this phase is application data. Some protocol level messages may still 285be exchanged - so it is not necessarily the case that, just because the 286underlying socket is "readable", that application data will be available to read. 287 288When the connection is no longer required then it should be shutdown. A shutdown 289may be initiated by either the client or the server via a message known as a 290"close_notify" alert. The client or server that receives a close_notify may 291respond with one and then the connection is fully closed and application data 292can no longer be sent or received. 293 294Once shutdown is complete a TLS application must clean up by freeing the SSL 295object. 296 297=head1 FURTHER READING 298 299See L<ossl-guide-tls-client-block(7)> for an example of how to apply these 300concepts in order to write a simple TLS client based on a blocking socket. 301See L<ossl-guide-tls-server-block(7)> for an example of how to apply these 302concepts in order to write a simple TLS server handling one client at a time 303over a blocking socket. 304See L<ossl-guide-quic-introduction(7)> for an introduction to QUIC in OpenSSL. 305 306=head1 SEE ALSO 307 308L<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>, 309L<ossl-guide-libssl-introduction(7)>, L<ossl-guide-tls-client-block(7)>, 310L<ossl-guide-tls-server-block(7)>, L<ossl-guide-quic-introduction(7)> 311 312=head1 COPYRIGHT 313 314Copyright 2023-2024 The OpenSSL Project Authors. All Rights Reserved. 315 316Licensed under the Apache License 2.0 (the "License"). You may not use 317this file except in compliance with the License. You can obtain a copy 318in the file LICENSE in the source distribution or at 319L<https://www.openssl.org/source/license.html>. 320 321=cut 322
