scapy.layers.tls package

Tools for handling TLS sessions and digital certificates. Use load_layer(‘tls’) to load them to the main namespace.


  • You may need to ‘pip install cryptography’ for the module to be loaded.

Main features:

  • X.509 certificates parsing/building.
  • RSA & ECDSA keys sign/verify methods.
  • TLS records and sublayers (handshake…) parsing/building. Works with versions SSLv2 to TLS 1.2. This may be enhanced by a TLS context. For instance, if Scapy reads a ServerHello with version TLS 1.2 and a cipher suite using AES, it will assume the presence of IVs prepending the data. See test/tls.uts for real examples.
  • TLS encryption/decryption capabilities with many ciphersuites, including some which may be deemed dangerous. Once again, the TLS context enables Scapy to transparently send/receive protected data if it learnt the session secrets. Note that if Scapy acts as one side of the handshake (e.g. reads all server-related packets and builds all client-related packets), it will indeed compute the session secrets.
  • TLS client & server basic automatons, provided for testing and tweaking purposes. These make for a very primitive TLS stack.
  • Additionally, a basic test PKI (key + certificate for a CA, a client and a server) is provided in tls/examples/pki_test.

Unit tests:

  • Various cryptography checks.
  • Reading a TLS handshake between a Firefox client and a GitHub server.
  • Reading TLS 1.3 handshakes from test vectors of a draft RFC.
  • Reading a SSLv2 handshake between s_client and s_server, without PFS.
  • Test our TLS server against s_client with different cipher suites.
  • Test our TLS client against our TLS server (s_server is unscriptable).

TODO list (may it be carved away by good souls):

  • Features to add (or wait for) in the cryptography library:

    • X448 from RFC 7748 (no support in openssl yet);
    • the compressed EC point format.
  • About the automatons:

    • Add resumption support, through session IDs or session tickets.
    • Add various checks for discrepancies between client and server. Is the ServerHello ciphersuite ok? What about the SKE params? Etc.
    • Add some examples which illustrate how the automatons could be used. Typically, we could showcase this with Heartbleed.
    • Allow the server to store both one RSA key and one ECDSA key, and select the right one to use according to the ClientHello suites.
    • Find a way to shutdown the automatons sockets properly without simultaneously breaking the unit tests.
  • Miscellaneous:

    • Enhance PSK and session ticket support.
    • Define several Certificate Transparency objects.
    • Add the extended master secret and encrypt-then-mac logic.
    • Mostly unused features : DSS, fixed DH, SRP, char2 curves…