TSDuck Version 3.19-1426 (TSDuck - The MPEG Transport Stream Toolkit)
ts::CipherChaining Class Referenceabstract

Base class of all cipher chaining modes. More...

Inheritance diagram for ts::CipherChaining:
Collaboration diagram for ts::CipherChaining:

Public Member Functions

virtual size_t blockSize () const override
 Size in bytes of the block used by the algorithm. More...
 
int cipherId () const
 Get the "cipher id" value, as previously stored by the application. More...
 
bool decrypt (const void *cipher, size_t cipher_length, void *plain, size_t plain_maxsize, size_t *plain_length=nullptr)
 Decrypt one block of data. More...
 
bool decryptInPlace (void *data, size_t data_length, size_t *max_actual_length=nullptr)
 Decrypt one block of data in place. More...
 
size_t decryptionCount () const
 Get the number of times the current key was used for decryption. More...
 
size_t decryptionMax () const
 Get the maximum number of times a key should be used for decryption. More...
 
virtual size_t defaultRounds () const override
 Default number of rounds for the algorithm. More...
 
bool encrypt (const void *plain, size_t plain_length, void *cipher, size_t cipher_maxsize, size_t *cipher_length=nullptr)
 Encrypt one block of data. More...
 
bool encryptInPlace (void *data, size_t data_length, size_t *max_actual_length=nullptr)
 Encrypt one block of data in place. More...
 
size_t encryptionCount () const
 Get the number of times the current key was used for encryption. More...
 
size_t encryptionMax () const
 Get the maximum number of times a key should be used for encryption. More...
 
bool getKey (ByteBlock &key) const
 Get the current key. More...
 
virtual bool isValidKeySize (size_t size) const override
 Check if a size in bytes is a valid key size. More...
 
virtual size_t maxIVSize () const
 Get the maximum IV sizes in bytes. More...
 
virtual size_t maxKeySize () const override
 Maximum key sizes in bytes. More...
 
virtual size_t maxRounds () const override
 Maximum number of rounds for the algorithm. More...
 
virtual size_t minIVSize () const
 Get the minimum IV sizes in bytes. More...
 
virtual size_t minKeySize () const override
 Minimum key sizes in bytes. More...
 
virtual size_t minMessageSize () const =0
 Get the minimum message size. More...
 
virtual size_t minRounds () const override
 Minimum number of rounds for the algorithm. More...
 
virtual UString name () const =0
 Algorithm name (informational only). More...
 
virtual bool residueAllowed () const =0
 Check if the chaining mode can process residue after the last multiple of the block size. More...
 
void setAlertHandler (BlockCipherAlertInterface *handler)
 Set the handler to be notified on alert. More...
 
void setCipherId (int id)
 Set some arbitrary "cipher id" value. More...
 
void setDecryptionMax (size_t count)
 Set the maximum number of times a key should be used for decryption. More...
 
void setEncryptionMax (size_t count)
 Set the maximum number of times a key should be used for encryption. More...
 
virtual bool setIV (const void *iv_data, size_t iv_length)
 Set a new initialization vector. More...
 
bool setKey (const void *key, size_t key_length, size_t rounds=0)
 Schedule a new key. More...
 

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

 CipherChaining (BlockCipher *cipher=nullptr, size_t iv_min_blocks=1, size_t iv_max_blocks=1, size_t work_blocks=1)
 Constructor for subclasses. More...
 
virtual bool decryptImpl (const void *cipher, size_t cipher_length, void *plain, size_t plain_maxsize, size_t *plain_length)=0
 Decrypt one block of data (implementation of algorithm-specific part). More...
 
virtual bool decryptInPlaceImpl (void *data, size_t data_length, size_t *max_actual_length)
 Decrypt one block of data in place (implementation of algorithm-specific part). More...
 
virtual bool encryptImpl (const void *plain, size_t plain_length, void *cipher, size_t cipher_maxsize, size_t *cipher_length)=0
 Encrypt one block of data (implementation of algorithm-specific part). More...
 
virtual bool encryptInPlaceImpl (void *data, size_t data_length, size_t *max_actual_length)
 Encrypt one block of data in place (implementation of algorithm-specific part). More...
 
virtual bool setKeyImpl (const void *key, size_t key_length, size_t rounds) override
 Schedule a new key (implementation of algorithm-specific part). More...
 

Protected Attributes

BlockCipheralgo
 An instance of the block cipher.
 
const size_t block_size
 Shortcut for algo->blockSize().
 
ByteBlock iv
 Current initialization vector.
 
const size_t iv_max_size
 IV max size in bytes.
 
const size_t iv_min_size
 IV min size in bytes.
 
ByteBlock work
 Temporary working buffer.
 

Detailed Description

Base class of all cipher chaining modes.

Each instance uses a specific block cipher. The combination of a block cipher and a chaining mode also implements the same interface as ts::BlockCipher.

Constructor & Destructor Documentation

◆ CipherChaining()

ts::CipherChaining::CipherChaining ( BlockCipher cipher = nullptr,
size_t  iv_min_blocks = 1,
size_t  iv_max_blocks = 1,
size_t  work_blocks = 1 
)
protected

Constructor for subclasses.

Parameters
[in,out]cipherAn instance of block cipher.
[in]iv_min_blocksMinimum IV size in multiples of cipher block size (default: 1).
[in]iv_max_blocksMaximum IV size in multiples of cipher block size (default: 1).
[in]work_blocksTemporary work buffer size in multiples of cipher block size (default: 1).

Member Function Documentation

◆ blockSize()

virtual size_t ts::CipherChaining::blockSize ( ) const
overridevirtual

Size in bytes of the block used by the algorithm.

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

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ minKeySize()

virtual size_t ts::CipherChaining::minKeySize ( ) const
overridevirtual

Minimum key sizes in bytes.

Returns
The minimum key sizes in bytes.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ maxKeySize()

virtual size_t ts::CipherChaining::maxKeySize ( ) const
overridevirtual

Maximum key sizes in bytes.

Returns
The maximum key sizes in bytes.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ isValidKeySize()

virtual bool ts::CipherChaining::isValidKeySize ( size_t  size) const
overridevirtual

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

Parameters
[in]sizeSuggested key size in bytes.
Returns
True if size is a valid key size for the algorithm.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ minRounds()

virtual size_t ts::CipherChaining::minRounds ( ) const
overridevirtual

Minimum number of rounds for the algorithm.

Returns
The minimum number of rounds for the algorithm.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ maxRounds()

virtual size_t ts::CipherChaining::maxRounds ( ) const
overridevirtual

Maximum number of rounds for the algorithm.

Returns
The maximum number of rounds for the algorithm.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ defaultRounds()

virtual size_t ts::CipherChaining::defaultRounds ( ) const
overridevirtual

Default number of rounds for the algorithm.

Returns
The default number of rounds for the algorithm.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ setIV()

virtual bool ts::CipherChaining::setIV ( const void *  iv_data,
size_t  iv_length 
)
virtual

Set a new initialization vector.

Parameters
[in]iv_dataAddress of IV.
[in]iv_lengthIV length in bytes.
Returns
True on success, false on error.

Reimplemented in ts::DVS042< CIPHER >, ts::DVS042< AES >, ts::DVS042< DES >, and ts::DVBCSA2.

◆ minIVSize()

virtual size_t ts::CipherChaining::minIVSize ( ) const
virtual

Get the minimum IV sizes in bytes.

Returns
The minimum IV sizes in bytes.

Reimplemented in ts::DVBCSA2.

◆ maxIVSize()

virtual size_t ts::CipherChaining::maxIVSize ( ) const
virtual

Get the maximum IV sizes in bytes.

Returns
The maximum IV sizes in bytes.

Reimplemented in ts::DVBCSA2.

◆ minMessageSize()

virtual size_t ts::CipherChaining::minMessageSize ( ) const
pure virtual

◆ residueAllowed()

virtual bool ts::CipherChaining::residueAllowed ( ) const
pure virtual

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.

Implemented in ts::DVBCSA2, ts::DVS042< CIPHER >, ts::DVS042< AES >, ts::DVS042< DES >, ts::CTR< CIPHER >, ts::CTR< ts::AES >, ts::CBC< CIPHER >, ts::CTS1< CIPHER >, ts::CBC< ts::AES >, ts::CBC< AES >, ts::CTS3< CIPHER >, ts::CTS2< CIPHER >, ts::CTS4< CIPHER >, and ts::ECB< CIPHER >.

◆ setKeyImpl()

virtual bool ts::CipherChaining::setKeyImpl ( const void *  key,
size_t  key_length,
size_t  rounds 
)
overrideprotectedvirtual

Schedule a new key (implementation of algorithm-specific part).

Parameters
[in]keyAddress of key value.
[in]key_lengthKey length in bytes.
[in]roundsRequested number of rounds. If zero, the default is used.
Returns
True on success, false on error.

Implements ts::BlockCipher.

Reimplemented in ts::DVBCSA2.

◆ name()

◆ setKey()

bool ts::BlockCipher::setKey ( const void *  key,
size_t  key_length,
size_t  rounds = 0 
)
inherited

Schedule a new key.

Parameters
[in]keyAddress of key value.
[in]key_lengthKey length in bytes.
[in]roundsRequested number of rounds. If zero, the default is used.
Returns
True on success, false on error.

◆ getKey()

bool ts::BlockCipher::getKey ( ByteBlock key) const
inherited

Get the current key.

Parameters
[out]keyCurrent key value.
Returns
True on success, false if the key is unset or invalid.

◆ encrypt()

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

Encrypt one block of 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.

Parameters
[in]plainAddress of plain text.
[in]plain_lengthPlain text length in bytes.
[out]cipherAddress of buffer for cipher text.
[in]cipher_maxsizeSize of cipher buffer.
[out]cipher_lengthReturned 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 
)
inherited

Decrypt one block of 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.

Parameters
[in]cipherAddress of cipher text.
[in]cipher_lengthCipher text length in bytes.
[out]plainAddress of buffer for plain text.
[in]plain_maxsizeSize of plain buffer.
[out]plain_lengthReturned actual size of plain text. Ignored if zero.
Returns
True on success, false on error.

◆ encryptInPlace()

bool ts::BlockCipher::encryptInPlace ( void *  data,
size_t  data_length,
size_t *  max_actual_length = nullptr 
)
inherited

Encrypt one block of data in place.

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.

Parameters
[in,out]dataAddress of data buffer to encrypt.
[in]data_lengthInput plain text length in bytes.
[in,out]max_actual_lengthOptional, ignored if zero. On input, contain the maximum size of the data buffer, which can be larger than data_length. On output, receive the actual size of the encrypted data. For pure block ciphers, this is the same as data_length. For cipher chainings with padding, this can be larger.
Returns
True on success, false on error.

◆ decryptInPlace()

bool ts::BlockCipher::decryptInPlace ( void *  data,
size_t  data_length,
size_t *  max_actual_length = nullptr 
)
inherited

Decrypt one block of data in place.

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.

Parameters
[in,out]dataAddress of data buffer to decrypt.
[in]data_lengthInput cipher text length in bytes.
[in,out]max_actual_lengthOptional, ignored if zero. On input, contain the maximum size of the data buffer, which can be larger than data_length. On output, receive the actual size of the decrypted data. For pure block ciphers, this is the same as data_length. For cipher chainings with padding, this can be smaller.
Returns
True on success, false on error.

◆ encryptionCount()

size_t ts::BlockCipher::encryptionCount ( ) const
inlineinherited

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
inlineinherited

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)
inlineinherited

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

The default initial value is UNLIMITED.

Parameters
[in]countThe maximum number of times a key should be used for encryption.

◆ setDecryptionMax()

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

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

The default initial value is UNLIMITED.

Parameters
[in]countThe maximum number of times a key should be used for decryption.

◆ encryptionMax()

size_t ts::BlockCipher::encryptionMax ( ) const
inlineinherited

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
inlineinherited

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)
inlineinherited

Set the handler to be notified on alert.

Only one handler can be set at a time.

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

◆ setCipherId()

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

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]idApplication-defined cipher id to assign.

◆ cipherId()

int ts::BlockCipher::cipherId ( ) const
inlineinherited

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

Returns
The application-defined cipher id.

◆ encryptImpl()

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

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

Parameters
[in]plainAddress of plain text.
[in]plain_lengthPlain text length in bytes.
[out]cipherAddress of buffer for cipher text.
[in]cipher_maxsizeSize of cipher buffer.
[out]cipher_lengthReturned actual size of cipher text. Ignored if zero.
Returns
True on success, false on error.

Implemented in ts::DVBCSA2, ts::DVS042< CIPHER >, ts::DVS042< AES >, ts::DVS042< DES >, ts::CTR< CIPHER >, ts::CTR< ts::AES >, ts::CBC< CIPHER >, ts::CTS1< CIPHER >, ts::CBC< ts::AES >, ts::CBC< AES >, ts::CTS3< CIPHER >, ts::CTS2< CIPHER >, ts::CTS4< CIPHER >, ts::AES, ts::ECB< CIPHER >, ts::DES, and ts::TDES.

◆ decryptImpl()

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

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

Parameters
[in]cipherAddress of cipher text.
[in]cipher_lengthCipher text length in bytes.
[out]plainAddress of buffer for plain text.
[in]plain_maxsizeSize of plain buffer.
[out]plain_lengthReturned actual size of plain text. Ignored if zero.
Returns
True on success, false on error.

Implemented in ts::DVBCSA2, ts::DVS042< CIPHER >, ts::DVS042< AES >, ts::DVS042< DES >, ts::CTR< CIPHER >, ts::CTR< ts::AES >, ts::CBC< CIPHER >, ts::CBC< ts::AES >, ts::CBC< AES >, ts::CTS1< CIPHER >, ts::CTS3< CIPHER >, ts::CTS2< CIPHER >, ts::CTS4< CIPHER >, ts::AES, ts::ECB< CIPHER >, ts::DES, and ts::TDES.

◆ encryptInPlaceImpl()

virtual bool ts::BlockCipher::encryptInPlaceImpl ( void *  data,
size_t  data_length,
size_t *  max_actual_length 
)
protectedvirtualinherited

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

The default implementation is to call encryptImpl() and copy the data. A subclass may provide a more efficient implementation.

Parameters
[in,out]dataAddress of data buffer to encrypt.
[in]data_lengthInput plain text length in bytes.
[in,out]max_actual_lengthOptional, ignored if zero. On input, contain the maximum size of the data buffer, which can be larger than data_length. On output, receive the actual size of the encrypted data. For pure block ciphers, this is the same as data_length. For cipher chainings with padding, this can be larger.
Returns
True on success, false on error.

Reimplemented in ts::DVBCSA2.

◆ decryptInPlaceImpl()

virtual bool ts::BlockCipher::decryptInPlaceImpl ( void *  data,
size_t  data_length,
size_t *  max_actual_length 
)
protectedvirtualinherited

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

The default implementation is to call decryptImpl() and copy the data. A subclass may provide a more efficient implementation.

Parameters
[in,out]dataAddress of data buffer to decrypt.
[in]data_lengthInput cipher text length in bytes.
[in,out]max_actual_lengthOptional, ignored if zero. On input, contain the maximum size of the data buffer, which can be larger than data_length. On output, receive the actual size of the decrypted data. For pure block ciphers, this is the same as data_length. For cipher chainings with padding, this can be smaller.
Returns
True on success, false on error.

Reimplemented in ts::DVBCSA2.


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