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
-
property
extData
¶ Return encoded payload of the extension
- Return type
bytearray
-
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()
-
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
-
__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
-
property
extData
¶ Return the raw data encoding of the extension
- Return type
bytearray
-
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
-
property
extData
¶ Return raw encoding of the extension.
- Return type
bytearray
-
-
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
-
property
extData
¶ Return raw encoding of the extension.
- Return type
bytearray
-
-
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
-
property
extData
¶ Raw encoding of extension data, without type and length header.
- Return type
bytearray
-
property
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
- 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
-
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
-
property
extData
¶ Return raw data encoding of the extension
- Return type
bytearray
-
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
-
property
extData
¶ Return the raw encoding of the extension data
- Return type
bytearray
-
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
-
property
extData
¶ Return raw encoding of the extension
- Return type
bytearray
-
parse
(parser)¶ Deserialise extension from on the wire data
- Return type
-
-
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()
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
-
__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
-
property
extData
¶ Return encoded payload of the extension.
- Return type
bytearray
-
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
-
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
-
property
extData
¶ Return the raw data encoding of the extension
- Return type
bytearray
-
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()
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
-
__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
-
property
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
-
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()
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
-
__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
-
property
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
-