--- /dev/null
+=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
+++ /dev/null
-=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
projects / openssl.git / commitdiff