DVB CSA-2 (Digital Video Broadcasting Common Scrambling Algorithm). More...

#include <tsDVBCSA2.h>

Inheritance diagram for ts::DVBCSA2:

Collaboration diagram for ts::DVBCSA2:

[legend]

Public Types
enum	EntropyMode { FULL_CW , REDUCE_ENTROPY }
	Control word entropy reduction. More...

Public Member Functions
	DVBCSA2 (EntropyMode mode=REDUCE_ENTROPY)
	Default 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 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.

EntropyMode	entropyMode () const
	Get the entropy mode, used in setKey().

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.

void	setEntropyMode (EntropyMode mode)
	Set the entropy mode, used in setKey().

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 Member Functions
static bool	IsReducedCW (const uint8_t *cw)
	Check if a control word is entropy-reduced.

static void	ReduceCW (uint8_t *cw)
	Manually perform the entropy reduction on a control word.

Static Public Attributes
static constexpr size_t	BLOCK_SIZE = 8
	DVB CSA-2 block size in bytes (informational only, not relevant to scrambling).

static constexpr size_t	KEY_BITS = 64
	DVB CSA-2 control words size in bits.

static constexpr size_t	KEY_SIZE = KEY_BITS / 8
	DVB CSA-2 control words size in bytes.

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
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) override
	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) override
	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 () override
	Schedule a new key and optional initialization vector (implementation of algorithm-specific part).

Static Protected Member Functions
static const BlockCipherProperties &	PROPERTIES ()
	Properties of this algorithm.

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

ByteBlock	work {}
	Temporary working buffer.

Detailed Description

DVB CSA-2 (Digital Video Broadcasting Common Scrambling Algorithm).

Member Enumeration Documentation

◆ EntropyMode

enum ts::DVBCSA2::EntropyMode

Control word entropy reduction.

This is a way to reduce the 'entropy' of control words to 48 bits, according to DVB regulations.

Enumerator
FULL_CW	Keep the full 64-bit control word.
REDUCE_ENTROPY	Reduce the entropy of the control word to 48 bits.

Constructor & Destructor Documentation

◆ DVBCSA2()

ts::DVBCSA2::DVBCSA2 ( EntropyMode mode = REDUCE_ENTROPY )

Default Constructor.

Parameters

[in] mode Entropy reduction mode.

Member Function Documentation

◆ setEntropyMode()

void ts::DVBCSA2::setEntropyMode ( EntropyMode mode )

inline

Set the entropy mode, used in setKey().

Parameters

[in] mode Entropy reduction mode.

◆ entropyMode()

EntropyMode ts::DVBCSA2::entropyMode ( ) const

inline

Get the entropy mode, used in setKey().

Returns: The entropy reduction mode.

◆ ReduceCW()

static void ts::DVBCSA2::ReduceCW ( uint8_t * cw )

static

Manually perform the entropy reduction on a control word.

Not needed with ts::DVBCSA2 class, preferably use REDUCE_ENTROPY mode.

Parameters

[in,out] cw Address of a control word to reduce. Its size must be ts::DVBCSA2::KEY_SIZE.

◆ IsReducedCW()

static bool ts::DVBCSA2::IsReducedCW ( const uint8_t * cw )

static

Check if a control word is entropy-reduced.

Parameters

[in] cw Address of a control word. Its size must be ts::DVBCSA2::KEY_SIZE.

Returns: True if reduced, false if not.

◆ PROPERTIES()

static const BlockCipherProperties & ts::DVBCSA2::PROPERTIES ( )

inlinestaticprotected

Properties of this algorithm.

Returns: A constant reference to the properties.

◆ setKeyImpl()

virtual bool ts::DVBCSA2::setKeyImpl ( )

overrideprotectedvirtual

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 from ts::BlockCipher.

◆ encryptImpl()

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

overrideprotectedvirtual

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 from ts::BlockCipher.

◆ decryptImpl()

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

overrideprotectedvirtual

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

virtualinherited

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

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

inlineinherited

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
	)

inlineinherited

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
	)

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

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] iv IV 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]	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`
	)

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

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] count The 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] count The 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] handler Handler 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] id Application-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.

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

protectedvirtualinherited

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

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:

tsDVBCSA2.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ EntropyMode

Constructor & Destructor Documentation

◆ DVBCSA2()

Member Function Documentation

◆ setEntropyMode()

◆ entropyMode()

◆ ReduceCW()

◆ IsReducedCW()

◆ PROPERTIES()

◆ setKeyImpl()

◆ encryptImpl()

◆ decryptImpl()

◆ 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()

◆ canProcessInPlace()

◆ getAlgorithm() [1/2]

◆ getAlgorithm() [2/2]

Member Data Documentation

◆ properties