From: Matt Caswell Date: Fri, 14 Jul 2023 15:29:39 +0000 (+0100) Subject: Incorporate the ssl man page into the OpenSSL guide X-Git-Tag: openssl-3.2.0-alpha1~265 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2c2ba73b7aa64859f1a6e68ccae781c19a1ef29f;p=thirdparty%2Fopenssl.git 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 Reviewed-by: Tim Hudson Reviewed-by: Matthias St. Pierre Reviewed-by: Anton Arapov (Merged from https://github.com/openssl/openssl/pull/21560) --- diff --git a/doc/man7/ossl-guide-libssl-introduction.pod b/doc/man7/ossl-guide-libssl-introduction.pod new file mode 100644 index 00000000000..3c1a5d73837 --- /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 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 for its underlying cryptographic +operations (see L). + +The set of APIs supplied by C 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 will include the F<< >> +header file and will typically use two main data structures, i.e. B and +B. + +An B 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 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 object used for the connection also +represents that stream. See L 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 object can represent the +underlying connection, or a stream, or both. Where multiple streams are in use +a separate B object is used for each one. See +L for more information. + +An B object is used to create the B object for the underlying +connection. A single B object can be used to create many connections +(each represented by a separate B object). Many API functions in libssl +exist in two forms: one that takes an B and one that takes an B. +Typically settings that you apply to the B will then be inherited by +any B object that you create from it. Alternatively you can apply settings +directly to the B object without affecting other B objects. Note that +you should not normally make changes to an B after the first B +object has been created from it. + +=head1 DATA STRUCTURES + +As well as B and B 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) + +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. + +=item B (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 object. A single successful connection with a +peer may generate zero or more such B objects for use in future +connection attempts. + +=item B (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 object. + +The set of available ciphersuites that can be used are configured in the +B or B. + +=back + +=head1 FURTHER READING + +See L for an introduction to the SSL/TLS +protocol and L for an introduction to QUIC. + +See L for an introduction to C. + +=head1 SEE ALSO + +L, L, +L + +=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. + +=cut diff --git a/doc/man7/ssl.pod b/doc/man7/ssl.pod deleted file mode 100644 index 7aff45c5ccd..00000000000 --- 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 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 object is created as a framework to establish -TLS/SSL enabled connections (see L). -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 object. After the B object has been created using -L, L or -L can be used to associate the network -connection with the object. - -When the TLS/SSL handshake is performed using -L or L -respectively. -L, L, L and L are -used to read and write data on the TLS/SSL connection. -L 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) - -This is a dispatch structure describing the internal B library -methods/functions which implement the various protocol versions (SSLv3 -TLSv1, ...). It's needed to create an B. - -=item B (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 basis and the actual ones used are then part of the -B. - -=item B (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 structures which are later created for the connections. - -=item B (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: Bs, client and server certificates, keys, etc. - -=item B (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 library provides the following C header files -containing the prototypes for the data structures and functions: - -=over 4 - -=item F<< >> - -This is the common header file for the SSL/TLS API. Include it into your -program to make the API of the B library available. It internally -includes both more private SSL headers and headers from the B 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<< >> - -Unused. Present for backwards compatibility only. - -=item F<< >> - -This is the sub header file dealing with the SSLv3 protocol only. - -=item F<< >> - -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. - -=cut