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 or MODE_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() and pysros.esm.cryptolib.AES.decrypt(), manual (un)padding needs to be applied on the last block. See the documentation for pad() for the supported values.

  • iv (bytes, optional) – The initial vector. For mode MODE_ECB this argument is not valid. For mode MODE_CBC it must be 16 bytes long. If not provided (but required), a random bytestring is generated. Its value must then be read via the iv 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 an output buffer was provided.

Return type:

bytes

Example: Encrypting
from 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 an output buffer was provided.

Return type:

bytes

Example: Decrypting
from 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 or x923. 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 of block_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 or x923. Default: pkcs7.

Returns:

The data without the padding bytes.

Return type:

bytes

Raises:

ValueError – If the padding is incorrect.