1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre Proncheryossl-guide-libssl-introduction, ssl 6*e7be843bSPierre Pronchery- OpenSSL Guide: An introduction to libssl 7*e7be843bSPierre Pronchery 8*e7be843bSPierre Pronchery=head1 INTRODUCTION 9*e7be843bSPierre Pronchery 10*e7be843bSPierre ProncheryThe OpenSSL C<libssl> library provides implementations of several secure network 11*e7be843bSPierre Proncherycommunications protocols. Specifically it provides SSL/TLS (SSLv3, TLSv1, 12*e7be843bSPierre ProncheryTLSv1.1, TLSv1.2 and TLSv1.3), DTLS (DTLSv1 and DTLSv1.2) and QUIC (client side 13*e7be843bSPierre Proncheryonly). The library depends on C<libcrypto> for its underlying cryptographic 14*e7be843bSPierre Proncheryoperations (see L<ossl-guide-libcrypto-introduction(7)>). 15*e7be843bSPierre Pronchery 16*e7be843bSPierre ProncheryThe set of APIs supplied by C<libssl> is common across all of these different 17*e7be843bSPierre Proncherynetwork protocols, so a developer familiar with writing applications using one 18*e7be843bSPierre Proncheryof these protocols should be able to transition to using another with relative 19*e7be843bSPierre Proncheryease. 20*e7be843bSPierre Pronchery 21*e7be843bSPierre ProncheryAn application written to use C<libssl> will include the F<< <openssl/ssl.h> >> 22*e7be843bSPierre Proncheryheader file and will typically use two main data structures, i.e. B<SSL> and 23*e7be843bSPierre ProncheryB<SSL_CTX>. 24*e7be843bSPierre Pronchery 25*e7be843bSPierre ProncheryAn B<SSL> object is used to represent a connection to a remote peer. Once a 26*e7be843bSPierre Proncheryconnection with a remote peer has been established data can be exchanged with 27*e7be843bSPierre Proncherythat peer. 28*e7be843bSPierre Pronchery 29*e7be843bSPierre ProncheryWhen using DTLS any data that is exchanged uses "datagram" semantics, i.e. 30*e7be843bSPierre Proncherythe packets of data can be delivered in any order, and they are not guaranteed 31*e7be843bSPierre Proncheryto arrive at all. In this case the B<SSL> object used for the connection is also 32*e7be843bSPierre Proncheryused for exchanging data with the peer. 33*e7be843bSPierre Pronchery 34*e7be843bSPierre ProncheryBoth TLS and QUIC support the concept of a "stream" of data. Data sent via a 35*e7be843bSPierre Proncherystream is guaranteed to be delivered in order without any data loss. A stream 36*e7be843bSPierre Proncherycan be uni- or bi-directional. 37*e7be843bSPierre Pronchery 38*e7be843bSPierre ProncherySSL/TLS only supports one stream of data per connection and it is always 39*e7be843bSPierre Proncherybi-directional. In this case the B<SSL> object used for the connection also 40*e7be843bSPierre Proncheryrepresents that stream. See L<ossl-guide-tls-introduction(7)> for more 41*e7be843bSPierre Proncheryinformation. 42*e7be843bSPierre Pronchery 43*e7be843bSPierre ProncheryThe QUIC protocol can support multiple streams per connection and they can be 44*e7be843bSPierre Proncheryuni- or bi-directional. In this case an B<SSL> object can represent the 45*e7be843bSPierre Proncheryunderlying connection, or a stream, or both. Where multiple streams are in use 46*e7be843bSPierre Proncherya separate B<SSL> object is used for each one. See 47*e7be843bSPierre ProncheryL<ossl-guide-quic-introduction(7)> for more information. 48*e7be843bSPierre Pronchery 49*e7be843bSPierre ProncheryAn B<SSL_CTX> object is used to create the B<SSL> object for the underlying 50*e7be843bSPierre Proncheryconnection. A single B<SSL_CTX> object can be used to create many connections 51*e7be843bSPierre Pronchery(each represented by a separate B<SSL> object). Many API functions in libssl 52*e7be843bSPierre Proncheryexist in two forms: one that takes an B<SSL_CTX> and one that takes an B<SSL>. 53*e7be843bSPierre ProncheryTypically settings that you apply to the B<SSL_CTX> will then be inherited by 54*e7be843bSPierre Proncheryany B<SSL> object that you create from it. Alternatively you can apply settings 55*e7be843bSPierre Proncherydirectly to the B<SSL> object without affecting other B<SSL> objects. Note that 56*e7be843bSPierre Proncheryyou should not normally make changes to an B<SSL_CTX> after the first B<SSL> 57*e7be843bSPierre Proncheryobject has been created from it. 58*e7be843bSPierre Pronchery 59*e7be843bSPierre Pronchery=head1 DATA STRUCTURES 60*e7be843bSPierre Pronchery 61*e7be843bSPierre ProncheryAs well as B<SSL_CTX> and B<SSL> there are a number of other data structures 62*e7be843bSPierre Proncherythat an application may need to use. They are summarised below. 63*e7be843bSPierre Pronchery 64*e7be843bSPierre Pronchery=over 4 65*e7be843bSPierre Pronchery 66*e7be843bSPierre Pronchery=item B<SSL_METHOD> (SSL Method) 67*e7be843bSPierre Pronchery 68*e7be843bSPierre ProncheryThis structure is used to indicate the kind of connection you want to make, e.g. 69*e7be843bSPierre Proncherywhether it is to represent the client or the server, and whether it is to use 70*e7be843bSPierre ProncherySSL/TLS, DTLS or QUIC. It is passed as a parameter when creating 71*e7be843bSPierre Proncherythe B<SSL_CTX>. 72*e7be843bSPierre Pronchery 73*e7be843bSPierre Pronchery=item B<SSL_SESSION> (SSL Session) 74*e7be843bSPierre Pronchery 75*e7be843bSPierre ProncheryAfter establishing a connection with a peer the agreed cryptographic material 76*e7be843bSPierre Proncherycan be reused to create future connections with the same peer more rapidly. The 77*e7be843bSPierre Proncheryset of data used for such a future connection establishment attempt is collected 78*e7be843bSPierre Proncherytogether into an B<SSL_SESSION> object. A single successful connection with a 79*e7be843bSPierre Proncherypeer may generate zero or more such B<SSL_SESSION> objects for use in future 80*e7be843bSPierre Proncheryconnection attempts. 81*e7be843bSPierre Pronchery 82*e7be843bSPierre Pronchery=item B<SSL_CIPHER> (SSL Cipher) 83*e7be843bSPierre Pronchery 84*e7be843bSPierre ProncheryDuring connection establishment the client and server agree upon cryptographic 85*e7be843bSPierre Proncheryalgorithms they are going to use for encryption and other uses. A single set 86*e7be843bSPierre Proncheryof cryptographic algorithms that are to be used together is known as a 87*e7be843bSPierre Proncheryciphersuite. Such a set is represented by an B<SSL_CIPHER> object. 88*e7be843bSPierre Pronchery 89*e7be843bSPierre ProncheryThe set of available ciphersuites that can be used are configured in the 90*e7be843bSPierre ProncheryB<SSL_CTX> or B<SSL>. 91*e7be843bSPierre Pronchery 92*e7be843bSPierre Pronchery=back 93*e7be843bSPierre Pronchery 94*e7be843bSPierre Pronchery=head1 FURTHER READING 95*e7be843bSPierre Pronchery 96*e7be843bSPierre ProncherySee L<ossl-guide-tls-introduction(7)> for an introduction to the SSL/TLS 97*e7be843bSPierre Proncheryprotocol and L<ossl-guide-quic-introduction(7)> for an introduction to QUIC. 98*e7be843bSPierre Pronchery 99*e7be843bSPierre ProncherySee L<ossl-guide-libcrypto-introduction(7)> for an introduction to C<libcrypto>. 100*e7be843bSPierre Pronchery 101*e7be843bSPierre Pronchery=head1 SEE ALSO 102*e7be843bSPierre Pronchery 103*e7be843bSPierre ProncheryL<ossl-guide-libcrypto-introduction(7)>, L<ossl-guide-tls-introduction(7)>, 104*e7be843bSPierre ProncheryL<ossl-guide-quic-introduction(7)> 105*e7be843bSPierre Pronchery 106*e7be843bSPierre Pronchery=head1 COPYRIGHT 107*e7be843bSPierre Pronchery 108*e7be843bSPierre ProncheryCopyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved. 109*e7be843bSPierre Pronchery 110*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 111*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 112*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 113*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 114*e7be843bSPierre Pronchery 115*e7be843bSPierre Pronchery=cut 116