tlslite.extensions module¶
Helper package for handling TLS extensions encountered in ClientHello and ServerHello messages.
-
class
tlslite.extensions.
ALPNExtension
¶ Bases:
tlslite.extensions.TLSExtension
Handling of Application Layer Protocol Negotiation extension from RFC 7301.
Variables: - protocol_names (list of bytearrays) – list of protocol names acceptable or selected by peer
- extType (int) – numberic type of ALPNExtension, i.e. 16
- extData (bytearray) – raw encoding of the extension data
-
__repr__
()¶ Create programmer-readable representation of object
Return type: str
-
create
(protocol_names=None)¶ Create an instance of ALPNExtension with specified protocols
Parameters: protocols (list) – list of protocol names that are to be sent
-
extData
¶ Return encoded payload of the extension
Return type: bytearray
-
parse
(parser)¶ Parse the extension from on the wire format
Parameters: parser (Parser) – data to be parsed as extension Raises: SyntaxError – when the encoding of the extension is self inconsistent Return type: ALPNExtension
-
class
tlslite.extensions.
CertificateStatusExtension
¶ Bases:
tlslite.extensions.TLSExtension
Handling of Certificate Status response as redefined in TLS1.3
-
__init__
()¶ Create instance of CertificateStatusExtension.
-
create
(status_type, response)¶ Set values of the extension.
-
extData
¶ Serialise the object.
-
parse
(parser)¶ Deserialise the data from on the wire representation.
-
-
class
tlslite.extensions.
ClientCertTypeExtension
¶ Bases:
tlslite.extensions.VarListExtension
This class handles the (client variant of) Certificate Type extension
See RFC 6091.
Variables: - extType (int) – numeric type of Certificate Type extension, i.e. 9
- extData (bytearray) – raw representation of the extension data
- certTypes (list of int) – list of certificate type identifiers (each one byte long)
-
__init__
()¶ Create an instance of ClientCertTypeExtension
See also:
create()
andparse()
Bases:
tlslite.extensions.TLSExtension
Class for handling the Client Hello version of the Key Share extension.
Extension for sending the key shares to server
Create instance of the object.
Set the advertised client shares in the extension.
Return the on the wire raw encoding of the extension
Return type: bytearray
Parse the extension from on the wire format
Parameters: parser (Parser) – data to be parsed Raises: SyntaxError – when the data does not match the definition Return type: ClientKeyShareExtension
-
class
tlslite.extensions.
ECPointFormatsExtension
¶ Bases:
tlslite.extensions.VarListExtension
Client side list of supported ECC point formats.
See RFC4492.
Variables: formats (list of int) – list of point formats supported by peer -
__init__
()¶ Create instance of class
-
Bases:
tlslite.extensions.TLSExtension
Class for handling the Hello Retry Request variant of the Key Share ext.
Extension for notifying the client of the server selected group for key exchange.
Create instance of the object.
Set the selected group in the extension.
Serialise the payload of the extension.
Parse the extension from on the wire format.
Parameters: parser (Parser) – data to be parsed Return type: HRRKeyShareExtension
Bases:
object
Handler for of the item of the Key Share extension.
Initialise the object.
Initialise the Key Share Entry from Key Share extension.
Parameters: - group (int) – ID of the key share
- key_exchange (bytearray) – value of the key share
- private (object) – private value for the given share (won’t be encoded during serialisation)
Return type:
Parse the value from on the wire format.
Parameters: parser (Parser) – data to be parsed as extension Return type: KeyShareEntry
Write the on the wire representation of the item to writer.
Parameters: writer (Writer) – buffer to write the data to
-
class
tlslite.extensions.
ListExtension
(fieldName, extType, item_enum=None)¶ Bases:
tlslite.extensions.TLSExtension
Abstract class for extensions that deal with single list in payload.
Extension for handling arbitrary extensions comprising of just a list of same-sized elementes inside an array
-
__init__
(fieldName, extType, item_enum=None)¶ Create instance of the class.
Parameters: - fieldName (str) – name of the field to store the list that is the payload
- item_enum (class) – TLSEnum class that defines the enum of the items in the list
-
__repr__
()¶ Return human readable representation of the extension.
-
create
(values)¶ Set the list to specified values.
Parameters: values (list) – list of values to save
-
extData
¶ Return raw data encoding of the extension.
Return type: bytearray
-
parse
(parser)¶ Deserialise extension from on-the-wire data.
Parameters: parser (tlslite.utils.codec.Parser) – data Return type: Extension
-
-
class
tlslite.extensions.
NPNExtension
¶ Bases:
tlslite.extensions.TLSExtension
This class handles the unofficial Next Protocol Negotiation TLS extension.
Variables: - protocols (list of bytearrays) – list of protocol names supported by the server
- extType (int) – numeric type of NPNExtension, i.e. 13172
- extData (bytearray) – raw representation of extension data
-
__repr__
()¶ Create programmer-readable version of representation
Return type: str
-
create
(protocols=None)¶ Create an instance of NPNExtension with specified protocols
Parameters: protocols (list) – list of protocol names that are supported
-
extData
¶ Return the raw data encoding of the extension
Return type: bytearray
-
parse
(p)¶ Parse the extension from on the wire format
Parameters: p (Parser) – data to be parsed Raises: SyntaxError – when the size of the passed element doesn’t match the internal representation Return type: NPNExtension
-
class
tlslite.extensions.
PaddingExtension
¶ Bases:
tlslite.extensions.TLSExtension
ClientHello message padding with a desired size.
Can be used to pad ClientHello messages to a desired size in order to avoid implementation bugs caused by certain ClientHello sizes.
See RFC7685.
-
__init__
()¶ Create instance of class.
-
create
(size)¶ Set the padding size and create null byte padding of defined size.
Parameters: size (int) – required padding size in bytes
-
extData
¶ Return raw encoding of the extension.
Return type: bytearray
-
parse
(p)¶ Deserialise extension from on the wire data.
Parameters: p (Parser) – data to be parsed Raises: SyntaxError – when the size of the passed element doesn’t match the internal representation Return type: TLSExtension
-
Bases:
tlslite.extensions.TLSExtension
Class for handling Pre Shared Key negotiation.
Create instance of class.
Set list of offered PSKs.
Serialise the payload of the extension.
Parse the extension from on the wire format.
-
class
tlslite.extensions.
PskIdentity
¶ Bases:
object
Handling of PskIdentity from PreSharedKey Extension.
-
__init__
()¶ Create instance of class.
-
create
(identity, obf_ticket_age)¶ Initialise instance.
-
parse
(parser)¶ Deserialize the object from bytearray.
-
write
()¶ Serialise the object.
-
-
class
tlslite.extensions.
PskKeyExchangeModesExtension
¶ Bases:
tlslite.extensions.VarListExtension
Handling of the PSK Key Exchange Modes extension.
-
__init__
()¶ Create instance of class.
-
-
class
tlslite.extensions.
RenegotiationInfoExtension
¶ Bases:
tlslite.extensions.TLSExtension
Client and Server Hello secure renegotiation extension from RFC 5746
Should have an empty renegotiated_connection field in case of initial connection
-
__init__
()¶ Create instance
-
create
(renegotiated_connection)¶ Set the finished message payload from previous connection.
Parameters: renegotiated_connection (bytearray) – data
-
extData
¶ Return raw encoding of the extension.
Return type: bytearray
-
parse
(parser)¶ Deserialise extension from on the wire data.
Parameters: parser (Parser) – data to be parsed Return type: RenegotiationInfoExtension
-
-
class
tlslite.extensions.
SNIExtension
¶ Bases:
tlslite.extensions.TLSExtension
Class for handling Server Name Indication (server_name) extension from RFC 4366.
Note that while usually the client does advertise just one name, it is possible to provide a list of names, each of different type. The type is a single byte value (represented by ints), the names are opaque byte strings, in case of DNS host names (records of type 0) they are UTF-8 encoded domain names (without the ending dot).
Variables: - hostNames (tuple of bytearrays) –
tuple of hostnames (server name records of type 0) advertised in the extension. Note that it may not include all names from client hello as the client can advertise other types. Also note that while it’s not possible to change the returned array in place, it is possible to assign a new set of names. IOW, this won’t work:
sni_extension.hostNames[0] = bytearray(b'example.com')
while this will work:
names = list(sni_extension.hostNames) names[0] = bytearray(b'example.com') sni_extension.hostNames = names
- serverNames (list of
ServerName
) – list of all names advertised in extension.ServerName
is a namedtuple with two elements, the first element (type) defines the type of the name (encoded as int) while the other (name) is a bytearray that carries the value. Known types are defined intlslite.constants.NameType
. The list will be empty if the on the wire extension had and empty list while it will be None if the extension was empty. - extType (int) – numeric type of SNIExtension, i.e. 0
- extData (bytearray) – raw representation of the extension
-
class
ServerName
(name_type, name)¶ Bases:
tuple
-
__repr__
()¶ Return a nicely formatted representation string
-
name
¶ Alias for field number 1
-
name_type
¶ Alias for field number 0
-
-
__repr__
()¶ Return programmer-readable representation of extension
Return type: str
-
create
(hostname=None, hostNames=None, serverNames=None)¶ Initializes an instance with provided hostname, host names or raw server names.
Any of the parameters may be None, in that case the list inside the extension won’t be defined, if either hostNames or serverNames is an empty list, then the extension will define a list of length 0.
If multiple parameters are specified at the same time, then the resulting list of names will be concatenated in order of hostname, hostNames and serverNames last.
Parameters: - hostname (bytearray) – raw UTF-8 encoding of the host name
- hostNames (list) – list of raw UTF-8 encoded host names
- serverNames (list) – pairs of name_type and name encoded as a namedtuple
Return type:
-
extData
¶ Raw encoding of extension data, without type and length header.
Return type: bytearray
-
hostNames
¶ Returns a simulated list of hostNames from the extension.
Return type: tuple of bytearrays
-
parse
(p)¶ Deserialise the extension from on-the-wire data
The parser should not include the type or length of extension!
Parameters: p (tlslite.util.codec.Parser) – data to be parsed Return type: SNIExtension Raises: SyntaxError – when the internal sizes don’t match the attached data
-
write
()¶ Returns encoded extension, as encoded on the wire
Return type: bytearray Returns: an array of bytes formatted as they are supposed to be written on the wire, including the type, length and extension data
- hostNames (tuple of bytearrays) –
-
class
tlslite.extensions.
SRPExtension
¶ Bases:
tlslite.extensions.TLSExtension
This class handles the Secure Remote Password protocol TLS extension defined in RFC 5054.
Variables: - extType (int) – numeric type of SRPExtension, i.e. 12
- extData (bytearray) – raw representation of extension data
- identity (bytearray) – UTF-8 encoding of user name
-
__repr__
()¶ Return programmer-centric description of extension
Return type: str
-
create
(identity=None)¶ Create and instance of SRPExtension with specified protocols
Parameters: identity (bytearray) – UTF-8 encoded identity (user name) to be provided to user. MUST be shorter than 2^8-1. Raises: ValueError – when the identity lenght is longer than 2^8-1
-
extData
¶ Return raw data encoding of the extension
Return type: bytearray
-
parse
(p)¶ Parse the extension from on the wire format
Parameters: p (Parser) – data to be parsed Raises: SyntaxError – when the data is internally inconsistent Return type: SRPExtension
-
class
tlslite.extensions.
ServerCertTypeExtension
¶ Bases:
tlslite.extensions.TLSExtension
This class handles the Certificate Type extension (variant sent by server) defined in RFC 6091.
Variables: -
__repr__
()¶ Return programmer-centric description of object
Return type: str
-
create
(val)¶ Create an instance for sending the extension to client.
Parameters: val (int) – selected type of certificate
-
extData
¶ Return the raw encoding of the extension data
Return type: bytearray
-
Bases:
tlslite.extensions.TLSExtension
Class for handling the Server Hello variant of the Key Share extension.
Extension for sending the key shares to client
Create instance of the object.
Set the advertised server share in the extension.
Serialise the payload of the extension
Parse the extension from on the wire format.
Parameters: parser (Parser) – data to be parsed Return type: ServerKeyShareExtension
-
class
tlslite.extensions.
SignatureAlgorithmsCertExtension
¶ Bases:
tlslite.extensions._SigListExt
Client side list of supported signatures in certificates.
Should be used when the signatures supported in certificates and in TLS messages differ.
See TLS1.3 RFC
-
__init__
()¶ Create instance of class.
-
-
class
tlslite.extensions.
SignatureAlgorithmsExtension
¶ Bases:
tlslite.extensions._SigListExt
Client side list of supported signature algorithms.
Should be used by server to select certificate and signing method for Server Key Exchange messages. In practice used only for the latter.
See RFC5246.
-
__init__
()¶ Create instance of class
-
Bases:
tlslite.extensions.TLSExtension
Handling of the Pre Shared Key extension from server.
Create instance of class.
Set the selected PSK identity.
Serialise the extension payload.
Parse the extension from on the wire format.
-
class
tlslite.extensions.
SrvSupportedVersionsExtension
¶ Bases:
tlslite.extensions.TLSExtension
Handling of SupportedVersion extension in SH and HRR in TLS 1.3.
See draft-ietf-tls-tls13.
Variables: -
__init__
()¶
-
__repr__
()¶ Return programmer-readable representation of the extension.
Return type: str
-
create
(version)¶ Set the version supported by the server.
Parameters: version (tuple) – Version selected by server. Return type: SrvSupportedVersionsExtension
-
extData
¶ Raw encoding of extension data, without type and length header.
Return type: bytearray
-
parse
(parser)¶ Deserialise the extension from on-the-wire data.
The parser should not include the type or length of extension.
Parameters: parser (tlslite.util.codec.Parser) – data to be parsed Return type: SrvSupportedVersionsExtension
-
-
class
tlslite.extensions.
StatusRequestExtension
¶ Bases:
tlslite.extensions.TLSExtension
Handling of the Certificate Status Request extension from RFC 6066.
Variables: - status_type (int) – type of the status request
- responder_id_list (list of bytearray) – list of DER encoded OCSP responder identifiers that the client trusts
- request_extensions (bytearray) – DER encoded list of OCSP extensions, as defined in RFC 2560
-
__init__
()¶
-
__repr__
()¶ Create programmer-readable representation of object
Return type: str
-
create
(status_type=1, responder_id_list=(), request_extensions=b'')¶ Create an instance of StatusRequestExtension with specified options.
Parameters: - status_type (int) – type of status returned
- responder_id_list (list) – list of encoded OCSP responder identifiers that the client trusts
- request_extensions (bytearray) – DER encoding of requested OCSP extensions
-
extData
¶ Return encoded payload of the extension.
Return type: bytearray
-
parse
(parser)¶ Parse the extension from on the wire format.
Parameters: parser (Parser) – data to be parsed as extension Return type: StatusRequestExtension
-
class
tlslite.extensions.
SupportedGroupsExtension
¶ Bases:
tlslite.extensions.VarListExtension
Client side list of supported groups of (EC)DHE key exchage.
See RFC4492, RFC7027 and RFC-ietf-tls-negotiated-ff-dhe-10
Variables: groups (int) – list of groups that the client supports -
__init__
()¶ Create instance of class
-
-
class
tlslite.extensions.
SupportedVersionsExtension
¶ Bases:
tlslite.extensions.VarSeqListExtension
This class handles the SupportedVersion extensions used in TLS 1.3.
See draft-ietf-tls-tls13.
Variables: - extType (int) – numeric type of the Supported Versions extension, i.e. 43
- extData (bytearray) – raw representation of the extension data
- versions (list of tuples) – list of supported protocol versions; each tuple has two one byte long integers
-
__init__
()¶ Create an instance of SupportedVersionsExtension.
-
class
tlslite.extensions.
TACKExtension
¶ Bases:
tlslite.extensions.TLSExtension
This class handles the server side TACK extension (see draft-perrin-tls-tack-02).
Variables: - tacks (list) – list of TACK’s supported by server
- activation_flags (int) – activation flags for the tacks
-
class
TACK
¶ Bases:
object
Implementation of the single TACK
-
__eq__
(other)¶ Tests if the other object is equivalent to this TACK
Returns False for every object that’s not a TACK
-
__init__
()¶ Create a single TACK object
-
__repr__
()¶ Return programmmer readable representation of TACK object
Return type: str
-
create
(public_key, min_generation, generation, expiration, target_hash, signature)¶ Initialise the TACK with data
-
parse
(p)¶ Parse the TACK from on the wire format
Parameters: p (Parser) – data to be parsed Return type: TACK Raises: SyntaxError – when the internal sizes don’t match the provided data
-
write
()¶ Convert the TACK into on the wire format
Return type: bytearray
-
-
__repr__
()¶ Create a programmer readable representation of TACK extension
Return type: str
-
create
(tacks, activation_flags)¶ Initialize the instance of TACKExtension
Return type: TACKExtension
-
extData
¶ Return the raw data encoding of the extension
Return type: bytearray
-
parse
(p)¶ Parse the extension from on the wire format
Parameters: p (Parser) – data to be parsed Return type: TACKExtension
-
class
tlslite.extensions.
TLSExtension
(server=False, extType=None, encExt=False, cert=False, hrr=False)¶ Bases:
object
Base class for handling handshake protocol hello messages extensions.
This class handles the generic information about TLS extensions used by both sides of connection in Client Hello and Server Hello messages. See https://tools.ietf.org/html/rfc4366 for more info.
It is used as a base class for specific users and as a way to store extensions that are not implemented in library.
To implement a new extension you will need to create a new class which calls this class contructor (__init__), usually specifying just the extType parameter. The other methods which need to be implemented are: extData, create, parse and __repr__. If the parser can be used for client and optionally server extensions, the extension constructor should be added to _universalExtensions. Otherwise, when the client and server extensions have completely different forms, you should add client form to the _universalExtensions and the server form to _serverExtensions. Since the server MUST NOT send extensions not advertised by client, there are no purely server-side extensions. But if the client side extension is just marked by presence and has no payload, the client side (thus the _universalExtensions may be skipped, then the TLSExtension class will be used for implementing it. See end of the file for type-to-constructor bindings.
Note
Subclassing for the purpose of parsing extensions is not an officially supported part of API (just as underscores in their names would indicate).
Variables: - extType (int) – a 2^16-1 limited integer specifying the type of the extension that it contains, e.g. 0 indicates server name extension
- extData (bytearray) – a byte array containing the value of the extension as to be written on the wire
- serverType (boolean) – indicates that the extension was parsed with ServerHello specific parser, otherwise it used universal or ClientHello specific parser
- encExtType (boolean) – indicates that the extension should be the type from Encrypted Extensions
- _universalExtensions (dict) – dictionary with concrete implementations of specific TLS extensions where key is the numeric value of the extension ID. Contains ClientHello version of extensions or universal implementations
- _serverExtensions (dict) – dictionary with concrete implementations of specific TLS extensions where key is the numeric value of the extension ID. Includes only those extensions that require special handlers for ServerHello versions.
- _certificateExtensions (dict) – dictionary with concrete implementations of specific TLS extensions where the key is the numeric value of the type of the extension and the value is the class. Includes only those extensions that require special handlers for Certificate message.
- _hrrExtensions (dict) – dictionary with concrete implementation of specific TLS extensions where the key is the numeric type of the extension and the value is the class. Includes only those extensions that require special handlers for the Hello Retry Request message.
-
__eq__
(that)¶ Test if two TLS extensions are effectively the same
Will check if encoding them will result in the same on the wire representation.
Will return False for every object that’s not an extension.
-
__init__
(server=False, extType=None, encExt=False, cert=False, hrr=False)¶ Creates a generic TLS extension.
You’ll need to use
create()
orparse()
methods to create an extension that is actually usable.Parameters: - server (bool) – whether to select ClientHello or ServerHello version for parsing
- extType (int) – type of extension encoded as an integer, to be used by subclasses
- encExt (bool) – whether to select the EncryptedExtensions type for parsing
- cert (bool) – whether to select the Certificate type of extension for parsing
- hrr (bool) – whether to select the Hello Retry Request type of extension for parsing
-
__repr__
()¶ Output human readable representation of object
Child classes should override this method to support more appropriate string rendering of the extension.
Return type: str
-
create
(*args, **kwargs)¶ Initializes a generic TLS extension.
The extension can carry arbitrary data and have arbitrary payload, can be used in client hello or server hello messages.
The legacy calling method uses two arguments - the extType and data. If the new calling method is used, only one argument is passed in - data.
Child classes need to override this method so that it is possible to set values for all fields used by the extension.
Parameters: - extType (int) – if int: type of the extension encoded as an integer between 0 and 2^16-1
- data (bytearray) – raw data representing extension on the wire
Return type:
-
extData
¶ Return the on the wire encoding of extension
Child classes need to override this property so that it returns just the payload of an extension, that is, without the 4 byte generic header common to all extension. In other words, without the extension ID and overall extension length.
Return type: bytearray
-
parse
(p)¶ Parses extension from on the wire format
Child classes should override this method so that it parses the extension from on the wire data. Note that child class parsers will not receive the generic header of the extension, but just a parser with the payload. In other words, the method should be the exact reverse of the extData property.
Parameters: p (tlslite.util.codec.Parser) – data to be parsed Raises: SyntaxError – when the size of the passed element doesn’t match the internal representation Return type: TLSExtension
-
write
()¶ Returns encoded extension, as encoded on the wire
Note that child classes in general don’t need to override this method.
Return type: bytearray Returns: An array of bytes formatted as is supposed to be written on the wire, including the extension_type, length and the extension data Raises: AssertionError – when the object was not initialized
-
class
tlslite.extensions.
VarListExtension
(elemLength, lengthLength, fieldName, extType, item_enum=None)¶ Bases:
tlslite.extensions.ListExtension
Abstract extension for handling extensions comprised of uniform value list.
Extension for handling arbitrary extensions comprising of just a list of same-sized elementes inside an array
-
__init__
(elemLength, lengthLength, fieldName, extType, item_enum=None)¶ Create handler for extension that has a list of items as payload.
Parameters: - elemLength (int) – number of bytes needed to encode single element
- lengthLength (int) – number of bytes needed to encode length field
- fieldName (str) – name of the field storing the list of elements
- extType (int) – numerical ID of the extension encoded
- item_enum (class) – TLSEnum class that defines entries in the list
-
extData
¶ Return raw data encoding of the extension.
Return type: bytearray
-
parse
(parser)¶ Deserialise extension from on-the-wire data.
Parameters: parser (tlslite.utils.codec.Parser) – data Return type: Extension
-
-
class
tlslite.extensions.
VarSeqListExtension
(elemLength, elemNum, lengthLength, fieldName, extType, item_enum=None)¶ Bases:
tlslite.extensions.ListExtension
Abstract extension for handling extensions comprised of tuple list.
Extension for handling arbitrary extensions comprising of a single list of same-sized elements in same-sized tuples
-
__init__
(elemLength, elemNum, lengthLength, fieldName, extType, item_enum=None)¶ Create a handler for extension that has a list of tuples as payload.
Parameters: - elemLength (int) – number of bytes needed to encode single element of a tuple
- elemNum (int) – number of elements in a tuple
- lengthLength (int) – number of bytes needed to encode overall length of the list
- fieldName (str) – name of the field storing the list of elements
- extType (int) – numerical ID of the extension encoded
- item_enum (class) – TLSEnum class that defines entries in the list
-
extData
¶ Return raw data encoding of the extension.
Return type: bytearray
-
parse
(parser)¶ Deserialise extension from on-the-wire data.
Parameters: parser (tlslite.utils.codec.Parser) – data Return type: Extension
-