The pysros.esm.cryptolib
module provides a set of classes and functions that can be used
to encrypt and decrypt data.
Note
This module is available when executing on SR OS only. On a remote
machine, the pysros.esm.cryptolib
module is not supported.
This module is only available when a Python application is triggered by the Enhanced Subscriber Management (ESM) application on SR OS.
The general principle is to create cipher object of the type of pysros.esm.cryptolib.AES
with which you want to encrypt and decrypt data.
This object is created with all required parameters once, after which it can be used multiple times to either encrypt or decrypt pieces of data.
Note
The cipher object contains all information needed to encrypt and decrypt data. Depending on the block-mode used, this also contains the intermediate state needed to chain multiple blocks of data. For these block-modes, an object can only be used for encryption or decryption, but not both at the same time.
MODE_ECB
is an exception because it does not use chaining, hence this object can be used
for both encryption and decryption at the same time.
Cryptography
- class pysros.esm.cryptolib.AES(key, mode, *, padding=None, iv=None)
Create a new AES cipher object. This object can then be used to encrypt and decrypt data.
- Parameters:
key (bytes) – The secret key to use. It must be 16, 24, or 32 bytes long (respectively for AES-128, AES-192 and AES-256).
mode (One of the constants
MODE_ECB
orMODE_CBC
.) – The chaining mode.padding (string, optional) – The padding algorithm to be automatically applied. When provided, the cleartext will be automatically padded/unpadded. The value of this attribute is the style of padding to use. This method can only be used if the complete data to be encrypted or decrypted is passed in as a whole. In case the data is encrypted in multiple invocations of
pysros.esm.cryptolib.AES.encrypt()
andpysros.esm.cryptolib.AES.decrypt()
, manual (un)padding needs to be applied on the last block. See the documentation forpad()
for the supported values.iv (bytes, optional) – The initial vector. For mode
MODE_ECB
this argument is not valid. For modeMODE_CBC
it must be 16 bytes long. If not provided (but required), a random bytestring is generated. Its value must then be read via theiv
attribute.
- encrypt(plaintext, /, *, output=None)
Encrypt plaintext.
The function either returns the encrypted data or places it in a preallocated buffer passed in via the
output
parameter.- Parameters:
plaintext (bytes) – The plaintext that needs to be encrypted. Should be a multiple of the configured
block_size
, unless automatic padding is configured.output (bytearray) – Preallocated buffer into which the encrypted data is written. The input must be of the correct size (i.e. the same length as the plaintext input). It cannot be used when the object is configured to automatically apply padding, as the size might increase due to an extra padding-block.
- Returns:
The ciphertext or
None
when anoutput
buffer was provided.- Return type:
bytes
Example: Encryptingfrom pysros.esm.cryptolib import AES, MODE_ECB key = b'0123456789abcdef' aes = AES(key, MODE_ECB, padding='pkcs7') aes.encrypt(b'My super-secret message') # b'\xd8V\x01\x08\xb9f\xad\xbe\xa1\xbe\x8c\xe4I0E\xc7J\xf1W\xf9\xa0\xf8\x18Nu\xb5\xbd\xe9L_E\xa7'
- decrypt(ciphertext, /, *, output=None)
Decrypt ciphertext.
The function either returns the plaintext data or places it in a preallocated buffer passed in via the
output
parameter.- Parameters:
ciphertext (bytes) – The ciphertext that needs to be decrypted. Should be a multiple of the configured
block_size
, unless automatic padding is configured.output (bytearray) – Preallocated buffer into which the decrypted plaintext is written. Must be of the correct size (i.e. the same length as the ciphertext input). It cannot be used when the object is configured to automatically apply padding, as the size might decrease due to stripped padding.
- Returns:
The plaintext or
None
when anoutput
buffer was provided.- Return type:
bytes
Example: Decryptingfrom pysros.esm.cryptolib import AES, MODE_ECB key = b'0123456789abcdef' aes = AES(key, MODE_ECB, padding='pkcs7') aes.decrypt(b'\xd8V\x01\x08\xb9f\xad\xbe\xa1\xbe\x8c\xe4I0E\xc7J\xf1W\xf9\xa0\xf8\x18Nu\xb5\xbd\xe9L_E\xa7') #b'My super-secret message'
Note
All places where parameters of type bytes are expected, objects of type bytearray or str can also be provided.
Mode constants
- MODE_ECB
Electronic Code Book mode.
- MODE_CBC
Cipher-Block Chaining mode
Utilities
- pysros.esm.cryptolib.pad(data, block_size, /, style='pkcs7')
Apply standard padding.
- Parameters:
data (bytes) – The data that needs to be padded.
block_size (int) – The block size to use. The output is a multiple of
block_size
.style – Padding algorithm. It can be
pkcs7
,iso7816
orx923
. Default:pkcs7
.
- Tyoe style:
str, optional
- Returns:
The original data with appropriate padding added to the end. If the length of
data
is already a multiple ofblock_size
, a whole extra block will be added.- Return type:
bytes
- pysros.esm.cryptolib.unpad(data, block_size, /, style='pkcs7')
Remove standard padding.
- Parameters:
data (bytes) – The data that needs to be stripped of padding.
block_size (int) – The block size to use. The input must be a multiple of
block_size
.style (str, optional) – Padding algorithm. It can be
pkcs7
,iso7816
orx923
. Default:pkcs7
.
- Returns:
The data without the padding bytes.
- Return type:
bytes
- Raises:
ValueError – If the padding is incorrect.