PcapPlusPlus  21.05
SSLLayer.h File Reference
#include "PointerVector.h"
#include "Layer.h"
#include "SSLCommon.h"
#include "SSLHandshake.h"

Go to the source code of this file.


class  pcpp::SSLLayer
class  pcpp::SSLHandshakeLayer
class  pcpp::SSLChangeCipherSpecLayer
class  pcpp::SSLAlertLayer
class  pcpp::SSLApplicationDataLayer


 The main namespace for the PcapPlusPlus lib.

Detailed Description

This file as well as SSLCommon.h and SSLHandshake.h provide structures that represent SSL/TLS protocol. Main features:

  • All common SSL/TLS version are supported from SSL 3.0 to TLS 1.3
  • All SSL/TLS message types are supported (at least the message types that are not encrypted)
  • More than 300 cipher-suites are supported
  • Only parsing capabilities exist, editing and creation of messages are not supported
  • X509 certificate parsing is not supported

SSL Records:

The SSL/TLS protocol has 4 types of records:

  • Handshake record type
  • Change cipher spec record type
  • Alert record type
  • Application data record type

Each record type corresponds to a layer class, and these classes inherit from one base class which is pcpp::SSLLayer. The pcpp::SSLLayer is an abstract class which cannot be instantiated. Only its 4 derived classes can be instantiated. This means you'll never see a layer of type pcpp::SSLLayer, you'll only see the type of the derived classes. A basic class diagram looks like this:

                            +---|     SSLHandshakeLayer      | ===> Handshake record type
                            |   +----------------------------+
                            |   +----------------------------+
                            +---|  SSLChangeCipherSpecLayer  | ===> Change cipher spec record type
                            |   +----------------------------+
 +------------+             |   +----------------------------+
 |  SSLLayer  |-------------+---|      SSLAlertLayer         | ===> Alert record type
 | (abstract) |             |   +----------------------------+
 +------------+             |
                            |   +----------------------------+
                            +---|   SSLApplicationDataLayer  | ===> Application data record type

A single packet may include several SSL/TLS records, meaning several layer instances of these types, for example:

           |          EthLayer        |
           |          IPv4Layer       |
           |          TcpLayer        |
           |    SSLHandshakeLayer     | \
           +--------------------------+  \
           | SSLChangeCipherSpecLayer | -------- 3 SSL/TLS records in the same packet!
           +--------------------------+  /
           |    SSLHandshakeLayer     | /

SSL/TLS Handshake records:

The SSL/TLS handshake records are the most complex ones. These type of records encapsulate all messages between client and server during SSL/TLS connection establishment. To accomplish that a SSL/TLS handshake record holds zero or more handshake messages (usually it holds 1 message). These messages form the handshake negotiation between the client and the server. There are several types of handshake messages. Some of the are sent from client to server and some from server to client. PcapPlusPlus supports 11 of these types (definitely the most common ones). For each message there is a designated class which parses the message and exposes its attributes in an easy-to-use manner. Here are the list of supported messages:

  • Client-hello
  • Server-hello
  • Certificate
  • Hello-request
  • Server-key-exchange
  • Client-key-exchange
  • Certificate-request
  • Server-hello-done
  • Certificate-verify
  • Finished
  • New-session-ticket

All handshake messages classes inherit from a base abstract class: pcpp::SSLHandshakeMessage which cannot be instantiated. Also, all of them reside in SSLHandshake.h. Following is a simple diagram of these classes:

+-------------------------------+           |--- SSLClientHelloMessage        ==> Client-hello message
|       SSLHandshakeLayer       |           |
+-------------------------------+           |--- SSLServerHelloMessage        ==> Server-hello message
| -List of SSLHandshakeMessage  |           |
|     Message1                  |           |---SSLCertificateMessage         ==> Certificate message
|     Message2                  |           |
|     ...                       |           |---SSLHelloRequestMessage        ==> Hello-request message
|                               |           |
+-------------------------------+           |---SSLServerKeyExchangeMessage   ==> Server-key-exchange message
                                            |---SSLClientKeyExchangeMessage   ==> Client-key-exchange message
                                            |---SSLCertificateRequestMessage  ==> Certificate-request message
                                            |---SSLServerHelloDoneMessage     ==> Server-hello-done message
                                            |---SSLCertificateVerifyMessage   ==> Certificate-verify message
                                            |---SSLFinishedMessage            ==> Finished message
                                            |---SSLNewSessionTicketMessage    ==> New-session-ticket message

In addition, for all handshake messages which aren't supported in PcapPlusPlus or for encrypted handshake messages There is another class: pcpp::SSLUnknownMessage

Cipher suites:

Cipher suites are named combinations of authentication, encryption, message authentication code (MAC) and key exchange algorithms used to negotiate the security settings for a network connection using SSL/TLS. There are many known cipher-suites. PcapPlusPlus support above 300 of them, according to this list: http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml There is a designated class in PcapPlusPlus called pcpp::SSLCipherSuite which represents the cipher-suites and provides access to their attributes. Then there is a static instance of this class for each one of the supported cipher-suites. This means there are 300+ static instances of pcpp::SSLCipherSuite representing the different cipher suites. The user can access them through static methods in pcpp::SSLCipherSuite or from client-hello and server-hello messages where they appear

SSL/TLS extensions:

SSL/TLS handshake messages, specifically client-hello and server-hello usually include extensions. There are various types of extensions - some are more broadly used, some are less. In PcapPlusPlus there is a base class for all extensions: pcpp::SSLExtension. This class is instantiable and represents a generic extension, which means extension data isn't parsed and given to the user as raw data. Currently there are only two extension that are fully parsed which are server-name-indication (pcpp::SSLServerNameIndicationExtension) and SupportedVersions (pcpp::SSLSupportedVersionsExtension). Both inherit from pcpp::SSLExtension and add additional parsing relevant for the specific extension. All other extensions aren't parsed and are represented by instance of pcpp::SSLExtension. Access to extensions is done through the handshake messages classes, specifically pcpp::SSLClientHelloMessage and pcpp::SSLServerHelloMessage