scapy.layers.tls.keyexchange

TLS key exchange logic.

class scapy.layers.tls.keyexchange.ClientDiffieHellmanPublic(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

If the user provides a value for dh_Yc attribute, we assume he will set the pms and ms accordingly and trigger the key derivation on his own.

XXX As specified in 7.4.7.2. of RFC 4346, we should distinguish the needs for implicit or explicit value depending on availability of DH parameters in client certificate. For now we can only do ephemeral/explicit DH.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|            DH YCLEN           |             DH YC             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                  Fig. ClientDiffieHellmanPublic                  
ClientDiffieHellmanPublic fields

dh_Yclen

FieldLenField

'None'

dh_Yc

StrLenField

"b''"

fill_missing(**kwargs)
guess_payload_class(p)
post_build(pkt, pay)
post_dissection(m)

First we update the client DHParams. Then, we try to update the server DHParams generated during Server*DHParams building, with the shared secret. Finally, we derive the session keys and update the context.

class scapy.layers.tls.keyexchange.ClientECDiffieHellmanPublic(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

Note that the ‘len’ field is 1 byte longer than with the previous class.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   ECDH YCLEN  |            ECDH YC            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                 Fig. ClientECDiffieHellmanPublic                 
ClientECDiffieHellmanPublic fields

ecdh_Yclen

FieldLenField

'None'

ecdh_Yc

StrLenField

"b''"

fill_missing(**kwargs)
post_build(pkt, pay)
post_dissection(m)
class scapy.layers.tls.keyexchange.ClientPSKIdentity(*args, **kargs)

Bases: scapy.packet.Packet

XXX We provide parsing abilities for ServerPSKParams, but the context operations have not been implemented yet. See RFC 4279. Note that we do not cover the (EC)DHE_PSK nor the RSA_PSK key exchange, which should contain either an EncryptedPMS or a ClientDiffieHellmanPublic.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|        PSK IDENTITY LEN       |          PSK IDENTITY         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                      Fig. ClientPSKIdentity                      
ClientPSKIdentity fields

psk_identity_len

FieldLenField

'None'

psk_identity

StrLenField

"b''"

class scapy.layers.tls.keyexchange.ECCurvePkt(*args, **kargs)

Bases: scapy.packet.Packet

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      ALEN     |               A               |      BLEN     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               B               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                         Fig. ECCurvePkt                          
ECCurvePkt fields

alen

FieldLenField

'None'

a

StrLenField

"b''"

blen

FieldLenField

'None'

b

StrLenField

"b''"

class scapy.layers.tls.keyexchange.ECPentanomialBasis(*args, **kargs)

Bases: scapy.packet.Packet

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     K1LEN     |               K1              |     K2LEN     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               K2              |     K3LEN     |       K3      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               |
+-+-+-+-+-+-+-+-+

                     Fig. ECPentanomialBasis                      
ECPentanomialBasis fields

k1len

FieldLenField

'None'

k1

StrLenField

"b''"

k2len

FieldLenField

'None'

k2

StrLenField

"b''"

k3len

FieldLenField

'None'

k3

StrLenField

"b''"

guess_payload_class(p)
val = 1
class scapy.layers.tls.keyexchange.ECTrinomialBasis(*args, **kargs)

Bases: scapy.packet.Packet

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      KLEN     |               K               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                      Fig. ECTrinomialBasis                       
ECTrinomialBasis fields

klen

FieldLenField

'None'

k

StrLenField

"b''"

guess_payload_class(p)
val = 0
class scapy.layers.tls.keyexchange.EncryptedPreMasterSecret(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

Pay attention to implementation notes in section 7.4.7.1 of RFC 5246.

aliastypes
classmethod dispatch_hook(_pkt=None, *args, **kargs)
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         CLIENT VERSION        |             RANDOM            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                  Fig. EncryptedPreMasterSecret                   
EncryptedPreMasterSecret fields

client_version

_TLSClientVersionField

'None'

random

StrFixedLenField

'None'

guess_payload_class(p)
post_build(pkt, pay)

We encrypt the premaster secret (the 48 bytes) with either the server certificate or the temporary RSA key provided in a server key exchange message. After that step, we add the 2 bytes to provide the length, as described in implementation notes at the end of section 7.4.7.1.

pre_dissect(m)
class scapy.layers.tls.keyexchange.ServerDHParams(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

ServerDHParams for FFDH-based key exchanges, as defined in RFC 5246/7.4.3.

Either with .fill_missing() or .post_dissection(), the server_kx_privkey or server_kx_pubkey of the TLS context are updated according to the parsed/assembled values. It is the user’s responsibility to store and restore the original values if he wants to keep them. For instance, this could be done between the writing of a ServerKeyExchange and the receiving of a ClientKeyExchange (which includes secret generation).

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|            DH PLEN            |              DH P             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|            DH GLEN            |              DH G             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|            DH YSLEN           |             DH YS             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                       Fig. ServerDHParams                        
ServerDHParams fields

dh_plen

FieldLenField

'None'

dh_p

StrLenField

"b''"

dh_glen

FieldLenField

'None'

dh_g

StrLenField

"b''"

dh_Yslen

FieldLenField

'None'

dh_Ys

StrLenField

"b''"

fill_missing(**kwargs)
guess_payload_class(p)

The signature after the params gets saved as Padding. This way, the .getfield() which _TLSServerParamsField inherits from PacketField will return the signature remain as expected.

post_dissection(r)
register_pubkey(**kwargs)
class scapy.layers.tls.keyexchange.ServerECDHExplicitChar2Params(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

We provide parsing abilities for Char2Params, but there is no support from the cryptography library, hence no context operations.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   CURVE TYPE  |               M               |   BASIS TYPE  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             BASIS             |             CURVE             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    BASELEN    |              BASE             |     ORDER     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    COFACTOR   |    POINTLEN   |             POINT             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                Fig. ServerECDHExplicitChar2Params                
ServerECDHExplicitChar2Params fields

curve_type

ByteEnumField

'2'

m

ShortField

'None'

basis_type

_ECBasisTypeField

'None'

basis

_ECBasisField

'<ECTrinomialBasis  |>'

curve

PacketField

'<ECCurvePkt  |>'

baselen

FieldLenField

'None'

base

StrLenField

"b''"

order

ByteField

'None'

cofactor

ByteField

'None'

pointlen

FieldLenField

'None'

point

StrLenField

"b''"

fill_missing()
guess_payload_class(p)
class scapy.layers.tls.keyexchange.ServerECDHExplicitPrimeParams(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

We provide parsing abilities for ExplicitPrimeParams, but there is no support from the cryptography library, hence no context operations.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   CURVE TYPE  |      PLEN     |               P               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             CURVE             |    BASELEN    |      BASE     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               |    ORDERLEN   |             ORDER             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  COFACTORLEN  |            COFACTOR           |    POINTLEN   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             POINT             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                Fig. ServerECDHExplicitPrimeParams                
ServerECDHExplicitPrimeParams fields

curve_type

ByteEnumField

'1'

plen

FieldLenField

'None'

p

StrLenField

"b''"

curve

PacketField

'None'

baselen

FieldLenField

'None'

base

StrLenField

"b''"

orderlen

FieldLenField

'None'

order

StrLenField

"b''"

cofactorlen

FieldLenField

'None'

cofactor

StrLenField

"b''"

pointlen

FieldLenField

'None'

point

StrLenField

"b''"

fill_missing()

Note that if it is not set by the user, the cofactor will always be 1. It is true for most, but not all, TLS elliptic curves.

guess_payload_class(p)
class scapy.layers.tls.keyexchange.ServerECDHNamedCurveParams(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   CURVE TYPE  |          NAMED CURVE          |    POINTLEN   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             POINT             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                 Fig. ServerECDHNamedCurveParams                  
ServerECDHNamedCurveParams fields

curve_type

ByteEnumField

'3'

named_curve

ShortEnumField

'None'

pointlen

FieldLenField

'None'

point

StrLenField

'None'

fill_missing(**kwargs)
guess_payload_class(p)
post_dissection(r)
register_pubkey(**kwargs)
class scapy.layers.tls.keyexchange.ServerPSKParams(*args, **kargs)

Bases: scapy.packet.Packet

XXX We provide some parsing abilities for ServerPSKParams, but the context operations have not been implemented yet. See RFC 4279. Note that we do not cover the (EC)DHE_PSK key exchange, which should contain a Server*DHParams after ‘psk_identity_hint’.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     PSK IDENTITY HINT LEN     |       PSK IDENTITY HINT       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                       Fig. ServerPSKParams                       
ServerPSKParams fields

psk_identity_hint_len

FieldLenField

'None'

psk_identity_hint

StrLenField

"b''"

fill_missing()
guess_payload_class(p)
post_dissection(pkt)
class scapy.layers.tls.keyexchange.ServerRSAParams(*args, **kargs)

Bases: scapy.layers.tls.session._GenericTLSSessionInheritance

Defined for RSA_EXPORT kx : it enables servers to share RSA keys shorter than their principal {>512}-bit key, when it is not allowed for kx.

This should not appear in standard RSA kx negotiation, as the key has already been advertised in the Certificate message.

aliastypes
fields_desc
Display RFC-like schema
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           RSAMODLEN           |             RSAMOD            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           RSAEXPLEN           |             RSAEXP            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                       Fig. ServerRSAParams                       
ServerRSAParams fields

rsamodlen

FieldLenField

'None'

rsamod

StrLenField

"b''"

rsaexplen

FieldLenField

'None'

rsaexp

StrLenField

"b''"

fill_missing(**kwargs)
guess_payload_class(p)
post_dissection(pkt)
register_pubkey(**kwargs)
class scapy.layers.tls.keyexchange.SigAndHashAlgField(*args, **kwds)

Bases: scapy.fields.EnumField

Used in _TLSSignature.

addfield()
getfield()
phantom_value = None
class scapy.layers.tls.keyexchange.SigAndHashAlgsField(*args, **kwds)

Bases: scapy.fields.FieldListField

Used in TLS_Ext_SignatureAlgorithms and TLSCertificateResquest.

addfield()
getfield()
phantom_value = []
class scapy.layers.tls.keyexchange.SigAndHashAlgsLenField(*args, **kwds)

Bases: scapy.fields.FieldLenField

Used in TLS_Ext_SignatureAlgorithms and TLSCertificateResquest.

addfield()
getfield()
phantom_value = 0
class scapy.layers.tls.keyexchange.SigLenField(*args, **kwds)

Bases: scapy.fields.FieldLenField

There is a trick for SSLv2, which uses implicit lengths…

addfield(pkt, s, val)

With SSLv2 you will never be able to add a sig_len.

getfield(pkt, s)
class scapy.layers.tls.keyexchange.SigValField(*args, **kwds)

Bases: scapy.fields.StrLenField

There is a trick for SSLv2, which uses implicit lengths…

getfield(pkt, m)
scapy.layers.tls.keyexchange.phantom_decorate(f, get_or_add)

Decorator for version-dependent fields. If get_or_add is True (means get), we return s, self.phantom_value. If it is False (means add), we return s.

scapy.layers.tls.keyexchange.phantom_mode(pkt)

We expect this. If tls_version is not set, this means we did not process any complete ClientHello, so we’re most probably reading/building a signature_algorithms extension, hence we cannot be in phantom_mode. However, if the tls_version has been set, we test for TLS 1.2.