scapy.layers.tls.handshake

TLS handshake fields & logic.

This module covers the handshake TLS subprotocol, except for the key exchange mechanisms which are addressed with keyexchange.py.

class scapy.layers.tls.handshake.SupDataEntry

Bases: scapy.packet.Packet

aliastypes
fields_desc
SupDataEntry fields

sdtype

ShortField

None

len

FieldLenField

None

data

StrLenField

b''

guess_payload_class(p)
class scapy.layers.tls.handshake.SupDataEntryUM

Bases: scapy.packet.Packet

aliastypes
fields_desc
SupDataEntryUM fields

sdtype

ShortField

None

len

FieldLenField

None

dlen

FieldLenField

None

data

PacketListField

[]

guess_payload_class(p)
class scapy.layers.tls.handshake.TLS13Certificate(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLS13Certificate fields

msgtype

ByteEnumField

11

msglen

ThreeBytesField

None

cert_req_ctxt_len

FieldLenField

None

cert_req_ctxt

StrLenField

b''

certslen

_ASN1CertLenField

None

certs

_ASN1CertAndExtListField

[]

post_dissection_tls_session_update(msg_str)
class scapy.layers.tls.handshake.TLS13CertificateRequest(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLS13CertificateRequest fields

msgtype

ByteEnumField

13

msglen

ThreeBytesField

None

cert_req_ctxt_len

FieldLenField

None

cert_req_ctxt

StrLenField

b''

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

class scapy.layers.tls.handshake.TLS13ClientHello(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

TLS 1.3 ClientHello, with abilities to handle extensions.

The Random structure is 32 random bytes without any GMT time

aliastypes
fields_desc
TLS13ClientHello fields

msgtype

ByteEnumField

1

msglen

ThreeBytesField

None

version

_TLSClientVersionField

None

random_bytes

_TLSRandomBytesField

None

sidlen

FieldLenField

None

sid

_SessionIDField

b''

cipherslen

FieldLenField

None

ciphers

_CipherSuitesField

None

complen

FieldLenField

None

comp

_CompressionMethodsField

[0]

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

post_build(p, pay)
tls_session_update(msg_str)

Either for parsing or building, we store the client_random along with the raw string representing this handshake message.

class scapy.layers.tls.handshake.TLS13EndOfEarlyData(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLS13EndOfEarlyData fields

msgtype

ByteEnumField

5

msglen

ThreeBytesField

None

class scapy.layers.tls.handshake.TLS13HelloRetryRequest(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLS13HelloRetryRequest fields

msgtype

ByteEnumField

2

msglen

ThreeBytesField

None

version

_TLSVersionField

771

random_bytes

_TLSRandomBytesField

None

sidlen

FieldLenField

None

sid

_SessionIDField

b''

cipher

EnumField

None

comp

_CompressionMethodsField

[0]

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

class scapy.layers.tls.handshake.TLS13KeyUpdate(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLS13KeyUpdate fields

msgtype

ByteEnumField

24

msglen

ThreeBytesField

None

request_update

ByteEnumField

0

class scapy.layers.tls.handshake.TLS13NewSessionTicket(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

Uncomment the TicketField line for parsing a RFC 5077 ticket.

aliastypes
fields_desc
TLS13NewSessionTicket fields

msgtype

ByteEnumField

4

msglen

ThreeBytesField

None

ticket_lifetime

IntField

4294967295

ticket_age_add

IntField

0

noncelen

FieldLenField

None

ticket_nonce

StrLenField

b''

ticketlen

FieldLenField

None

ticket

StrLenField

b''

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

post_dissection_tls_session_update(msg_str)
class scapy.layers.tls.handshake.TLS13ServerHello(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

TLS 1.3 ServerHello

aliastypes
fields_desc
TLS13ServerHello fields

msgtype

ByteEnumField

2

msglen

ThreeBytesField

None

version

_TLSVersionField

771

random_bytes

_TLSRandomBytesField

None

sidlen

FieldLenField

None

sid

_SessionIDField

b''

cipher

EnumField

None

comp

_CompressionMethodsField

[0]

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

post_build(p, pay)
tls_session_update(msg_str)

Either for parsing or building, we store the server_random along with the raw string representing this handshake message. We also store the cipher suite (if recognized), and finally we instantiate the write and read connection states.

class scapy.layers.tls.handshake.TLSCertificate(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

XXX We do not support RFC 5081, i.e. OpenPGP certificates.

aliastypes
classmethod dispatch_hook(_pkt=None, *args, **kargs)
fields_desc
TLSCertificate fields

msgtype

ByteEnumField

11

msglen

ThreeBytesField

None

certslen

_ASN1CertLenField

None

certs

_ASN1CertListField

[]

post_dissection_tls_session_update(msg_str)
class scapy.layers.tls.handshake.TLSCertificateRequest(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLSCertificateRequest fields

msgtype

ByteEnumField

13

msglen

ThreeBytesField

None

ctypeslen

FieldLenField

None

ctypes

_CertTypesField

[1, 64]

sig_algs_len

SigAndHashAlgsLenField

None

sig_algs

SigAndHashAlgsField

[1027, 1025, 513]

certauthlen

FieldLenField

None

certauth

_CertAuthoritiesField

[]

class scapy.layers.tls.handshake.TLSCertificateStatus(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLSCertificateStatus fields

msgtype

ByteEnumField

22

msglen

ThreeBytesField

None

status_type

ByteEnumField

1

responselen

ThreeBytesLenField

None

response

_StatusField

None

class scapy.layers.tls.handshake.TLSCertificateURL(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

Defined in RFC 4366. PkiPath structure of section 8 is not implemented yet.

aliastypes
fields_desc
TLSCertificateURL fields

msgtype

ByteEnumField

21

msglen

ThreeBytesField

None

certchaintype

ByteEnumField

None

uahlen

FieldLenField

None

uah

PacketListField

[]

class scapy.layers.tls.handshake.TLSCertificateVerify(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
build(*args, **kargs)
fields_desc
TLSCertificateVerify fields

msgtype

ByteEnumField

15

msglen

ThreeBytesField

None

sig

_TLSSignatureField

None

post_dissection(pkt)
class scapy.layers.tls.handshake.TLSClientHello(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

TLS ClientHello, with abilities to handle extensions.

The Random structure follows the RFC 5246: while it is 32-byte long, many implementations use the first 4 bytes as a gmt_unix_time, and then the remaining 28 byts should be completely random. This was designed in order to (sort of) mitigate broken RNGs. If you prefer to show the full 32 random bytes without any GMT time, just comment in/out the lines below.

aliastypes
fields_desc
TLSClientHello fields

msgtype

ByteEnumField

1

msglen

ThreeBytesField

None

version

_TLSClientVersionField

None

gmt_unix_time

_GMTUnixTimeField

None

random_bytes

_TLSRandomBytesField

None

sidlen

FieldLenField

None

sid

_SessionIDField

b''

cipherslen

FieldLenField

None

ciphers

_CipherSuitesField

None

complen

FieldLenField

None

comp

_CompressionMethodsField

[0]

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

post_build(p, pay)
tls_session_update(msg_str)

Either for parsing or building, we store the client_random along with the raw string representing this handshake message.

class scapy.layers.tls.handshake.TLSClientKeyExchange(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

This class mostly works like TLSServerKeyExchange and its ‘params’ field.

aliastypes
build(*args, **kargs)
fields_desc
TLSClientKeyExchange fields

msgtype

ByteEnumField

16

msglen

ThreeBytesField

None

exchkeys

_TLSCKExchKeysField

None

class scapy.layers.tls.handshake.TLSEncryptedExtensions(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLSEncryptedExtensions fields

msgtype

ByteEnumField

8

msglen

ThreeBytesField

None

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

post_build_tls_session_update(msg_str)
post_dissection_tls_session_update(msg_str)
class scapy.layers.tls.handshake.TLSFinished(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
build(*args, **kargs)
fields_desc
TLSFinished fields

msgtype

ByteEnumField

20

msglen

ThreeBytesField

None

vdata

_VerifyDataField

None

post_build_tls_session_update(msg_str)
post_dissection(pkt)
post_dissection_tls_session_update(msg_str)
class scapy.layers.tls.handshake.TLSHelloRequest(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLSHelloRequest fields

msgtype

ByteEnumField

0

msglen

ThreeBytesField

None

tls_session_update(msg_str)

Message should not be added to the list of handshake messages that will be hashed in the finished and certificate verify messages.

class scapy.layers.tls.handshake.TLSHelloVerifyRequest(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

Defined for DTLS, see RFC 6347.

aliastypes
fields_desc
TLSHelloVerifyRequest fields

msgtype

ByteEnumField

21

msglen

ThreeBytesField

None

cookielen

FieldLenField

None

cookie

StrLenField

b''

class scapy.layers.tls.handshake.TLSNewSessionTicket(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

XXX When knowing the right secret, we should be able to read the ticket.

aliastypes
classmethod dispatch_hook(_pkt=None, *args, **kargs)
fields_desc
TLSNewSessionTicket fields

msgtype

ByteEnumField

4

msglen

ThreeBytesField

None

lifetime

IntField

4294967295

ticketlen

FieldLenField

None

ticket

StrLenField

b''

post_dissection_tls_session_update(msg_str)
class scapy.layers.tls.handshake.TLSServerHello(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

TLS ServerHello, with abilities to handle extensions.

The Random structure follows the RFC 5246: while it is 32-byte long, many implementations use the first 4 bytes as a gmt_unix_time, and then the remaining 28 byts should be completely random. This was designed in order to (sort of) mitigate broken RNGs. If you prefer to show the full 32 random bytes without any GMT time, just comment in/out the lines below.

aliastypes
classmethod dispatch_hook(_pkt=None, *args, **kargs)
fields_desc
TLSServerHello fields

msgtype

ByteEnumField

2

msglen

ThreeBytesField

None

version

_TLSVersionField

None

gmt_unix_time

_GMTUnixTimeField

None

random_bytes

_TLSRandomBytesField

None

sidlen

FieldLenField

None

sid

_SessionIDField

b''

cipher

EnumField

None

comp

_CompressionMethodsField

[0]

extlen

_ExtensionsLenField

None

ext

_ExtensionsField

None

post_build(p, pay)
tls_session_update(msg_str)

Either for parsing or building, we store the server_random along with the raw string representing this handshake message. We also store the session_id, the cipher suite (if recognized), the compression method, and finally we instantiate the pending write and read connection states. Usually they get updated later on in the negotiation when we learn the session keys, and eventually they are committed once a ChangeCipherSpec has been sent/received.

class scapy.layers.tls.handshake.TLSServerHelloDone(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLSServerHelloDone fields

msgtype

ByteEnumField

14

msglen

ThreeBytesField

None

class scapy.layers.tls.handshake.TLSServerKeyExchange(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
build(*args, **kargs)

We overload build() method in order to provide a valid default value for params based on TLS session if not provided. This cannot be done by overriding i2m() because the method is called on a copy of the packet.

The ‘params’ field is built according to key_exchange.server_kx_msg_cls which should have been set after receiving a cipher suite in a previous ServerHello. Usual cases are:

  • None: for RSA encryption or fixed FF/ECDH. This should never happen, as no ServerKeyExchange should be generated in the first place.

  • ServerDHParams: for ephemeral FFDH. In that case, the parameter to server_kx_msg_cls does not matter.

  • ServerECDH*Params: for ephemeral ECDH. There are actually three classes, which are dispatched by _tls_server_ecdh_cls_guess on the first byte retrieved. The default here is b”03”, which corresponds to ServerECDHNamedCurveParams (implicit curves).

When the Server*DHParams are built via .fill_missing(), the session server_kx_privkey will be updated accordingly.

fields_desc
TLSServerKeyExchange fields

msgtype

ByteEnumField

12

msglen

ThreeBytesField

None

params

_TLSServerParamsField

None

sig

_TLSSignatureField

None

post_dissection(pkt)

While previously dissecting Server*DHParams, the session server_kx_pubkey should have been updated.

XXX Add a ‘fixed_dh’ OR condition to the ‘anonymous’ test.

class scapy.layers.tls.handshake.TLSSupplementalData(_pkt='', post_transform=None, _internal=0, _underlayer=None, tls_session=None, **fields)

Bases: scapy.layers.tls.handshake._TLSHandshake

aliastypes
fields_desc
TLSSupplementalData fields

msgtype

ByteEnumField

23

msglen

ThreeBytesField

None

sdatalen

ThreeBytesLenField

None

sdata

PacketListField

[]

class scapy.layers.tls.handshake.ThreeBytesLenField(name, default, length_of=None, adjust=<function ThreeBytesLenField.<lambda>>)

Bases: scapy.fields.FieldLenField

addfield(pkt, s, val)
getfield(pkt, s)
i2repr(pkt, x)
class scapy.layers.tls.handshake.URLAndOptionalHash

Bases: scapy.packet.Packet

aliastypes
fields_desc
URLAndOptionalHash fields

urllen

FieldLenField

None

url

StrLenField

b''

hash_present

FieldLenField

None

hash

StrLenField

b''

guess_payload_class(p)
class scapy.layers.tls.handshake.UserMappingData

Bases: scapy.packet.Packet

aliastypes
fields_desc
UserMappingData fields

version

ByteField

None

len

FieldLenField

None

data

StrLenField

b''

guess_payload_class(p)