mirror of https://github.com/openssl/openssl
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)
This commit is contained in:
Matt Caswell
Tomas Mraz
parent
d5b7d0a6a2
commit
2c2ba73b7a
|
|
@ -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
|
||||
116
doc/man7/ssl.pod
116
doc/man7/ssl.pod
|
|
@ -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
|
||||
Loading…
Reference in New Issue