Class TLS

scapy/layers/tls/record.py:234–751

The generic TLS Record message, based on section 6.2 of RFC 5246. When reading a TLS message, we try to parse as much as we can. In .pre_dissect(), according to the type of the current cipher algorithm (self.tls_session.rcs.cipher.type), we extract the 'iv', 'mac', 'pad' and 'p

class TLS(_GenericTLSSessionInheritance):
    """
    The generic TLS Record message, based on section 6.2 of RFC 5246.

    When reading a TLS message, we try to parse as much as we can.
    In .pre_dissect(), according to the type of the current cipher algorithm
    (self.tls_session.rcs.cipher.type), we extract the 'iv', 'mac', 'pad' and
    'padlen'. Some of these fields may remain blank: for instance, when using
    a stream cipher, there is no IV nor any padding. The 'len' should always
    hold the length of the ciphered message; for the plaintext version, you
    should rely on the additional 'deciphered_len' attribute.

    XXX Fix 'deciphered_len' which should not be defined when failing with
    AEAD decryption. This is related to the 'decryption_success' below.
    Also, follow this behaviour in record_sslv2.py and record_tls13.py

    Once we have isolated the ciphered message aggregate (which should be one
    or several TLS messages of the same type), we try to decipher it. Either we
    succeed and store the clear data in 'msg', or we graciously fail with a
    CipherError and store the ciphered data in 'msg'.

    Unless the user manually provides the session secrets through the passing
    of a 'tls_session', obviously the ciphered messages will not be deciphered.
    Indeed, the need for a proper context may also present itself when trying
    to parse clear handshake messages.

    For instance, suppose you sniffed the beginning of a DHE-RSA negotiation::

        t1 = TLS(<client_hello>)
        t2 = TLS(<server_hello | certificate | server_key_exchange>)
        t3 = TLS(<server_hello | certificate | server_key_exchange>,
                 tls_session=t1.tls_session)

    (Note that to do things properly, here 't1.tls_session' should actually be
    't1.tls_session.mirror()'. See session.py for explanations.)

    As no context was passed to t2, neither was any client_random. Hence Scapy
    will not be able to verify the signature of the server_key_exchange inside
    t2. However, it should be able to do so for t3, thanks to the tls_session.
    The consequence of not having a complete TLS context is even more obvious
    when trying to parse ciphered content, as we described before.

    Thus, in order to parse TLS-protected communications with Scapy:
    _either Scapy reads every message from one side of the TLS connection and
    builds every message from the other side (as such, it should know the
    secrets needed for the generation of the pre_master_secret), while passing
    the same tls_session context (this is how our automaton.py mostly works);
    _or, if Scapy did not build any TLS message, it has to create a TLS context
    and feed it with secrets retrieved by whatever technique. Note that the
    knowing the private key of the server certificate will not be sufficient
    if a PFS ciphersuite was used. However, if you got a master_secret somehow,
    use it with tls_session.(w|r)cs.derive_keys() and leave the rest to Scapy.

    When building a TLS message with raw_stateful, we expect the tls_session to
    have the right parameters for ciphering. Else, .post_build() might fail.
    """
    __slots__ = ["deciphered_len"]
    name = "TLS"