Skip to content

Latest commit

 

History

History
909 lines (606 loc) · 23 KB

cipher.md

File metadata and controls

909 lines (606 loc) · 23 KB

Cipher

The Cipher class handles all encryption and decryption including AEAD as well as provides various information about selecte cipher algorithm.

Constants

Cipher::MODE_CBC

The CBC (Cipher Block Chaining) mode XOR's the previous block with the currently en/decrypted one. It requires random IV to be set.

Cipher::MODE_CCM

The CCM (Counter with CBC-MAC) is an authenticated mode. It requires a length pre-initialization which means that a plain resp. cipher text must be known before encryption resp. decryption. That makes it unsituable for streams or continuous cipher update.

Encryption is done using CTR (Counter) mode which means that a supplied nonce and counter is used. The nonce is passed as an IV. The default tag size is 16 bytes.

Cipher::MODE_CFB

The CFB (Cipher FeedBack) mode makes a block ciphper into a self-synchronizing stream cipher.

Cipher::MODE_CTR

The CTR (CounTeR) mode uses counter and a random nonce.

Cipher::MODE_ECB

The ECB (Electronic Codebook) mode is an insecure mode susceptible on replay attack if a message length is greater than a block length.

Cipher::MODE_GCM

The GCM (Golias Counter Mode) is an authenticated mode.

Cipher::MODE_OFB

The OFB (Output FeedBack) mode makes a block cipher into a synchronous stream cipher

Cipher::MODE_XTS

The XTS (XEX-based tweaked codebook mode with ciphertext stealing) mode is a mode designed for hard disk storage.

Static Methods

Cipher::__callStatic($name, $arguments)

Description: Creates a cipher using a static call syntax.

The usage of __callStatic magic method allows simplified syntax for creating a Cipher object (e.g. Cipher::aes(Crypto\Cipher::MODE_CBC, 128)). The $name depicts the algorithm which is checked if it's found. If not then CipherException is thrown. Otherwise the new Cipher instance is returned.

Parameters

name : string - the algorithm name (e.g. aes)

arguments : array - there should be an algorithm mode and key size (if supported by algorithm)

Return value

Cipher: New instances of the class.

Throws

It can throw CipherException with code

  • CipherException::ALGORITHM_NOT_FOUND - the algorithm (name) is not found
Examples
$cipher = \Crypto\Cipher::aes(\Crypto\Cipher::MODE_CBC, 128);

Cipher::getAlgorithms($aliases = false, $prefix = null)

Description: Returns all cipher algorithms.

This static method returns all cipher algorithms. Their parameters allow filtering of the result. Some algorithms have aliases that can be returned if the $aliases parameter is true. The $prefix allows filtering by the supplied prefix string.

Parameters

aliases : bool - whether to show aliases prefix : string - prefix that is used for filtering of the result

Throws

This method does not throw any exception.

Return value

array: list of supported cipher alorithms

Examples
print_r(\Crypto\Cipher::getAlgorithms());

Cipher::hasAlgorithm($algorithm)

Description: Finds out wheter the supplied algorithm is supported

This static method checks if the supplied cipher algorithm is supported.

Parameters

algorithm : string - algorithm name

Throws

This method does not throw any exception.

Return value

bool: if the algorithm is supperted, returns true, otherwise false

Examples
if (\Crypto\Cipher::hasAlgorithm('aes-128-ccm')) {
    // use AES wiht CCM mode
}

Cipher::hasMode($mode)

Description: Finds out wheter the supplied mode is supported

This static method checks if the supplied cipher mode is supported. The $mode parameter must be one of the mode cipher constant defined in Cipher class.

Parameters

mode : int - mode constant

Throws

This method does not throw any exception.

Return value

bool: if the mode is supperted, returns true, otherwise false

Examples
if (\Crypto\Cipher::hasMode(\Crypto\Cipher::MODE_CCM)) {
    // use CCM mode
}

Instance Methods

Cipher::__construct($algorithm, $mode = NULL, $key_size = NULL)

Description: Creates a new cipher object

The constructor allows creating an object using two ways. Either algorithm name is a string containing all details (algorithm, mode, key size) or it is just a name of the block algorithm (e.g. AES) followed by mode Cipher class constant and, if algorithm allows that, then key size. Internally the name is concatened to the first form so the result is the same. The final algorithm name is then checked if it is supported. If not, then the CipherException is thrown.

Parameters

algorithm : string - algorithm name

mode : int - mode constant

key_size : int - algorithm key size

Throws

It can throw CipherException with code

  • CipherException::ALGORITHM_NOT_FOUND - the algorithm (name) is not found
Return value

Cipher: new cipher object

Examples

Creating cipher using just algorithm parameter

$cipher = new \Crypto\Cipher('AES-128-GCM');

Creating cipher using composed parameters

use Crypto\Cipher;

$cipher = new Cipher('AES', Cipher::MODE_GCM, 128);

Cipher::decrypt($data, $key, $iv = null)

Description: Decrypts encrypted data using key and IV

This method decrypts encrypted data (cipher text) on the Cipher object. It uses a supplied key $key and an initial vector $iv for decryption. Internally it calls init, update and finish operations on cipher context. If any of them fails, a CipherException with an appropriate code is thrown.

The key resp. IV parameters has to contain an exact number of bytes that is returned by Cipher::getKeyLength resp. Cipher::getIVLength(). If it's not the case, then a CipherException is thrown.

Parameters

data : string - cipher text

key : string - key

iv : string - initial vector

Throws

It can throw CipherException with code

  • CipherException::INIT_ALG_FAILED - initialization of cipher algorithm failed
  • CipherException::INIT_CTX_FAILED - initialization of cipher context failed
  • CipherException::UPDATE_FAILED - updating of decryption failed
  • CipherException::FINISH_FAILED - finalizing of decryption failed
  • CipherException::INPUT_DATA_LENGTH_HIGH - if the data length exceeds C INT_MAX
  • CipherException::KEY_LENGTH_INVALID - the key length is invalid
  • CipherException::IV_LENGTH_INVALID - the IV length is invalid
  • CipherException::TAG_VERIFY_FAILED - tag verification failed (only for GCM or CCM mode)
Return value

string: The decrypted plain text.

Examples
$cipher = new \Crypto\Cipher('AES-128-GCM');
echo $cipher->decrypt($msg, $key, $iv);

Cipher::decryptFinish()

Description: Finalizes a decryption

This method decrypts an outstanding incomplete block if there is any such block in cipher context. It also closes the context so the update cannot be called again unless the object is again initialized. In addition it finishes the authentication for GCM mode.

If the operation fails (e.g. verification fails), then CipherException is thrown. The same exception with different code is thrown if the context has not been initialized for decryption before.

Parameters

This method has no parameters.

Throws

It can throw CipherException with code

  • CipherException::FINISH_FAILED - finalizing of decryption failed
  • CipherException::FINISH_DECRYPT_FORBIDDEN - cipher has not been initialized for decryption
  • CipherException::TAG_VERIFY_FAILED - tag verification failed (only for GCM or CCM mode)
Return value

string: The decrypted data (plain text) from the last incomplets block or empty string.

Examples
$cipher = new \Crypto\Cipher('AES-128-CTR');
$cipher->decryptInit($key, $iv);
$ct = $cipher->decryptUpdate($msg);
$ct .= $cipher->decryptFinish();

Cipher::decryptInit($key, $iv = null)

Description: Initializes cipher decryption

This method initializes decryption on the Cipher object. It uses a supplied key $key and an initial vector $iv. If the initialization fails, a CipherException with an appropriate code is thrown.

The key resp. IV parameters has to contain an exact number of bytes that is returned by Cipher::getKeyLength resp. Cipher::getIVLength(). If it's not the case, then a CipherException is thrown.

Parameters

key : string - key

iv : string - initial vector

Throws

It can throw CipherException with code

  • CipherException::INIT_ALG_FAILED - initialization of cipher algorithm failed
  • CipherException::INIT_CTX_FAILED - initialization of cipher context failed
  • CipherException::KEY_LENGTH_INVALID - the key length is invalid
  • CipherException::IV_LENGTH_INVALID - the IV length is invalid
Return value

null: Nothing is returned.

Examples
$cipher = new \Crypto\Cipher('AES-128-CBC');
try {
    $cipher->decryptInit($key, $iv);
} catch (\Crypto\CipherException $ex) {
    switch ($ex->getCode()) {
        case \Crypto\CipherException::KEY_LENGTH_INVALID:
            echo "You need to set a correct key length";
            break;
        case \Crypto\CipherException::IV_LENGTH_INVALID:
            echo "You need to set a correct IV length";
            break;
        default:
            echo $ex->getMessage();
            break;
    }
}

Cipher::decryptUpdate($data)

Description: Updates decryption context with data and returns encrypted blocks.

This method decrypts encrypted data (cipher text) on the Cipher object. It updates an initialized context and all encrypted blocks are returned. If the context is not initialized using Cipher::decryptInit, then a CipherException is thrown.

If the decryption fails, a CipherException is thrown.

Parameters

data : string - cipher text

Throws

It can throw CipherException with code

  • CipherException::UPDATE_FAILED - updating of decryption failed
  • CipherException::INPUT_DATA_LENGTH_HIGH - if the data length exceeds C INT_MAX
  • CipherException::UPDATE_DECRYPT_FORBIDDEN - cipher has not been initialized for decryption
  • CipherException::TAG_VERIFY_FAILED - tag verification failed (only for GCM or CCM mode)
Return value

string: The decrypted plain text.

Examples
$cipher = new \Crypto\Cipher('AES-128-CTR');
$cipher->decryptInit($key, $iv);
$plain_text = "";
while (($data = read_data_from_somewhere()) !== false) {
    $plain_text .= $cipher->decryptUpdate($msg);
}
$plain_text .= $cipher->decryptFinish();

Cipher::encrypt($data, $key, $iv = null)

Description: Encrypts data using key and IV

This method encrypts data (plain text) on the Cipher object. It uses a supplied key $key and an initial vector $iv for encryption. Internally it calls init, update and finish operations on cipher context. If any of them fails, a CipherException with an appropriate code is thrown.

The key resp. IV parameters has to contain an exact number of bytes that is returned by Cipher::getKeyLength resp. Cipher::getIVLength(). If it's not the case, then a CipherException is thrown.

Parameters

data : string - plain text

key : string - key

iv : string - initial vector

Throws

It can throw CipherException with code

  • CipherException::INIT_ALG_FAILED - initialization of cipher algorithm failed
  • CipherException::INIT_CTX_FAILED - initialization of cipher context failed
  • CipherException::UPDATE_FAILED - updating of encryption failed
  • CipherException::FINISH_FAILED - finalizing of encryption failed
  • CipherException::INPUT_DATA_LENGTH_HIGH - if the data length exceeds C INT_MAX
  • CipherException::KEY_LENGTH_INVALID - the key length is invalid
  • CipherException::IV_LENGTH_INVALID - the IV length is invalid
Return value

string: The encrypted cipher text.

Examples
$cipher = new \Crypto\Cipher('AES-128-CTR');
echo $cipher->encrypt($cipher_text, $key, $iv);

Cipher::encryptFinish()

Description: Finalizes encryption

This method encrypts an outstanding incomplete block including padding if there is any such block in cipher context and/or padding is required. It also closes the context so the update cannot be called again unless the object is again initialized.

If the operation fails (e.g. verification fails), then CipherException is thrown. The same exception with different code is thrown if the context has not been initialized for decryption before.

Parameters

This method has no parameters.

Throws

It can throw CipherException with code

  • CipherException::FINISH_FAILED - finalizing of encryption failed
  • CipherException::FINISH_ENCRYPT_FORBIDDEN - cipher has not been initialized for encryption
Return value

string: The encrypted data (cipher text) from the last incomplete block with padding or empty string.

Examples
$cipher = new \Crypto\Cipher('AES-128-CTR');
$cipher->encryptInit($key, $iv);
$plain_text = $cipher->encryptUpdate($cipher_text);
$plain_text .= $cipher->encryptFinish();

Cipher::encryptInit($key, $iv = null)

Description: Initializes cipher encryption

This method initializes encryption on the Cipher object. It uses a supplied key $key and an initial vector $iv. If the initialization fails, a CipherException with an appropriate code is thrown.

The key resp. IV parameters has to contain an exact number of bytes that is returned by Cipher::getKeyLength resp. Cipher::getIVLength(). If it's not the case, then a CipherException is thrown.

Parameters

key : string - key

iv : string - initial vector

Throws

It can throw CipherException with code

  • CipherException::INIT_ALG_FAILED - initialization of cipher algorithm failed
  • CipherException::INIT_CTX_FAILED - initialization of cipher context failed
  • CipherException::KEY_LENGTH_INVALID - the key length is invalid
  • CipherException::IV_LENGTH_INVALID - the IV length is invalid
Return value

null: Nothing is returned.

Examples
$cipher = new \Crypto\Cipher('AES-128-CBC');
try {
    $cipher->encryptInit($key, $iv);
} catch (\Crypto\CipherException $ex) {
    switch ($ex->getCode()) {
        case \Crypto\CipherException::KEY_LENGTH_INVALID:
            echo "You need to set a correct key length";
            break;
        case \Crypto\CipherException::IV_LENGTH_INVALID:
            echo "You need to set a correct IV length";
            break;
        default:
            echo $ex->getMessage();
            break;
    }
}

Cipher::encryptUpdate($data)

Description: Updates encryption context with data and returns encrypted blocks.

This method encrypts data (plain text) on the Cipher object. It updates an initialized context and all encrypted blocks are returned (if any). If the context is not initialized using Cipher::encryptInit, then a CipherException is thrown.

If the decryption fails, a CipherException is thrown.

Parameters

data : string - plain text

Throws

It can throw CipherException with code

  • CipherException::UPDATE_FAILED - updating of encryption failed
  • CipherException::INPUT_DATA_LENGTH_HIGH - if the data length exceeds C INT_MAX
  • CipherException::UPDATE_DECRYPT_FORBIDDEN - cipher has not been initialized for encryption
Return value

string: The encrypted cipher text.

Examples
$cipher = new \Crypto\Cipher('AES-128-CTR');
$cipher->decryptInit($key, $iv);
$cipher_text = "";
while (($data = read_data_from_somewhere()) !== false) {
    $cipher_text .= $cipher->encryptUpdate($msg);
}
$cipher_text .= $cipher->encryptFinish();

Cipher::getAlgorithmName()

Description: Returns a cipher algorithm name.

It is a getter for internal Cipher::$algorithm read only property which is set during the object creation.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

string: The name of the cipher algorithm and additional info like a mode (e.g. AES-128-CTR)

Examples
$cipher = new \Crypto\Cipher('aes-128-ctr');
// this will output AES-128-CTR
echo $cipher->getAlgorithmName();

Cipher::getBlockSize()

Description: Returns a cipher block size in bytes.

This method returns a block size of the cipher algorithm.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

int: The cipher block size in bytes.

Examples
$cipher = new \Crypto\Cipher('aes-128-ctr');
// this will output 16
echo $cipher->getBlockSize();

Cipher::getIVLength()

Description: Returns a cipher IV length in bytes.

This method returns an initial vector length of the cipher algorithm. The IV length depends on the selected mode. This is also applicable on modes that are based on CTR mode which requires a nonce. The nonce length is returned in this case.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

int: The cipher IV length in bytes.

Examples
$cipher = new \Crypto\Cipher('aes-128-ctr');
// this will output 16
echo $cipher->getIVLength();

Cipher::getKeyLength()

Description: Returns a cipher key length in bytes.

This method returns a key length of the cipher algorithm. The key length depends on the cipher where some ciphers support more key lengths (e.g. AES) that can be specified in the algorithm name or as a parameter of the cipher constructor.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

int: The cipher key length in bytes.

Examples
$cipher = new \Crypto\Cipher('aes-192-ctr');
// this will output 24
echo $cipher->getKeyLength();

Cipher::getMode()

Description: Returns a cipher mode constant value.

This method returns a Cipher class constant value for the used mode. It's identified from the algorithm name passed to the constructor.

Parameters

This method has no parameters.

Throws

This method does not throw any exception.

Return value

int: The cipher mode constant value.

Examples
$cipher = new \Crypto\Cipher('aes-128-ctr');
$mode = $cipher->getMode();
// this will be true
if ($mode === \Crypto\Cipher::MODE_CTR) {
    echo "Mode is CTR";
}

Cipher::getTag()

Description: Returns an authentication tag.

This method returns a message authentication tag. It can be used only for modes that supports that (GCM and CCM) and only after encryption is finished. In any other case, CipherException is thrown.

The returned tag length can be set by Cipher::setTagLength before encryption. If it's not set, then the defualt length is 16.

Parameters

This method has no parameters.

Throws

It can throw CipherException with code

  • CipherException::AUTHENTICATION_NOT_SUPPORTED - mode is not an authenticated mode
  • CipherException::TAG_GETTER_FORBIDDEN - method is not called after finishing encryption
  • CipherException::TAG_GETTER_FAILED - getting tag failed
Return value

string: The authenticated tag.

Examples
$cipher = new \Crypto\Cipher('aes-128-gcm');
$cipher_text = $cipher->encrypt($plain_text, $key, $iv);
$tag = $cipher->getTag();

Cipher::setAAD($aad)

Description: Sets an additional application data.

This method sets an additional application data (AAD). It can be used only for authenticated modes (GCM and CCM) and only before encryption or decryption is updated (any data are encrypted or decrypted). In any other case, a CipherException is thrown.

Parameters

aad : string - additional application data

Throws

It can throw CipherException with code

  • CipherException::AUTHENTICATION_NOT_SUPPORTED - mode is not an authenticated mode
  • CipherException::AAD_SETTER_FORBIDDEN - method is not called before encryption or decryption
  • CipherException::AAD_LENGTH_HIGH - if the AAD length exceeds C INT_MAX
Return value

bool: true if the AAD was set succesfully

Examples
// encrypt
$cipher = new \Crypto\Cipher('aes-128-gcm');
$cipher->setAAD($aad);
$cipher_text = $cipher->encrypt($plain_text, $key, $iv);
$tag = $cipher->getTag();

// later you have to decrypt with the same AAD
$cipher = new \Crypto\Cipher('aes-128-gcm');
$cipher->setAAD($aad);
$cipher->setTag($tag);
$plain_text = $cipher->decrypt($cipher_text, $key, $iv);

Cipher::setTag($tag)

Description: Sets a message authentication tag.

This method sets a message authentication tag. It can be used only for authenticated modes (GCM and CCM) and only before decryption is updated (any data are decrypted). In any other case, a CipherException is thrown.

The tag length has to be between 4 and 16 bytes, otherwise a CipherException is thrown.

Parameters

tag : string - message authentication tag

Throws

It can throw CipherException with code

  • CipherException::AUTHENTICATION_NOT_SUPPORTED - mode is not an authenticated mode
  • CipherException::TAG_SETTER_FORBIDDEN - method is not called before decryption
  • CipherException::TAG_LENGTH_LOW - if tag length is less than 4 bytes
  • CipherException::TAG_LENGTH_HIGH - if tag length is more than 16 bytes
Return value

bool: true if the tag was set succesfully

Examples
$cipher = new \Crypto\Cipher('aes-128-gcm');
$cipher->setTag($tag);
$plain_text = $cipher->decrypt($cipher_text, $key, $iv);

Cipher::setTagLength($tag_length)

Description: Sets a message authentication tag length.

This method sets a length for an authentication tag that is later returned using Cipher::getTag. It can be used only for authenticated modes (GCM and CCM) and only before encryption is updated (any data are encrypted). In any other case, a CipherException is thrown.

The tag length has to be between 4 and 16 bytes, otherwise a CipherException is thrown.

The method is useful only if there is a requirement of different tag length than the default which is 16 bytes. The tag is just trimmed for GCM mode. However it's a completely different tag if it's used with CCM mode.

Parameters

length : int - message authentication tag length

Throws

It can throw CipherException with code

  • CipherException::AUTHENTICATION_NOT_SUPPORTED - mode is not an authenticated mode
  • CipherException::TAG_SETTER_FORBIDDEN - method is not called before encryption
  • CipherException::TAG_LENGTH_LOW - if tag length is less than 4 bytes
  • CipherException::TAG_LENGTH_HIGH - if tag length is more than 16 bytes
Return value

bool: true if the tag length was set succesfully

Examples
$cipher = new \Crypto\Cipher('aes-128-ccm');
$cipher->setTagLength(12);
$cipher_text = $cipher->encrypt($plain_text, $key, $nonce);
// tag with lenth 12 bytes (characters)
$tag = $cipher->getTag();