Cipher class¶

class crsysapi.Cipher¶

Generic block cipher functions.

class Alg¶

Block cipher algorithms.

AES128 = 32¶: AES-128

AES192 = 48¶: AES-192

AES256 = 64¶: AES-256

TDEA = 16¶: Triple DES (3DES, des-ede3)

class Mode¶

Block cipher modes.

CBC = 256¶: Cipher Block Chaining mode

CFB = 768¶: Cipher Feedback mode

CTR = 1024¶: Counter mode

ECB = 0¶: Electronic Code Book mode (default)

OFB = 512¶: Output Feedback mode

class Opts¶

Advanced options.

DEFAULT = 0¶: Use default options

PREFIXIV = 4096¶: Prepend the IV before the ciphertext in the output (ignored for ECB mode)

class Pad¶

Block cipher padding options.

ANSIX923 = 262144¶: Padding scheme in ANSI X9.23

DEFAULT = 0¶: Use default padding

NOPAD = 65536¶: No padding is added

ONEANDZEROES = 196608¶: Pad with 0x80 followed by as many zero bytes necessary to fill the block

PKCS5 = 131072¶: Padding scheme in PKCS#5/#7

W3C = 327680¶: Padding scheme in W3C XMLENC

static blockbytes(alg)¶

Return the block size in bytes for a given cipher algorithm.

Parameters:: alg (Cipher.Alg) -- Cipher algorithm
Returns:: Block size in bytes
Return type:: int

static decrypt(data, key, iv=None, algmodepad='', alg=None, mode=0, pad=0, opts=0)¶

Decrypt data.

Parameters:

data (bytes) -- Input data to be decrypted
key (bytes) -- Key of exact length for block cipher algorithm
iv (bytes) -- Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
algmodepad (str) -- String containing the block cipher algorithm, mode and padding, e.g. "Aes128/CBC/OneAndZeroes"
alg (Cipher.Alg) -- Cipher algorithm. Ignored if algmodepad is set, otherwise required.
mode (Cipher.Mode) -- Cipher mode. Ignored if algmodepad is set.
pad (Cipher.Pad) -- Padding method to use. Ignored if algmodepad is set.
opts (Cipher.Opts) -- Advanced options. Use Cipher.Opts.PREFIXIV to expect the IV to be prepended at the start of the input.

Returns:

Plaintext in byte array or empty array on error.

Return type:

bytes

static decrypt_block(data, key, iv=None, alg=Alg.TDEA, mode=Mode.ECB)¶

Decrypt a block of data. Must be an exact multiple of block length.

Parameters:

data (bytes) -- Input data to be decrypted
key (bytes) -- Key of exact length for block cipher algorithm
iv (bytes) -- Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
alg (Cipher.Alg) -- Cipher algorithm
mode (Cipher.Mode) -- Cipher mode

Returns:

Plaintext in byte array or empty array on error. Output is always the same length as the input.

Return type:

bytes

static decrypt_hex(datahex, keyhex, ivhex='', algmodepad='', alg=None, mode=0, pad=0, opts=0)¶

Decrypt hex-encoded data using hex-encoded parameters.

Parameters:

datahex (str) -- Input data to be decrypted encoded in hexadecimal.
keyhex (str) -- Hex-encoded key of exact length for block cipher algorithm
ivhex (str) -- Hex-encoded Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
algmodepad (str) -- String containing the block cipher algorithm, mode and padding, e.g. "Aes128/CBC/OneAndZeroes"
alg (Cipher.Alg) -- Cipher algorithm. Ignored if algmodepad is set, otherwise required.
mode (Cipher.Mode) -- Cipher mode. Ignored if algmodepad is set.
pad (Cipher.Pad) -- Padding method to use. Ignored if algmodepad is set.
opts (Cipher.Opts) -- Advanced options. Use Cipher.Opts.PREFIXIV to expect the IV to be prepended at the start of the input.

Returns:

Hex-encoded plaintext in byte array or empty array on error.

Return type:

str

static encrypt(data, key, iv=None, algmodepad='', alg=None, mode=0, pad=0, opts=0)¶

Encrypt data.

Parameters:

data (bytes) -- Input data to be encrypted
key (bytes) -- Key of exact length for block cipher algorithm
iv (bytes) -- Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
algmodepad (str) -- String containing the block cipher algorithm, mode and padding, e.g. "Aes128/CBC/OneAndZeroes"
alg (Cipher.Alg) -- Cipher algorithm. Ignored if algmodepad is set, otherwise required.
mode (Cipher.Mode) -- Cipher mode. Ignored if algmodepad is set.
pad (Cipher.Pad) -- Padding method to use. Ignored if algmodepad is set.
opts (Cipher.Opts) -- Advanced options. Use Cipher.Opts.PREFIXIV to prepend the IV to the output.

Returns:

Ciphertext or empty array on error.

Return type:

bytes

static encrypt_block(data, key, iv=None, alg=Alg.TDEA, mode=Mode.ECB)¶

Encrypt a block of data. Must be an exact multiple of block length.

Parameters:

data (bytes) -- Input data to be encrypted
key (bytes) -- Key of exact length for block cipher algorithm
iv (bytes) -- Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
alg (Cipher.Alg) -- Cipher algorithm
mode (Cipher.Mode) -- Cipher mode

Returns:

Ciphertext in byte array or empty array on error. Output is always the same length as the input.

Return type:

bytes

static encrypt_hex(datahex, keyhex, ivhex='', algmodepad='', alg=None, mode=0, pad=0, opts=0)¶

Encrypt data hex-encoded data using hex-encoded parameters.

Parameters:

datahex (str) -- Input data to be encrypted encoded in hexadecimal.
keyhex (str) -- Hex-encoded key of exact length for block cipher algorithm.
ivhex (str) -- Hex-encoded Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode.
algmodepad (str) -- String containing the block cipher algorithm, mode and padding, e.g. "Aes128/CBC/OneAndZeroes".
alg (Cipher.Alg) -- Cipher algorithm. Ignored if algmodepad is set, otherwise required.
mode (Cipher.Mode) -- Cipher mode. Ignored if algmodepad is set.
pad (Cipher.Pad) -- Padding method to use. Ignored if algmodepad is set.
opts (Cipher.Opts) -- Advanced options. Use Cipher.Opts.PREFIXIV to prepend the IV to the output.

Returns:

Hex-encoded ciphertext or empty array on error.

Return type:

str

static file_decrypt(fileout, filein, key, iv, algmodepad='', alg=None, mode=0, pad=0, opts=0)¶

Decrypt a file.

Parameters:

fileout (str) -- Name of output file to be created or overwritten
filein (str) -- Name of input file
key (bytes) -- Key of exact length for block cipher algorithm
iv (bytes) -- Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
algmodepad (str) -- String containing the block cipher algorithm, mode and padding, e.g. "Aes128/CBC/OneAndZeroes"
alg (Cipher.Alg) -- Cipher algorithm. Ignored if algmodepad is set, otherwise required.
mode (Cipher.Mode) -- Cipher mode. Ignored if algmodepad is set.
pad (Cipher.Pad) -- Padding method to use. Ignored if algmodepad is set.
opts (Cipher.Opts) -- Advanced options

Returns:

0 if successful.

Return type:

int

Note

fileout and filein must not be the same.

static file_encrypt(fileout, filein, key, iv, algmodepad='', alg=None, mode=0, pad=0, opts=0)¶

Encrypt a file.

Parameters:

fileout (str) -- Name of output file to be created or overwritten
filein (str) -- Name of input file
key (bytes) -- Key of exact length for block cipher algorithm
iv (bytes) -- Initialization Vector (IV) of exactly the block size (see Cipher.blockbytes()) or None for ECB mode
algmodepad (str) -- String containing the block cipher algorithm, mode and padding, e.g. "Aes128/CBC/OneAndZeroes"
alg (Cipher.Alg) -- Cipher algorithm. Ignored if algmodepad is set, otherwise required.
mode (Cipher.Mode) -- Cipher mode. Ignored if algmodepad is set.
pad (Cipher.Pad) -- Padding method to use. Ignored if algmodepad is set.
opts (Cipher.Opts) -- Advanced options

Returns:

0 if successful.

Return type:

int

Note

fileout and filein must not be the same.

static key_unwrap(data, kek, alg)¶

Unwrap (decrypt) key material with a key-encryption key.

Parameters:

data (bytes) -- Wrapped key
kek (bytes) -- Key encryption key
alg (Cipher.Alg) -- Cipher algorithm

Returns:

Unwrapped key material in byte array.

Return type:

bytes

static key_wrap(data, kek, alg)¶

Wrap (encrypt) key material with a key-encryption key.

Parameters:

data (bytes) -- Input key material to be encrypted
kek (bytes) -- Key encryption key
alg (Cipher.Alg) -- Cipher algorithm

Returns:

Wrapped key in byte array.

Return type:

bytes

static keybytes(alg)¶

Return the key size in bytes for a given cipher algorithm.

Parameters:: alg (Cipher.Alg) -- Cipher algorithm
Returns:: Key size in bytes
Return type:: int

static pad(data, alg, pad=Pad.PKCS5)¶

Pad byte array to correct length for ECB and CBC encryption.

Parameters:

data (bytes) -- data to be padded
alg (Cipher.Alg) -- Block cipher being used
pad (Cipher.Pad) -- Padding method to use.

Returns:

padded data in byte array.

Return type:

bytes

static pad_hex(datahex, alg, pad=Pad.PKCS5)¶

Pad hex-encoded string to correct length for ECB and CBC encryption.

Parameters:

datahex (str) -- hex-encoded data to be padded
alg (Cipher.Alg) -- Block cipher being used
pad (Cipher.Pad) -- Padding method to use.

Returns:

padded data in hex-encoded string.

Return type:

string

static unpad(data, alg, pad=Pad.PKCS5)¶

Remove padding from an encryption block.

Parameters:

data (bytes) -- padded data
alg (Cipher.Alg) -- Block cipher being used
pad (Cipher.Pad) -- Padding method to use.

Returns:

Unpadded data in byte array.

Return type:

bytes

Note

Unless pad is NoPad, the unpadded output is always shorter than the padded input. An error is indicated by returning the original data. Check its length.

static unpad_hex(datahex, alg, pad=Pad.PKCS5)¶

Remove the padding from a hex-encoded encryption block.

Parameters:

datahex (str) -- hex-encoded padded data
alg (Cipher.Alg) -- Block cipher being used
pad (Cipher.Pad) -- Padding method to use.

Returns:

Unpadded data in hex-encoded string or unchanged data on error.

Return type:

string

Note

Unless pad is NoPad, the unpadded output is always shorter than the padded input. An error is indicated by returning the original data. Check its length.