Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-tls-introduction.7ssl

raw
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>.