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

__init__()¶

Create instance of ALPNExtension

See also: create() and parse()

__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.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() and parse()

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

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

__init__()¶

Create an instance of NPNExtension

See also: create() and parse()

__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

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 in tlslite.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

__init__()¶

Create an instance of SNIExtension.

See also: create() and parse()

__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:	extType (int) – binary type of Certificate Type extension, i.e. 9 extData (bytearray) – raw representation of the extension data cert_type (int) – the certificate type selected by server

__init__()¶

Create an instance of ServerCertTypeExtension

See also: create() and parse()

__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

parse(p)¶

Parse the extension from on the wire format

Parameters:	p (Parser) – parser with data

class tlslite.extensions.SignatureAlgorithmsExtension¶

Bases: tlslite.extensions.TLSExtension

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

create(sigalgs)¶

Set the list of supported algorithm types

Parameters:	sigalgs (list) – list of pairs of a hash algorithm and signature algorithm

extData¶

Return raw encoding of the extension

Return type:	bytearray

parse(parser)¶

Deserialise extension from on the wire data

Return type:	SignatureAlgorithmsExtension

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__()¶

Creates a generic TLS extension.

You’ll need to use create() or parse() 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

__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.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

__init__()¶

Create an instance of TACKExtension

See also: create() and :py:meth`parse`

__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)¶

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
_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.

__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)¶

Creates a generic TLS extension.

You’ll need to use create() or parse() 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

__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:	TLSExtension

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)¶

Bases: tlslite.extensions.TLSExtension

Abstract extension for handling extensions comprised only of a value list

Extension for handling arbitrary extensions comprising of just a list of same-sized elementes inside an array

__init__(elemLength, lengthLength, fieldName, extType)¶

Creates a generic TLS extension.

You’ll need to use create() or parse() 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

__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(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

tlslite.extensions module¶

tlslite-ng

Navigation

Related Topics

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:	SNIExtension