diff options
author | Matt Caswell <matt@openssl.org> | 2023-07-14 16:29:39 +0100 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2023-08-08 18:42:41 +0200 |
commit | 2c2ba73b7aa64859f1a6e68ccae781c19a1ef29f (patch) | |
tree | 7b2ce679e2edd5517f9f2c43cab3e460f61a18df | |
parent | d5b7d0a6a2c7263c4bc22a9403e05bc80d324f9a (diff) |
Incorporate the ssl man page into the OpenSSL guide
We also rewrite quite a lot of the content to update it for QUIC and to make
it flow better as part of the guide.
Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Anton Arapov <anton@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21560)
-rw-r--r-- | doc/man7/ossl-guide-libssl-introduction.pod | 115 | ||||
-rw-r--r-- | doc/man7/ssl.pod | 116 |
2 files changed, 115 insertions, 116 deletions
diff --git a/doc/man7/ossl-guide-libssl-introduction.pod b/doc/man7/ossl-guide-libssl-introduction.pod new file mode 100644 index 0000000000..3c1a5d7383 --- /dev/null +++ b/doc/man7/ossl-guide-libssl-introduction.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +ossl-guide-libssl-introduction, ssl +- OpenSSL Guide: An introduction to libssl + +=head1 INTRODUCTION + +The OpenSSL C<libssl> library provides implementations of several secure network +communications protocols. Specifically it provides SSL/TLS (SSLv3, TLSv1, +TLSv1.1, TLSv1.2 and TLSv1.3), DTLS (DTLSv1 and DTLSv1.2) and QUIC (client side +only). The library depends on C<libcrypto> for its underlying cryptographic +operations (see L<ossl-guide-libcrypto-introduction(7)>). + +The set of APIs supplied by C<libssl> is common across all of these different +network protocols, so a developer familiar with writing applications using one +of these protocols should be able to transition to using another with relative +ease. + +An application written to use C<libssl> will include the F<< <openssl/ssl.h> >> +header file and will typically use two main data structures, i.e. B<SSL> and +B<SSL_CTX>. + +An B<SSL> object is used to represent a connection to a remote peer. Once a +connection with a remote peer has been established data can be exchanged with +that peer. + +When using DTLS any data that is exchanged uses "datagram" semantics, i.e. +the packets of data can be delivered in any order, and they are not guaranteed +to arrive at all. In this case the B<SSL> object used for the connection is also +used for exchanging data with the peer. + +Both TLS and QUIC support the concept of a "stream" of data. Data sent via a +stream is guaranteed to be delivered in order without any data loss. A stream +can be uni- or bi-directional. + +SSL/TLS only supports one stream of data per connection and it is always +bi-directional. In this case the B<SSL> object used for the connection also +represents that stream. See L<ossl-guide-tls-introduction(7)> for more +information. + +The QUIC protocol can support multiple streams per connection and they can be +uni- or bi-directional. In this case an B<SSL> object can represent the +underlying connection, or a stream, or both. Where multiple streams are in use +a separate B<SSL> object is used for each one. See +L<ossl-guide-quic-introduction(7)> for more information. + +An B<SSL_CTX> object is used to create the B<SSL> object for the underlying +connection. A single B<SSL_CTX> object can be used to create many connections +(each represented by a separate B<SSL> object). Many API functions in libssl +exist in two forms: one that takes an B<SSL_CTX> and one that takes an B<SSL>. +Typically settings that you apply to the B<SSL_CTX> will then be inherited by +any B<SSL> object that you create from it. Alternatively you can apply settings +directly to the B<SSL> object without affecting other B<SSL> objects. Note that +you should not normally make changes to an B<SSL_CTX> after the first B<SSL> +object has been created from it. + +=head1 DATA STRUCTURES + +As well as B<SSL_CTX> and B<SSL> there are a number of other data structures +that an application may need to use. They are summarised below. + +=over 4 + +=item B<SSL_METHOD> (SSL Method) + +This structure is used to indicate the kind of connection you want to make, e.g. +whether it is to represent the client or the server, and whether it is to use +SSL/TLS, DTLS or QUIC (client only). It is passed as a parameter when creating +the B<SSL_CTX>. + +=item B<SSL_SESSION> (SSL Session) + +After establishing a connection with a peer the agreed cryptographic material +can be reused to create future connections with the same peer more rapidly. The +set of data used for such a future connection establishment attempt is collected +together into an B<SSL_SESSION> object. A single successful connection with a +peer may generate zero or more such B<SSL_SESSION> objects for use in future +connection attempts. + +=item B<SSL_CIPHER> (SSL Cipher) + +During connection establishment the client and server agree upon cryptographic +algorithms they are going to use for encryption and other uses. A single set +of cryptographic algorithms that are to be used together is known as a +ciphersuite. Such a set is represented by an B<SSL_CIPHER> object. + +The set of available ciphersuites that can be used are configured in the +B<SSL_CTX> or B<SSL>. + +=back + +=head1 FURTHER READING + +See L<ossl-guide-tls-introduction(7)> for an introduction to the SSL/TLS +protocol and L<ossl-guide-quic-introduction(7)> for an introduction to QUIC. + +See L<ossl-guide-libcrypto-introduction(7)> for an introduction to C<libcrypto>. + +=head1 SEE ALSO + +L<ossl-guide-libcrypto-introduction(7)>, L<ossl-guide-tls-introduction(7)>, +L<ossl-guide-quic-introduction(7)> + +=head1 COPYRIGHT + +Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man7/ssl.pod b/doc/man7/ssl.pod deleted file mode 100644 index 7aff45c5cc..0000000000 --- a/doc/man7/ssl.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=head1 NAME - -ssl - OpenSSL SSL/TLS library - -=head1 SYNOPSIS - -See the individual manual pages for details. - -=head1 DESCRIPTION - -The OpenSSL B<ssl> library implements several versions of the -Secure Sockets Layer, Transport Layer Security, and Datagram Transport Layer -Security protocols. -This page gives a brief overview of the extensive API and data types -provided by the library. - -An B<SSL_CTX> object is created as a framework to establish -TLS/SSL enabled connections (see L<SSL_CTX_new(3)>). -Various options regarding certificates, algorithms etc. can be set -in this object. - -When a network connection has been created, it can be assigned to an -B<SSL> object. After the B<SSL> object has been created using -L<SSL_new(3)>, L<SSL_set_fd(3)> or -L<SSL_set_bio(3)> can be used to associate the network -connection with the object. - -When the TLS/SSL handshake is performed using -L<SSL_accept(3)> or L<SSL_connect(3)> -respectively. -L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> and L<SSL_write(3)> are -used to read and write data on the TLS/SSL connection. -L<SSL_shutdown(3)> can be used to shut down the -TLS/SSL connection. - -=head1 DATA STRUCTURES - -Here are some of the main data structures in the library. - -=over 4 - -=item B<SSL_METHOD> (SSL Method) - -This is a dispatch structure describing the internal B<ssl> library -methods/functions which implement the various protocol versions (SSLv3 -TLSv1, ...). It's needed to create an B<SSL_CTX>. - -=item B<SSL_CIPHER> (SSL Cipher) - -This structure holds the algorithm information for a particular cipher which -are a core part of the SSL/TLS protocol. The available ciphers are configured -on a B<SSL_CTX> basis and the actual ones used are then part of the -B<SSL_SESSION>. - -=item B<SSL_CTX> (SSL Context) - -This is the global context structure which is created by a server or client -once per program life-time and which holds mainly default values for the -B<SSL> structures which are later created for the connections. - -=item B<SSL_SESSION> (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: B<SSL_CIPHER>s, client and server certificates, keys, etc. - -=item B<SSL> (SSL Connection) - -This is the main SSL/TLS structure which is created by a server or client per -established connection. This actually is the core structure in the SSL API. -At run-time the application usually deals with this structure which has -links to mostly all other structures. - -=back - -=head1 HEADER FILES - -Currently the OpenSSL B<ssl> library provides the following C header files -containing the prototypes for the data structures and functions: - -=over 4 - -=item F<< <openssl/ssl.h> >> - -This is the common header file for the SSL/TLS API. Include it into your -program to make the API of the B<ssl> library available. It internally -includes both more private SSL headers and headers from the B<crypto> library. -Whenever you need hard-core details on the internals of the SSL API, look -inside this header file. -This file also includes the others listed below. - -=item F<< <openssl/ssl2.h> >> - -Unused. Present for backwards compatibility only. - -=item F<< <openssl/ssl3.h> >> - -This is the sub header file dealing with the SSLv3 protocol only. - -=item F<< <openssl/tls1.h> >> - -This is the sub header file dealing with the TLSv1 protocol only. - -=back - -=head1 COPYRIGHT - -Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L<https://www.openssl.org/source/license.html>. - -=cut |