tlslite.recordlayer module¶
Implementation of the TLS Record Layer protocol
-
class
tlslite.recordlayer.
ConnectionState
¶ Bases:
object
Preserve the connection state for reading and writing data to records
-
__init__
()¶ Create an instance with empty encryption and MACing contexts
-
getSeqNumBytes
()¶ Return encoded sequence number and increment it.
-
-
class
tlslite.recordlayer.
RecordLayer
(sock)¶ Bases:
object
Implementation of TLS record layer protocol
Variables: - version – the TLS version to use (tuple encoded as on the wire)
- sock – underlying socket
- client – whether the connection should use encryption
- handshake_finished – used in SSL2, True if handshake protocol is over
- tls13record – if True, the record layer will use the TLS 1.3 version and content type hiding
- early_data_ok (bool) – if True, it’s ok to ignore undecryptable records up to the size of max_early_data (sum of payloads)
- max_early_data (int) – maximum number of bytes that will be processed before aborting the connection on data that can not be validated, works only if early_data_ok is set to True
- padding_cb (callable) – callback used for calculating the size of padding to add in TLSv1.3 records
- send_record_limit (int) – hint provided to padding callback to not generate records larger than the receiving size expects
- recv_record_limit (int) – negotiated size of records we are willing to accept, TLSRecordOverflow will be raised when records with larger plaintext size are received (in TLS 1.3 padding is included in this size but encrypted content type is not)
-
__init__
(sock)¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
addPadding
(data)¶ Add padding to data so that it is multiple of block size
-
blockSize
¶ Return the size of block used by current symmetric cipher (R/O)
-
calcPendingStates
(cipherSuite, masterSecret, clientRandom, serverRandom, implementations)¶ Create pending states for encryption and decryption.
-
calcSSL2PendingStates
(cipherSuite, masterSecret, clientRandom, serverRandom, implementations)¶ Create the keys for encryption and decryption in SSLv2
While we could reuse calcPendingStates(), we need to provide the key-arg data for the server that needs to be passed up to handshake protocol.
-
calcTLS1_3KeyUpdate_reciever
(cipherSuite, cl_app_secret, sr_app_secret)¶
-
calcTLS1_3KeyUpdate_sender
(cipherSuite, cl_app_secret, sr_app_secret)¶
-
calcTLS1_3PendingState
(cipherSuite, cl_traffic_secret, sr_traffic_secret, implementations)¶ Create pending state for encryption in TLS 1.3.
Parameters: - cipherSuite (int) – cipher suite that will be used for encrypting and decrypting data
- cl_traffic_secret (bytearray) – Client Traffic Secret, either handshake secret or application data secret
- sr_traffic_secret (bytearray) – Server Traffic Secret, either handshake secret or application data secret
- implementations (list) – list of names of implementations that are permitted for the connection
-
calculateMAC
(mac, seqnumBytes, contentType, data)¶ Calculate the SSL/TLS version of a MAC
-
changeReadState
()¶ Change the cipher state to the pending one for read operations.
This should be done only once after a call to
calcPendingStates()
was performed and directly after receiving aChangeCipherSpec
message.
-
changeWriteState
()¶ Change the cipher state to the pending one for write operations.
This should be done only once after a call to
calcPendingStates()
was performed and directly after sending aChangeCipherSpec
message.
-
early_data_ok
¶ Set or get the state of early data acceptability.
If processing of the early_data records is to suceed, even if the encryption is not correct, set this property to True. It will be automatically reset to False as soon as a decryptable record is processed.
Use max_early_data to set the limit of the total size of records that will be processed like this.
-
encryptThenMAC
¶ Set or get the setting of Encrypt Then MAC mechanism.
set the encrypt-then-MAC mechanism for record integrity for next parameter change (after CCS), gets current state
-
getCipherImplementation
()¶ Return the name of the implementation used for the connection
‘python’ for tlslite internal implementation, ‘openssl’ for M2crypto and ‘pycrypto’ for pycrypto :rtype: str :returns: Name of cipher implementation used, None if not initialised
-
getCipherName
()¶ Return the name of the bulk cipher used by this connection
Return type: str Returns: The name of the cipher, like ‘aes128’, ‘rc4’, etc.
-
isCBCMode
()¶ Returns true if cipher uses CBC mode
-
recvRecord
()¶ Read, decrypt and check integrity of a single record
Return type: tuple
Returns: message header and decrypted message payload
Raises: - TLSDecryptionFailed – when decryption of data failed
- TLSBadRecordMAC – when record has bad MAC or padding
- socket.error – when reading from socket was unsuccessful
- TLSRecordOverflow – when the received record was longer than allowed by negotiated version of TLS
-
recv_record_limit
¶ Maximum record size that is permitted for receiving.
-
sendRecord
(msg)¶ Encrypt, MAC and send arbitrary message as-is through socket.
Note that if the message was not fragmented to below 2**14 bytes it will be rejected by the other connection side.
Parameters: msg (ApplicationData, HandshakeMessage, etc.) – TLS message to send
-
shutdown
()¶ Clear read and write states
-
tls13record
¶ Return the value of the tls13record state.
-
version
¶ Return the TLS version used by record layer
-
class
tlslite.recordlayer.
RecordSocket
(sock)¶ Bases:
object
Socket wrapper for reading and writing TLS Records.
Variables: - sock – wrapped socket
- version – version for the records to be encoded on the wire
- tls13record – flag to indicate that TLS 1.3 specific record limits should be used for received records
- recv_record_limit (int) – negotiated maximum size of record plaintext size
-
__init__
(sock)¶ Assign socket to wrapper
-
recv
()¶ Read a single record from socket, handle SSLv2 and SSLv3 record layer
Return type: generator
Returns: generator that returns 0 or 1 in case the read would be blocking or a tuple containing record header (object) and record data (bytearray) read from socket
Raises: - socket.error – In case of network error
- TLSAbruptCloseError – When the socket was closed on the other side in middle of record receiving
- TLSRecordOverflow – When the received record was longer than allowed by TLS
- TLSIllegalParameterException – When the record header was malformed
-
send
(msg, padding=0)¶ Send the message through socket.
Parameters: - msg (bytearray) – TLS message to send
- padding (int) – amount of padding to specify for SSLv2
Raises: socket.error – when write to socket failed