Cipher algorithm definitions for the PSA Crypto API. More...

Detailed Description

Cipher algorithm definitions for the PSA Crypto API.

Author: Armin Wolf wolf..nosp@m.armi.nosp@m.n@mai.nosp@m.lbox.nosp@m..tu-d.nosp@m.resd.nosp@m.en.de; Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

Definition in file algorithm.h.

#include "psa/algorithm.h"

Include dependency graph for algorithm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define	PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000)
	Category for cipher algorithms.

#define	PSA_ALG_IS_CIPHER(alg) (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)
	Whether the specified algorithm is a symmetric cipher algorithm.

#define	PSA_ALG_IS_STREAM_CIPHER(alg) (((alg) & 0x7f800000) == 0x04800000)
	Whether the specified algorithm is a stream cipher.

#define	PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800100)
	The stream cipher mode of a stream cipher algorithm.

#define	PSA_ALG_CTR ((psa_algorithm_t)0x04c01000)
	A stream cipher built using the Counter (CTR) mode of a block cipher.

#define	PSA_ALG_CFB ((psa_algorithm_t)0x04c01100)
	A stream cipher built using the Cipher Feedback (CFB) mode of a block cipher.

#define	PSA_ALG_OFB ((psa_algorithm_t)0x04c01200)
	A stream cipher built using the Output Feedback (OFB) mode of a block cipher.

#define	PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00)
	The XEX with Ciphertext Stealing (XTS) cipher mode of a block cipher.

#define	PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t)0x04404000)
	The Cipher Block Chaining (CBC) mode of a block cipher, with no padding.

#define	PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04404100)
	The Cipher Block Chaining (CBC) mode of a block cipher, with PKCS#7 padding.

#define	PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t)0x04404400)
	The Electronic Codebook (ECB) mode of a block cipher, with no padding.

Macro Definition Documentation

◆ PSA_ALG_CATEGORY_CIPHER

#define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000)

Category for cipher algorithms.

Definition at line 34 of file algorithm.h.

◆ PSA_ALG_CBC_NO_PADDING

#define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t)0x04404000)

The Cipher Block Chaining (CBC) mode of a block cipher, with no padding.

The underlying block cipher is determined by the key type. This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block size of the chosen block cipher.

CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.

Note

The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().

     The CBC block cipher mode is defined in NIST Special Publication 800-38A:
     Recommendation for Block Cipher Modes of Operation: Methods and Techniques
     [SP800-38A](https://doi.org/10.6028/NIST.SP.800-38B).

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_AES
     - @ref PSA_KEY_TYPE_ARIA
     - @ref PSA_KEY_TYPE_DES
     - @ref PSA_KEY_TYPE_CAMELLIA
     - @ref PSA_KEY_TYPE_SM4

Definition at line 276 of file algorithm.h.

◆ PSA_ALG_CBC_PKCS7

#define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04404100)

The Cipher Block Chaining (CBC) mode of a block cipher, with PKCS#7 padding.

The underlying block cipher is determined by the key type.

     CBC mode requires an initialization vector (IV) that is the same size as the cipher
     block length.

Note

The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().

     The CBC block cipher mode is defined in NIST Special Publication 800-38A:
     Recommendation for Block Cipher Modes of Operation: Methods and Techniques
     [SP800-38A](https://doi.org/10.6028/NIST.SP.800-38B).
     The padding operation is defined by PKCS #7: Cryptographic Message Syntax Version 1.5
     [RFC2315](https://tools.ietf.org/html/rfc2315.html) §10.3.

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_AES
     - @ref PSA_KEY_TYPE_ARIA
     - @ref PSA_KEY_TYPE_DES
     - @ref PSA_KEY_TYPE_CAMELLIA
     - @ref PSA_KEY_TYPE_SM4

Definition at line 301 of file algorithm.h.

◆ PSA_ALG_CFB

#define PSA_ALG_CFB ((psa_algorithm_t)0x04c01100)

A stream cipher built using the Cipher Feedback (CFB) mode of a block cipher.

The underlying block cipher is determined by the key type. This is the variant of CFB where each iteration encrypts or decrypts a segment of the input that is the same length as the cipher block size. For example, using PSA_ALG_CFB with a key of type PSA_KEY_TYPE_AES will result in the AES-CFB-128 cipher.

CFB mode requires an initialization vector (IV) that is the same size as the cipher block length.

Note

The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().

     The CFB block cipher mode is defined in NIST Special Publication 800-38A:
     Recommendation for Block Cipher Modes of Operation: Methods and Techniques
     [SP800-38A](https://doi.org/10.6028/NIST.SP.800-38A), using a segment size s equal
     to the block size b. The definition in
     [SP800-38A](https://doi.org/10.6028/NIST.SP.800-38A) is
     extended to allow an incomplete final block of input, in which case the algorithm
     discards the final bytes of the key stream when encrypting or decrypting the final
     partial block.

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_AES
     - @ref PSA_KEY_TYPE_ARIA
     - @ref PSA_KEY_TYPE_DES
     - @ref PSA_KEY_TYPE_CAMELLIA
     - @ref PSA_KEY_TYPE_SM4

Definition at line 199 of file algorithm.h.

◆ PSA_ALG_CTR

#define PSA_ALG_CTR ((psa_algorithm_t)0x04c01000)

A stream cipher built using the Counter (CTR) mode of a block cipher.

CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type PSA_KEY_TYPE_AES and a size of 128 bits (16 bytes).

The CTR block cipher mode is defined in NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques [SP800-38A].

CTR mode requires a counter block which is the same size as the cipher block length. The counter block is updated for each block (or a partial final block) that is encrypted or decrypted.

A counter block value must only be used once across all messages encrypted using the same key value. This is typically achieved by splitting the counter block into a nonce, which is unique among all message encrypted with the key, and a counter which is incremented for each block of a message.

For example, when using AES-CTR encryption, which uses a 16-byte block, the application can provide a 12-byte nonce when setting the IV. This leaves 4 bytes for the counter, allowing up to 2^32 blocks (64GB) of message data to be encrypted in each message.

The first counter block is constructed from the initialization vector (IV). The initial counter block is is constructed in the following ways:

A call to psa_cipher_encrypt() will generate a random counter block value. This is the first block of output.
A call to psa_cipher_decrypt() will use first block of the input buffer as the initial counter block value.
A call to psa_cipher_generate_iv() on a multi-part cipher operation will generate and return a random counter block value.
A call to psa_cipher_set_iv() on a multi-part cipher operation requires an IV that is between 1 and n bytes in length, where n is the cipher block length. The counter block is initialized using the IV, and padded with zero bytes up to the block length.

During the counter block update operation, the counter block is treated as a single big-endian encoded integer and the update operation increments this integer by 1.

This scheme meets the recommendations in Appendix B of SP800-38A.

Note

The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_AES
     - @ref PSA_KEY_TYPE_ARIA
     - @ref PSA_KEY_TYPE_DES
     - @ref PSA_KEY_TYPE_CAMELLIA
     - @ref PSA_KEY_TYPE_SM4

Definition at line 168 of file algorithm.h.

◆ PSA_ALG_ECB_NO_PADDING

#define PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t)0x04404400)

The Electronic Codebook (ECB) mode of a block cipher, with no padding.

Warning: ECB mode does not protect the confidentiality of the encrypted data except in extremely narrow circumstances. It is recommended that applications only use ECB if they need to construct an operating mode that the implementation does not provide. Implementations are encouraged to provide the modes that applications need in preference to supporting direct access to ECB.

The underlying block cipher is determined by the key type.

     This symmetric cipher mode can only be used with messages whose lengths are a multiple
     of the block size of the chosen block cipher.

     ECB mode does not accept an initialization vector (IV). When using a multi-part cipher
     operation with this algorithm, @ref psa_cipher_generate_iv() and
     @ref psa_cipher_set_iv() must not be called.

Note

The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().

     The ECB block cipher mode is defined in NIST Special Publication 800-38A:
     Recommendation for Block Cipher Modes of Operation: Methods and Techniques
     [SP800-38A](https://doi.org/10.6028/NIST.SP.800-38A).

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_AES
     - @ref PSA_KEY_TYPE_ARIA
     - @ref PSA_KEY_TYPE_DES
     - @ref PSA_KEY_TYPE_CAMELLIA
     - @ref PSA_KEY_TYPE_SM4

Definition at line 334 of file algorithm.h.

◆ PSA_ALG_IS_CIPHER

#define PSA_ALG_IS_CIPHER ( alg ) (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)

Whether the specified algorithm is a symmetric cipher algorithm.

Parameters

alg	An algorithm identifier (value of type psa_algorithm_t).

Returns: 1 if alg is a symmetric cipher algorithm, 0 if algorithm is not recognized or not supported

Definition at line 44 of file algorithm.h.

◆ PSA_ALG_IS_STREAM_CIPHER

#define PSA_ALG_IS_STREAM_CIPHER ( alg ) (((alg) & 0x7f800000) == 0x04800000)

Whether the specified algorithm is a stream cipher.

A stream cipher is a symmetric cipher that encrypts or decrypts messages by applying a bitwise-xor with a stream of bytes that is generated from a key.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a stream cipher 0 otherwise

Definition at line 57 of file algorithm.h.

◆ PSA_ALG_OFB

#define PSA_ALG_OFB ((psa_algorithm_t)0x04c01200)

A stream cipher built using the Output Feedback (OFB) mode of a block cipher.

The underlying block cipher is determined by the key type.

     OFB mode requires an initialization vector (IV) that is the same size as the cipher
     block length. OFB mode requires that the IV is a nonce, and must be unique for each use
     of the mode with the same key.

Note

The cipher block length can be determined using PSA_BLOCK_CIPHER_BLOCK_LENGTH().

     The OFB block cipher mode is defined in NIST Special Publication 800-38A:
     Recommendation for Block Cipher Modes of Operation: Methods and Techniques
     [SP800-38A](https://doi.org/10.6028/NIST.SP.800-38A).

     @b Compatible @b key @b types
     - @ref PSA_KEY_TYPE_AES
     - @ref PSA_KEY_TYPE_ARIA
     - @ref PSA_KEY_TYPE_DES
     - @ref PSA_KEY_TYPE_CAMELLIA
     - @ref PSA_KEY_TYPE_SM4

Definition at line 223 of file algorithm.h.

◆ PSA_ALG_STREAM_CIPHER

#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800100)

The stream cipher mode of a stream cipher algorithm.

The underlying stream cipher is determined by the key type. The ARC4 and ChaCha20 ciphers use this algorithm identifier.

ARC4 To use ARC4, use a key type of PSA_KEY_TYPE_ARC4 and algorithm id PSA_ALG_STREAM_CIPHER.

Warning: The ARC4 cipher is weak and deprecated and is only recommended for use in legacy protocols.

The ARC4 cipher does not use an initialization vector (IV). When using a multi-part cipher operation with the PSA_ALG_STREAM_CIPHER algorithm and an ARC4 key, psa_cipher_generate_iv() and psa_cipher_set_iv() must not be called.

ChaCha20 To use ChaCha20, use a key type of PSA_KEY_TYPE_CHACHA20 and algorithm id PSA_ALG_STREAM_CIPHER.

Implementations must support the variant that is defined in ChaCha20 and Poly1305 for IETF Protocols RFC7539 §2.4, which has a 96-bit nonce and a 32-bit counter. Implementations can optionally also support the original variant, as defined in ChaCha, a variant of Salsa20 CHACHA20, which has a 64-bit nonce and a 64-bit counter. Except where noted, the RFC7539 variant must be used.

ChaCha20 defines a nonce and an initial counter to be provided to the encryption and decryption operations. When using a ChaCha20 key with the PSA_ALG_STREAM_CIPHER algorithm, these values are provided using the initialization vector (IV) functions in the following ways:

A call to psa_cipher_encrypt() will generate a random 12-byte nonce, and set the counter value to zero. The random nonce is output as a 12-byte IV value in the output.
A call to psa_cipher_decrypt() will use first 12 bytes of the input buffer as the nonce and set the counter value to zero.
A call to psa_cipher_generate_iv() on a multi-part cipher operation will generate and return a random 12-byte nonce and set the counter value to zero.
A call to psa_cipher_set_iv() on a multi-part cipher operation can support the following IV sizes:
- 12 bytes: the provided IV is used as the nonce, and the counter value is set to zero.
  - 16 bytes: the first four bytes of the IV are used as the counter value (encoded as little-endian), and the remaining 12 bytes is used as the nonce.
  - 8 bytes: the cipher operation uses the original CHACHA20 definition of ChaCha20: the provided IV is used as the 64-bit nonce, and the 64-bit counter value is set to zero.
  - It is recommended that implementations do not support other sizes of IV.

Compatible key types

Definition at line 115 of file algorithm.h.

◆ PSA_ALG_XTS

#define PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00)

The XEX with Ciphertext Stealing (XTS) cipher mode of a block cipher.

XTS is a cipher mode which is built from a block cipher, designed for use in disk encryption. It requires at least one full cipher block length of input, but beyond this minimum the input does not need to be a whole number of blocks.

XTS mode uses two keys for the underlying block cipher. These are provided by using a key that is twice the normal key size for the cipher. For example, to use AES-256-XTS the application must create a key with type PSA_KEY_TYPE_AES and bit size 512.

XTS mode requires an initialization vector (IV) that is the same size as the cipher block length. The IV for XTS is typically defined to be the sector number of the disk block being encrypted or decrypted.

The XTS block cipher mode is defined in 1619-2018 — IEEE Standard for Cryptographic Protection of Data on Block-Oriented Storage Devices IEEE-XTS.

Compatible key types

Definition at line 251 of file algorithm.h.