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