Base class for all block ciphers. More...

#include <tsBlockCipher.h>

Inheritance diagram for ts::BlockCipher:

[legend]

Collaboration diagram for ts::BlockCipher:

[legend]

Public Member Functions
virtual	~BlockCipher ()
	Virtual destructor.

size_t	blockSize () const
	Size in bytes of the block used by the algorithm.

int	cipherId () const
	Get the "cipher id" value, as previously stored by the application.

const ByteBlock &	currentIV () const
	Get the current initialization vector.

const ByteBlock &	currentKey () const
	Get the current key.

bool	decrypt (const void cipher, size_t cipher_length, void plain, size_t plain_maxsize, size_t *plain_length=nullptr)
	Decrypt data.

size_t	decryptionCount () const
	Get the number of times the current key was used for decryption.

size_t	decryptionMax () const
	Get the maximum number of times a key should be used for decryption.

bool	encrypt (const void plain, size_t plain_length, void cipher, size_t cipher_maxsize, size_t *cipher_length=nullptr)
	Encrypt data.

size_t	encryptionCount () const
	Get the number of times the current key was used for encryption.

size_t	encryptionMax () const
	Get the maximum number of times a key should be used for encryption.

bool	hasChainingMode () const
	Check if this object is a base encryption algorithm (one block) or includes a chaining mode.

bool	hasKey () const
	Check if a current key is present and valid.

virtual bool	isValidIVSize (size_t size) const
	Check if a size in bytes is a valid initialization vector size.

virtual bool	isValidKeySize (size_t size) const
	Check if a size in bytes is a valid key size.

size_t	maxIVSize () const
	Get the maximum initialization vector sizes in bytes.

size_t	maxKeySize () const
	Maximum key sizes in bytes.

size_t	minIVSize () const
	Get the minimum initialization vector sizes in bytes.

size_t	minKeySize () const
	Minimum key sizes in bytes.

size_t	minMessageSize () const
	Get the minimum message size.

UString	name () const
	Algorithm name (informational only).

bool	residueAllowed () const
	Check if the chaining mode can process residue after the last multiple of the block size.

void	setAlertHandler (BlockCipherAlertInterface *handler)
	Set the handler to be notified on alert.

void	setCipherId (int id)
	Set some arbitrary "cipher id" value.

void	setDecryptionMax (size_t count)
	Set the maximum number of times a key should be used for decryption.

void	setEncryptionMax (size_t count)
	Set the maximum number of times a key should be used for encryption.

bool	setIV (const ByteBlock &iv)
	Set a new initialization vector without changing the key, or before setting the key.

bool	setIV (const void *iv, size_t iv_length)
	Set a new initialization vector without changing the key, or before setting the key.

bool	setKey (const ByteBlock &key)
	Schedule a new key.

bool	setKey (const ByteBlock &key, const ByteBlock &iv)
	Schedule a new key and initialization vector.

bool	setKey (const void key, size_t key_length, const void iv=nullptr, size_t iv_length=0)
	Schedule a new key and optional initialization vector.

Static Public Attributes
static constexpr size_t	UNLIMITED = std::numeric_limits<size_t>::max()
	A constant meaning "may use a key an unlimited number of times".

Protected Member Functions
	BlockCipher (const BlockCipherProperties &properties)
	Constructor for subclasses.

void	canProcessInPlace (bool can_do)
	Inform the superclass that the subclass can encrypt and decrypt in place (identical in/out buffers).

virtual bool	decryptImpl (const void cipher, size_t cipher_length, void plain, size_t plain_maxsize, size_t *plain_length)
	Decrypt one block of data (implementation of algorithm-specific part).

virtual bool	encryptImpl (const void plain, size_t plain_length, void cipher, size_t cipher_maxsize, size_t *cipher_length)
	Encrypt one block of data (implementation of algorithm-specific part).

virtual const EVP_CIPHER *	getAlgorithm () const
	Get the EVP for the cipher algorithm, when the subclass uses OpenSSL.

virtual void	getAlgorithm (::BCRYPT_ALG_HANDLE &algo, size_t &length, bool &ignore_iv) const
	Get the algorithm handle and subobject size, when the subclass uses Microsoft BCrypt library.

virtual bool	setKeyImpl ()
	Schedule a new key and optional initialization vector (implementation of algorithm-specific part).

Protected Attributes
const BlockCipherProperties &	properties
	Properties for this block cipher object instance.

ByteBlock	work {}
	Temporary working buffer.

Detailed Description

Base class for all block ciphers.

A block cipher may be a base encryption algorithm (one block) or includes a chaining mode.

Constructor & Destructor Documentation

◆ BlockCipher()

ts::BlockCipher::BlockCipher ( const BlockCipherProperties & properties )

protected

Constructor for subclasses.

Parameters

[in] properties Constant reference to a block of properties of this block cipher. The reference is kept all along the life of the object instance. The referenced object is typically static.

Member Function Documentation

◆ name()

UString ts::BlockCipher::name ( ) const

Algorithm name (informational only).

Returns: The algorithm name.

◆ blockSize()

size_t ts::BlockCipher::blockSize ( ) const

inline

Size in bytes of the block used by the algorithm.

Returns: The size in bytes of the block used by the algorithm.

◆ minKeySize()

size_t ts::BlockCipher::minKeySize ( ) const

inline

Minimum key sizes in bytes.

Returns: The minimum key sizes in bytes.

◆ maxKeySize()

size_t ts::BlockCipher::maxKeySize ( ) const

inline

Maximum key sizes in bytes.

Returns: The maximum key sizes in bytes.

◆ isValidKeySize()

virtual bool ts::BlockCipher::isValidKeySize ( size_t size ) const

virtual

Check if a size in bytes is a valid key size.

Parameters

[in] size Suggested key size in bytes.

Returns: True if size is a valid key size for the algorithm.

◆ isValidIVSize()

virtual bool ts::BlockCipher::isValidIVSize ( size_t size ) const

virtual

Check if a size in bytes is a valid initialization vector size.

Parameters

[in] size Suggested IV size in bytes.

Returns: True if size is a valid IV size for the algorithm.

◆ hasChainingMode()

bool ts::BlockCipher::hasChainingMode ( ) const

inline

Check if this object is a base encryption algorithm (one block) or includes a chaining mode.

Returns: True if this object includes a chaining mode, false otherwise.

◆ minIVSize()

size_t ts::BlockCipher::minIVSize ( ) const

inline

Get the minimum initialization vector sizes in bytes.

Returns: The minimum IV sizes in bytes. Zero if no chaining mode is defined.

◆ maxIVSize()

size_t ts::BlockCipher::maxIVSize ( ) const

inline

Get the maximum initialization vector sizes in bytes.

Returns: The maximum IV sizes in bytes. Zero if no chaining mode is defined.

◆ minMessageSize()

size_t ts::BlockCipher::minMessageSize ( ) const

inline

Get the minimum message size.

Shorter data cannot be ciphered in this mode.

Returns: The minimum message size. Always equal to blockSize() if no chaining mode is defined.

◆ residueAllowed()

bool ts::BlockCipher::residueAllowed ( ) const

inline

Check if the chaining mode can process residue after the last multiple of the block size.

Returns: True if the chaining mode can process residue after the last multiple of the block size.

◆ setKey() [1/3]

bool ts::BlockCipher::setKey	(	const void *	key,
		size_t	key_length,
		const void *	iv = `nullptr`,
		size_t	iv_length = `0`
	)

Schedule a new key and optional initialization vector.

Parameters

[in]	key	Address of key value.
[in]	key_length	Key length in bytes.
[in]	iv	Address of IV value (for chaining mode only).
[in]	iv_length	IV length in bytes (for chaining mode only).

Returns: True on success, false on error.

◆ setKey() [2/3]

bool ts::BlockCipher::setKey ( const ByteBlock & key )

inline

Schedule a new key.

Parameters

[in] key Key value.

Returns: True on success, false on error.

◆ setKey() [3/3]

bool ts::BlockCipher::setKey	(	const ByteBlock &	key,
		const ByteBlock &	iv
	)

inline

Schedule a new key and initialization vector.

Parameters

[in]	key	Key value.
[in]	iv	IV value (for chaining mode only).

Returns: True on success, false on error.

◆ setIV() [1/2]

bool ts::BlockCipher::setIV	(	const void *	iv,
		size_t	iv_length
	)

Set a new initialization vector without changing the key, or before setting the key.

Note that if you need to set the key and IV, it is usually much more efficient to do it in one call instead of two (and not only because of te two calls).

Parameters

[in]	iv	Address of IV value (for chaining mode only).
[in]	iv_length	IV length in bytes (for chaining mode only).

Returns: True on success, false on error.

◆ setIV() [2/2]

bool ts::BlockCipher::setIV ( const ByteBlock & iv )

inline

Set a new initialization vector without changing the key, or before setting the key.

Note that if you need to set the key and IV, it is usually much more efficient to do it in one call instead of two (and not only because of te two calls).

Parameters

[in] iv IV value (for chaining mode only).

Returns: True on success, false on error.

◆ hasKey()

bool ts::BlockCipher::hasKey ( ) const

inline

Check if a current key is present and valid.

Returns: True if a current key is present and valid.

◆ currentKey()

const ByteBlock & ts::BlockCipher::currentKey ( ) const

inline

Get the current key.

Returns: A constant reference to the current key value.

◆ currentIV()

const ByteBlock & ts::BlockCipher::currentIV ( ) const

inline

Get the current initialization vector.

Returns: A constant reference to the current initialization vector value.

◆ encrypt()

bool ts::BlockCipher::encrypt	(	const void *	plain,
		size_t	plain_length,
		void *	cipher,
		size_t	cipher_maxsize,
		size_t *	cipher_length = `nullptr`
	)

Encrypt data.

For pure block ciphers such as AES or DES, the plain text and cipher text must have the block size of the algorithm. For cipher chainings, the acceptable message sizes depend on the chaining mode.

Plain and cipher buffers may be identical (start at the same location). If they don't start at the same address, they may not overlap.

Parameters

[in]	plain	Address of plain text.
[in]	plain_length	Plain text length in bytes.
[out]	cipher	Address of buffer for cipher text.
[in]	cipher_maxsize	Size of cipher buffer.
[out]	cipher_length	Returned actual size of cipher text. Ignored if zero.

Returns: True on success, false on error.

◆ decrypt()

bool ts::BlockCipher::decrypt	(	const void *	cipher,
		size_t	cipher_length,
		void *	plain,
		size_t	plain_maxsize,
		size_t *	plain_length = `nullptr`
	)

Decrypt data.

For pure block ciphers such as AES or DES, the plain text and cipher text must have the block size of the algorithm. For cipher chainings, the acceptable message sizes depend on the chaining mode.

Plain and cipher buffers may be identical (start at the same location). If they don't start at the same address, they may not overlap.

Parameters

[in]	cipher	Address of cipher text.
[in]	cipher_length	Cipher text length in bytes.
[out]	plain	Address of buffer for plain text.
[in]	plain_maxsize	Size of plain buffer.
[out]	plain_length	Returned actual size of plain text. Ignored if zero.

Returns: True on success, false on error.

◆ encryptionCount()

size_t ts::BlockCipher::encryptionCount ( ) const

inline

Get the number of times the current key was used for encryption.

Returns: The number of times the current key was used for encryption.

◆ decryptionCount()

size_t ts::BlockCipher::decryptionCount ( ) const

inline

Get the number of times the current key was used for decryption.

Returns: The number of times the current key was used for decryption.

◆ setEncryptionMax()

void ts::BlockCipher::setEncryptionMax ( size_t count )

inline

Set the maximum number of times a key should be used for encryption.

The default initial value is UNLIMITED.

Parameters

[in] count The maximum number of times a key should be used for encryption.

◆ setDecryptionMax()

void ts::BlockCipher::setDecryptionMax ( size_t count )

inline

Set the maximum number of times a key should be used for decryption.

The default initial value is UNLIMITED.

Parameters

[in] count The maximum number of times a key should be used for decryption.

◆ encryptionMax()

size_t ts::BlockCipher::encryptionMax ( ) const

inline

Get the maximum number of times a key should be used for encryption.

Returns: The maximum number of times a key should be used for encryption.

◆ decryptionMax()

size_t ts::BlockCipher::decryptionMax ( ) const

inline

Get the maximum number of times a key should be used for decryption.

Returns: The maximum number of times a key should be used for decryption.

◆ setAlertHandler()

void ts::BlockCipher::setAlertHandler ( BlockCipherAlertInterface * handler )

inline

Set the handler to be notified on alert.

Only one handler can be set at a time.

Parameters

[in] handler Handler to set. Use a null pointer to remove the handler.

◆ setCipherId()

void ts::BlockCipher::setCipherId ( int id )

inline

Set some arbitrary "cipher id" value.

This value is chosen and set by the application and can be retrieved later. The cipher id is not interpreted by the block cipher engine, it is only stored for the application. The initial value of a cipher id is zero.

Parameters

[in] id Application-defined cipher id to assign.

◆ cipherId()

int ts::BlockCipher::cipherId ( ) const

inline

Get the "cipher id" value, as previously stored by the application.

Returns: The application-defined cipher id.

◆ setKeyImpl()

virtual bool ts::BlockCipher::setKeyImpl ( )

protectedvirtual

Schedule a new key and optional initialization vector (implementation of algorithm-specific part).

Must be implemented by the subclass if it does not use the system-provided cryptographic library.

Returns: True on success, false on error.

Reimplemented in ts::DVBCSA2.

◆ encryptImpl()

virtual bool ts::BlockCipher::encryptImpl	(	const void *	plain,
		size_t	plain_length,
		void *	cipher,
		size_t	cipher_maxsize,
		size_t *	cipher_length
	)

protectedvirtual

Encrypt one block of data (implementation of algorithm-specific part).

Must be implemented by the subclass if it does not use the system-provided cryptographic library.

Parameters

[in]	plain	Address of plain text.
[in]	plain_length	Plain text length in bytes.
[out]	cipher	Address of buffer for cipher text.
[in]	cipher_maxsize	Size of cipher buffer.
[out]	cipher_length	Returned actual size of cipher text. Ignored if zero.

Returns: True on success, false on error.

Reimplemented in ts::DVBCSA2.

◆ decryptImpl()

virtual bool ts::BlockCipher::decryptImpl	(	const void *	cipher,
		size_t	cipher_length,
		void *	plain,
		size_t	plain_maxsize,
		size_t *	plain_length
	)

protectedvirtual

Decrypt one block of data (implementation of algorithm-specific part).

Must be implemented by the subclass if it does not use the system-provided cryptographic library.

Parameters

[in]	cipher	Address of cipher text.
[in]	cipher_length	Cipher text length in bytes.
[out]	plain	Address of buffer for plain text.
[in]	plain_maxsize	Size of plain buffer.
[out]	plain_length	Returned actual size of plain text. Ignored if zero.

Returns: True on success, false on error.

Reimplemented in ts::DVBCSA2.

◆ canProcessInPlace()

void ts::BlockCipher::canProcessInPlace ( bool can_do )

inlineprotected

Inform the superclass that the subclass can encrypt and decrypt in place (identical in/out buffers).

Typically called by a subclass in constructor.

Parameters

[in] can_do If true, encrypt and decrypt in place is possible.

◆ getAlgorithm() [1/2]

virtual void ts::BlockCipher::getAlgorithm	(	::BCRYPT_ALG_HANDLE &	algo,
		size_t &	length,
		bool &	ignore_iv
	)		const

protectedvirtual

Get the algorithm handle and subobject size, when the subclass uses Microsoft BCrypt library.

Parameters

[out]	algo	Handle to hash algorithm.
[out]	length	Length in bytes of the subobject to allocate.
[out]	ignore_iv	The IV shall not be passed to BCrypt.

Reimplemented in ts::AES128, ts::AES256, ts::DES, and ts::TDES.

◆ getAlgorithm() [2/2]

virtual const EVP_CIPHER * ts::BlockCipher::getAlgorithm ( ) const

protectedvirtual

Get the EVP for the cipher algorithm, when the subclass uses OpenSSL.

Returns: EVP cipher.

Member Data Documentation

◆ properties

const BlockCipherProperties& ts::BlockCipher::properties

protected

Properties for this block cipher object instance.

Accessible to subclasses, but constant.

The documentation for this class was generated from the following file:

tsBlockCipher.h

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BlockCipher()

Member Function Documentation

◆ name()

◆ blockSize()

◆ minKeySize()

◆ maxKeySize()

◆ isValidKeySize()

◆ isValidIVSize()

◆ hasChainingMode()

◆ minIVSize()

◆ maxIVSize()

◆ minMessageSize()

◆ residueAllowed()

◆ setKey() [1/3]

◆ setKey() [2/3]

◆ setKey() [3/3]

◆ setIV() [1/2]

◆ setIV() [2/2]

◆ hasKey()

◆ currentKey()

◆ currentIV()

◆ encrypt()

◆ decrypt()

◆ encryptionCount()

◆ decryptionCount()

◆ setEncryptionMax()

◆ setDecryptionMax()

◆ encryptionMax()

◆ decryptionMax()

◆ setAlertHandler()

◆ setCipherId()

◆ cipherId()

◆ setKeyImpl()

◆ encryptImpl()

◆ decryptImpl()

◆ canProcessInPlace()

◆ getAlgorithm() [1/2]

◆ getAlgorithm() [2/2]

Member Data Documentation

◆ properties