TSDuck v3.38-3675
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::TDES Class Reference

Triple-DES block cipher. More...

#include <tsTDES.h>

Inheritance diagram for ts::TDES:
Collaboration diagram for ts::TDES:

Public Member Functions

 TDES ()
 Constructor.
 
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 ByteBlockcurrentIV () const
 Get the current initialization vector.
 
const ByteBlockcurrentKey () 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 BLOCK_SIZE = 8
 TDES block size in bytes (same as DES).
 
static constexpr size_t KEY_SIZE = 24
 TDES key size in bytes (3 DES keys).
 
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

 TDES (const BlockCipherProperties &props)
 Constructor for subclasses which add some properties, such as chaining mode.
 
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 override
 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).
 

Static Protected Member Functions

static const BlockCipherPropertiesPROPERTIES ()
 Properties of this algorithm.
 

Protected Attributes

const BlockCipherPropertiesproperties
 Properties for this block cipher object instance.
 
ByteBlock work {}
 Temporary working buffer.
 

Detailed Description

Triple-DES block cipher.

Constructor & Destructor Documentation

◆ TDES()

ts::TDES::TDES ( const BlockCipherProperties props)
protected

Constructor for subclasses which add some properties, such as chaining mode.

Parameters
[in]propsConstant reference to a block of properties of this block cipher.

Member Function Documentation

◆ PROPERTIES()

static const BlockCipherProperties & ts::TDES::PROPERTIES ( )
inlinestaticprotected

Properties of this algorithm.

Returns
A constant reference to the properties.

◆ getAlgorithm() [1/2]

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

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

Parameters
[out]algoHandle to hash algorithm.
[out]lengthLength in bytes of the subobject to allocate.
[out]ignore_ivThe IV shall not be passed to BCrypt.

Reimplemented from ts::BlockCipher.

◆ name()

UString ts::BlockCipher::name ( ) const
inherited

Algorithm name (informational only).

Returns
The algorithm name.

◆ blockSize()

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

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
inlineinherited

Minimum key sizes in bytes.

Returns
The minimum key sizes in bytes.

◆ maxKeySize()

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

Maximum key sizes in bytes.

Returns
The maximum key sizes in bytes.

◆ isValidKeySize()

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

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.

◆ isValidIVSize()

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

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

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

◆ hasChainingMode()

bool ts::BlockCipher::hasChainingMode ( ) const
inlineinherited

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
inlineinherited

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
inlineinherited

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
inlineinherited

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
inlineinherited

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

Schedule a new key and optional initialization vector.

Parameters
[in]keyAddress of key value.
[in]key_lengthKey length in bytes.
[in]ivAddress of IV value (for chaining mode only).
[in]iv_lengthIV length in bytes (for chaining mode only).
Returns
True on success, false on error.

◆ setKey() [2/3]

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

Schedule a new key.

Parameters
[in]keyKey value.
Returns
True on success, false on error.

◆ setKey() [3/3]

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

Schedule a new key and initialization vector.

Parameters
[in]keyKey value.
[in]ivIV 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 
)
inherited

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]ivAddress of IV value (for chaining mode only).
[in]iv_lengthIV length in bytes (for chaining mode only).
Returns
True on success, false on error.

◆ setIV() [2/2]

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

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]ivIV value (for chaining mode only).
Returns
True on success, false on error.

◆ hasKey()

bool ts::BlockCipher::hasKey ( ) const
inlineinherited

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
inlineinherited

Get the current key.

Returns
A constant reference to the current key value.

◆ currentIV()

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

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

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]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 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]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.

◆ 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.

◆ setKeyImpl()

virtual bool ts::BlockCipher::setKeyImpl ( )
protectedvirtualinherited

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

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]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.

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

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]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.

Reimplemented in ts::DVBCSA2.

◆ canProcessInPlace()

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

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_doIf true, encrypt and decrypt in place is possible.

◆ getAlgorithm() [2/2]

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

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

Returns
EVP cipher.

Member Data Documentation

◆ properties

const BlockCipherProperties& ts::BlockCipher::properties
protectedinherited

Properties for this block cipher object instance.

Accessible to subclasses, but constant.


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