tlslite.messages module

Classes representing TLS messages.

class tlslite.messages.Alert

Bases: object

__init__()

__repr__()

Return repr(self).

__str__()

Return str(self).

create(description, level=2)

property descriptionName

property levelName

parse(p)

write()

class tlslite.messages.ApplicationData

Bases: object

__init__()

create(bytes)

parse(p)

splitFirstByte()

write()

class tlslite.messages.Certificate(certificateType, version=(3, 2))

Bases: HandshakeMsg

__init__(certificateType, version=(3, 2))

__repr__()

Return repr(self).

property cert_chain

Getter for the cert_chain property.

create(cert_chain, context=b'')

Initialise fields of the class.

parse(p)

write()

class tlslite.messages.CertificateEntry(certificateType)

Bases: object

Object storing a single certificate from TLS 1.3.

Stores a certificate (or possibly a raw public key) together with associated extensions

__init__(certificateType)

Initialise the object for given certificate type.

__repr__()

Return repr(self).

create(certificate, extensions)

Set all values of the certificate entry.

parse(parser)

Deserialise the object from on the wire data.

write()

Serialise the object.

class tlslite.messages.CertificateRequest(version)

Bases: HelloMessage

__init__(version)

Initialize object.

create(certificate_types=None, certificate_authorities=None, sig_algs=None, context=b'', extensions=None)

Creates a Certificate Request message. For TLS 1.3 only the context and extensions parameters should be provided, the others are ignored. For TLS versions below 1.3 instead only the first three parameters are considered.

parse(parser)

property supported_signature_algs

Returns the list of supported algorithms.

We store the list in an extension even for TLS < 1.3 Extensions are used/valid only for TLS 1.3 but they are a good unified storage mechanism for all versions.

write()

class tlslite.messages.CertificateStatus

Bases: HandshakeMsg

Handling of the CertificateStatus message from RFC 6066.

Handling of the handshake protocol message that includes the OCSP staple.

Variables:

• status_type (int) – type of response returned

• ocsp (bytearray) – OCSPResponse from RFC 2560

__init__()

Create the objet, set its type.

create(status_type, ocsp)

Set up message payload.

parse(parser)

Deserialise the message from one the wire data.

write()

Serialise the message.

class tlslite.messages.CertificateVerify(version)

Bases: HandshakeMsg

Serializer for TLS handshake protocol Certificate Verify message.

__init__(version)

Create message.

Parameters:

version – TLS protocol version in use

create(signature, signatureAlgorithm=None)

Provide data for serialisation of message.

Parameters:

• signature – signature carried in the message

• signatureAlgorithm – signature algorithm used to make the signature (TLSv1.2 only)

parse(parser)

Deserialize message from parser.

Parameters:

parser – parser with data to read

write()

Serialize the data to bytearray.

Return type:

bytearray

class tlslite.messages.ChangeCipherSpec

Bases: object

__init__()

create()

parse(p)

write()

class tlslite.messages.ClientFinished

Bases: SSL2Finished

Handling of SSLv2 CLIENT-FINISHED message.

Variables:

verify_data (bytearray) – payload of the message, should be the CONNECTION-ID

__init__()

class tlslite.messages.ClientHello(ssl2=False)

Bases: HelloMessage

Class for handling the ClientHello SSLv2/SSLv3/TLS message.

Variables:

• certificate_types (list) – list of supported certificate types (deprecated)

• srp_username (bytearray) – name of the user in SRP extension (deprecated)

• ~.supports_npn (boolean) – NPN extension presence (deprecated)

• ~.tack (boolean) – TACK extension presence (deprecated)

• ~.server_name (bytearray) – first host_name (type 0) present in SNI extension (deprecated)

• extensions (list of TLSExtension) – list of TLS extensions parsed from wire or to send, see TLSExtension and child classes for exact examples

__init__(ssl2=False)

Initialize object.

__repr__()

Return machine readable representation of Client Hello.

Return type:

str

__str__()

Return human readable representation of Client Hello.

Return type:

str

property certificate_types

Return the list of certificate types supported.

Deprecated since version 0.5: use extensions field to get the extension for inspection

create(version, random, session_id, cipher_suites, certificate_types=None, srpUsername=None, tack=False, supports_npn=None, serverName=None, extensions=None)

Create a ClientHello message for sending.

Parameters:

• version (tuple) – the highest supported TLS version encoded as two int tuple

• random (bytearray) – client provided random value, in old versions of TLS (before 1.2) the first 32 bits should include system time, also used as the “challenge” field in SSLv2

• session_id (bytearray) – ID of session, set when doing session resumption

• cipher_suites (list) – list of ciphersuites advertised as supported

• certificate_types (list) – list of supported certificate types, uses TLS extension for signalling, as such requires TLS1.0 to work

• srpUsername (bytearray) – utf-8 encoded username for SRP, TLS extension

• tack (boolean) – whatever to advertise support for TACK, TLS extension

• supports_npn (boolean) – whatever to advertise support for NPN, TLS extension

• serverName (bytearray) – the hostname to request in server name indication extension, TLS extension. Note that SNI allows to set multiple hostnames and values that are not hostnames, use SNIExtension together with extensions to use it.

• extensions (list of TLSExtension) – list of extensions to advertise

parse(p)

Deserialise object from on the wire data.

psk_truncate()

Return a truncated encoding of message without binders.

In TLS 1.3, with PSK exchange, the ClientHello message is signed by the binders in it. Return the part that is symmetrically signed by those binders.

See “PSK Binder” in draft-ietf-tls-tls13-23.

Return type:

bytearray

property server_name

Return first host_name present in SNI extension.

Deprecated since version 0.5: use extensions field to get the extension for inspection

Return type:

bytearray

property srp_username

Return username for the SRP.

Deprecated since version 0.5: use extensions field to get the extension for inspection

property supports_npn

Return whether client supports NPN extension.

Deprecated since version 0.5: use extensions field to get the extension for inspection

Return type:

boolean

property tack

Return whether the client supports TACK.

Deprecated since version 0.5: use extensions field to get the extension for inspection

Return type:

boolean

write()

Serialise object to on the wire data.

class tlslite.messages.ClientKeyExchange(cipherSuite, version=None)

Bases: HandshakeMsg

Handling of TLS Handshake protocol ClientKeyExchange message.

Variables:

• cipherSuite (int) – the cipher suite id used for the connection

• ~.version (tuple(int, int)) – TLS protocol version used for the connection

• srp_A (int) – SRP protocol client answer value

• dh_Yc (int) – client Finite Field Diffie-Hellman protocol key share

• ecdh_Yc (bytearray) – encoded curve coordinates

• encryptedPreMasterSecret (bytearray) – client selected PremMaster secret encrypted with server public key (from certificate)

__init__(cipherSuite, version=None)

Initialise ClientKeyExchange for reading or writing.

Parameters:

• cipherSuite (int) – id of the ciphersuite selected by server

• version (tuple(int, int)) – protocol version selected by server

createDH(dh_Yc)

Set the client FFDH key share.

returns self

Return type:

ClientKeyExchange

createECDH(ecdh_Yc)

Set the client ECDH key share.

returns self

Return type:

ClientKeyExchange

createRSA(encryptedPreMasterSecret)

Set the encrypted PreMaster Secret.

returns self

Return type:

ClientKeyExchange

createSRP(srp_A)

Set the SRP client answer.

returns self

Parameters:

srp_A (int) – client SRP answer

Return type:

ClientKeyExchange

parse(parser)

Deserialise the message from Parser,

returns self

Return type:

ClientKeyExchange

write()

Serialise the object.

Return type:

bytearray

class tlslite.messages.ClientMasterKey

Bases: HandshakeMsg

Handling of SSLv2 CLIENT-MASTER-KEY message.

Variables:

• cipher (int) – negotiated cipher

• clear_key (bytearray) – the part of master secret key that is sent in clear for export cipher suites

• encrypted_key (bytearray) – (part of) master secret encrypted using server key

• key_argument (bytearray) – additional key argument for block ciphers

__init__()

create(cipher, clear_key, encrypted_key, key_argument)

Set values of the CLIENT-MASTER-KEY object.

parse(parser)

Deserialise object from on the wire data.

write()

Serialise the object to on the wire data.

class tlslite.messages.EncryptedExtensions

Bases: HelloMessage

Handling of the TLS1.3 Encrypted Extensions message.

__init__()

Initialize object.

create(extensions)

Set the extensions in the message.

parse(parser)

Parse the extensions from on the wire data.

write()

Serialise the message to on the wire data.

Return type:

bytearray

class tlslite.messages.Finished(version, hash_length=None)

Bases: HandshakeMsg

__init__(version, hash_length=None)

create(verify_data)

parse(p)

write()

class tlslite.messages.HandshakeMsg(handshakeType)

Bases: object

__init__(handshakeType)

postWrite(w)

class tlslite.messages.Heartbeat

Bases: object

Handling Heartbeat messages from RFC 6520

Variables:

• message_type – type of message (response or request)

• payload – payload

• padding – random padding of selected length

__init__()

__str__()

Return human readable representation of heartbeat message.

create(message_type, payload, padding_length)

Create heartbeat request or response with selected parameters

create_response()

Creates heartbeat response based on request.

parse(p)

Deserialize heartbeat message from parser.

We are reading only message type and payload, ignoring leftover bytes (padding).

write()

Serialise heartbeat message.

class tlslite.messages.HelloMessage(*args, **kwargs)

Bases: HandshakeMsg

Class for sharing code between ClientHello and ServerHello.

__init__(*args, **kwargs)

Initialize object.

addExtension(ext)

Add extension to internal list of extensions.

Parameters:

ext (TLSExtension) – extension object to add to list

getExtension(extType)

Return extension of given type if present, None otherwise.

Return type:

TLSExtension

Raises:

TLSInternalError – when there are multiple extensions of the same type

class tlslite.messages.HelloRequest

Bases: HandshakeMsg

Handling of Hello Request messages.

__init__()

create()

parse(parser)

write()

class tlslite.messages.KeyUpdate

Bases: HandshakeMsg

Handling KeyUpdate message from RFC 8446

Variables:

message_type (int) – type of message (update_not_requested or update_requested)

__init__()

create(message_type)

Create KeyUpdate message with selected parameter.

parse(p)

Deserialize keyupdate message from parser.

write()

Serialise keyupdate message.

class tlslite.messages.Message(contentType, data)

Bases: object

Generic TLS message.

__init__(contentType, data)

Initialize object with specified contentType and data.

Parameters:

• contentType (int) – TLS record layer content type of associated data

• data (bytearray) – data

write()

Return serialised object data.

class tlslite.messages.NewSessionTicket

Bases: HelloMessage

Handling of the TLS1.3 New Session Ticket message.

__init__()

Create New Session Ticket object.

create(ticket_lifetime, ticket_age_add, ticket_nonce, ticket, extensions)

Initialise a New Session Ticket.

parse(parser)

Parse the object from on the wire data.

write()

Serialise the message to on the wire data.

Return type:

bytearray

class tlslite.messages.NewSessionTicket1_0

Bases: HelloMessage

Handling of the TLS1.0-TLS1.2 NewSessionTicket message.

__init__()

Create New Session Ticket object.

create(ticket_lifetime, ticket)

Initialise a New Session Ticket.

parse(parser)

Parse the object from on the wire data.

write()

Serialise the message to on the wire data.

Return type:

bytearray

class tlslite.messages.NextProtocol

Bases: HandshakeMsg

__init__()

create(next_proto)

parse(p)

write(trial=False)

class tlslite.messages.RecordHeader(ssl2)

Bases: object

Generic interface to SSLv2 and SSLv3 (and later) record headers.

__init__(ssl2)

Define instance variables.

class tlslite.messages.RecordHeader2

Bases: RecordHeader

SSLv2 record header.

Variables:

• padding (int) – number of bytes added at end of message to make it multiple of block cipher size

• securityEscape (boolean) – whether the record contains a security escape message

__init__()

Define a SSLv2 style class.

create(length, padding=0, securityEscape=False)

Set object’s values.

parse(parser)

Deserialise object from Parser.

write()

Serialise object to bytearray.

class tlslite.messages.RecordHeader3

Bases: RecordHeader

SSLv3 (and later) TLS record header.

__init__()

Define a SSLv3 style class.

__repr__()

Return repr(self).

__str__()

Return str(self).

create(version, type, length)

Set object values for writing (serialisation).

parse(parser)

Deserialise object from Parser.

property typeName

write()

Serialise object to bytearray.

class tlslite.messages.SSL2Finished(msg_type)

Bases: HandshakeMsg

Handling of the SSL2 FINISHED messages.

__init__(msg_type)

create(verify_data)

Set the message payload.

parse(parser)

Deserialise the message from on the wire data.

write()

Serialise the message to on the wire data.

class tlslite.messages.ServerFinished

Bases: SSL2Finished

Handling of SSLv2 SERVER-FINISHED message.

Variables:

verify_data (bytearray) – payload of the message, should be SESSION-ID

__init__()

class tlslite.messages.ServerHello

Bases: HelloMessage

Handling of Server Hello messages.

Variables:

• server_version (tuple) – protocol version encoded as two int tuple

• random (bytearray) – server random value

• session_id (bytearray) – session identifier for resumption

• cipher_suite (int) – server selected cipher_suite

• compression_method (int) – server selected compression method

• next_protos (list of bytearray) – list of advertised protocols in NPN extension

• next_protos_advertised (list of bytearray) – list of protocols advertised in NPN extension

• certificate_type (int) – certificate type selected by server

• extensions (list) – list of TLS extensions present in server_hello message, see TLSExtension and child classes for exact examples

__init__()

Initialise ServerHello object.

__repr__()

Return repr(self).

__str__()

Return str(self).

property certificate_type

Return the certificate type selected by server.

Return type:

int

create(version, random, session_id, cipher_suite, certificate_type=None, tackExt=None, next_protos_advertised=None, extensions=None)

Initialize the object for deserialisation.

property next_protos

Return the advertised protocols in NPN extension.

Return type:

list of bytearrays

property next_protos_advertised

Return the advertised protocols in NPN extension.

Return type:

list of bytearrays

parse(p)

property tackExt

Return the TACK extension.

write()

class tlslite.messages.ServerHello2

Bases: HandshakeMsg

SERVER-HELLO message from SSLv2.

Variables:

• session_id_hit (int) – non zero if the client provided session ID was matched in server’s session cache

• certificate_type (int) – type of certificate sent

• server_version (tuple of ints) – protocol version selected by server

• certificate (bytearray) – certificate sent by server

• ciphers (array of int) – list of ciphers supported by server

• session_id (bytearray) – idendifier of negotiated session

__init__()

create(session_id_hit, certificate_type, server_version, certificate, ciphers, session_id)

Initialize fields of the SERVER-HELLO message.

parse(parser)

Deserialise object from on the wire data.

write()

Serialise object to on the wire data.

class tlslite.messages.ServerHelloDone

Bases: HandshakeMsg

__init__()

__repr__()

Human readable representation of object.

create()

parse(p)

write()

class tlslite.messages.ServerKeyExchange(cipherSuite, version)

Bases: HandshakeMsg

Handling TLS Handshake protocol Server Key Exchange messages.

Variables:

• cipherSuite (int) – id of ciphersuite selected in Server Hello message

• srp_N (int) – SRP protocol prime

• srp_N_len (int) – length of srp_N in bytes

• srp_g (int) – SRP protocol generator

• srp_g_len (int) – length of srp_g in bytes

• srp_s (bytearray) – SRP protocol salt value

• srp_B (int) – SRP protocol server public value

• srp_B_len (int) – length of srp_B in bytes

• dh_p (int) – FFDHE protocol prime

• dh_p_len (int) – length of dh_p in bytes

• dh_g (int) – FFDHE protocol generator

• dh_g_len (int) – length of dh_g in bytes

• dh_Ys (int) – FFDH protocol server key share

• dh_Ys_len (int) – length of dh_Ys in bytes

• curve_type (int) – Type of curve used (explicit, named, etc.)

• named_curve (int) – TLS ID of named curve

• ecdh_Ys (bytearray) – ECDH protocol encoded point key share

• signature (bytearray) – signature performed over the parameters by server

• hashAlg (int) – id of hash algorithm used for signature

• signAlg (int) – id of signature algorithm used for signature

__init__(cipherSuite, version)

Initialise Server Key Exchange for reading or writing.

Parameters:

cipherSuite (int) – id of ciphersuite selected by server

__repr__()

Return repr(self).

createDH(dh_p, dh_g, dh_Ys)

Set FFDH protocol parameters.

createECDH(curve_type, named_curve=None, point=None)

Set ECDH protocol parameters.

createSRP(srp_N, srp_g, srp_s, srp_B)

Set SRP protocol parameters.

hash(clientRandom, serverRandom)

Calculate hash of parameters to sign.

Return type:

bytearray

parse(parser)

Deserialise message from Parser.

Parameters:

parser (Parser) – parser to read data from

write()

Serialise complete message.

Return type:

bytearray

writeParams()

Serialise the key exchange parameters.

Return type:

bytearray

class tlslite.messages.SessionTicketPayload

Bases: object

Serialisation and deserialisation of server state for resumption.

This is the internal (meant to be encrypted) representation of server state that is sent to the client in the NewSessionTicket message.

Variables:

• ~.version (int) – implementation detail for forward compatibility

• master_secret (bytearray) – master secret for TLS 1.2-, resumption master secret for TLS 1.3

• protocol_version (tuple) – version of protocol that was previously negotiated in this session

• cipher_suite (int) – numerical ID of ciphersuite that was negotiated previously

• nonce (bytearray) – nonce for TLS 1.3 KDF

• creation_time (int) – Unix time in seconds when was the ticket created

• client_cert_chain (X509CertChain) – Client X509 Certificate Chain

• encrypt_then_mac (bool) – The session used the encrypt_then_mac extension

• extended_master_secret (bool) – The session used the extended_master_secret extension

__init__()

Create instance of the object.

property client_cert_chain

Getter for the client_cert_chain property.

create(master_secret, protocol_version, cipher_suite, creation_time, nonce=bytearray(b''), client_cert_chain=None, encrypt_then_mac=False, extended_master_secret=False, server_name=bytearray(b''))

Initialise the object with cryptographic data.

parse(parser)

write()

tlslite.messages.bytes_to_int(bytes, byteorder='big', *, signed=False)

Return the integer represented by the given array of bytes.

bytes

Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.

byteorder

The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value. Default is to use ‘big’.

signed

Indicates whether two’s complement is used to represent the integer.