embassy-nrf

Crates

git

Versions

nrf9161-s

Flavors

Skip to main content

Module symmetric

Module symmetric 

Source
Expand description

Symmetric crypto engines: AES, hash and ChaCha.

The three engines share one DMA, so only one of them runs at a time. They are owned together through the CRYPTO_SYMMETRIC peripheral and the Symmetric driver.

The state of every operation lives in a context object outside the driver. Any number of operations of any kind can be in progress at once, and their calls can be interleaved.

§AES

ModeAuthenticatednRF52840, nRF91nRF5340nRF54L
ECBNo✓✓✓
CBCNo✓✓✓
CTRNo✓✓✓
CMACMAC only✓✓✓
CCMYes✓✓✓
GCMYes✗✓✓

128-bit keys are supported on all chips. 192-bit and 256-bit keys are supported on nRF5340 and nRF54L.

To run a cipher operation:

  1. Start it with Symmetric::aes_start. This returns an AesContext.
  2. Feed additional authenticated data with Symmetric::aes_blocking_aad (authenticated modes only).
  3. Feed the payload with Symmetric::aes_blocking_payload.
  4. Finish with Symmetric::aes_blocking_finish. For MAC and AEAD modes this returns the authentication tag.

§Hash and HMAC

AlgorithmnRF52840, nRF91, nRF5340nRF54L
SHA-1✓✓
SHA-224✓✓
SHA-256✓✓
SHA-384✗✓
SHA-512✗✓
SHA-512/224✗✓
SHA-512/256✗✓

HMAC is available for every supported algorithm.

To compute a digest:

  1. Start with Symmetric::hash_start or Symmetric::hmac_start.
  2. Feed data with Symmetric::hash_blocking_update.
  3. Finish with Symmetric::hash_blocking_finish.

§ChaCha and ChaCha-Poly1305

Both follow RFC 8439: a 256-bit key, a 96-bit nonce and a 32-bit block counter. The ChaChaVariant selects the number of rounds: ChaCha20 everywhere, and also the reduced-round ChaCha12 and ChaCha8 on the CryptoCell.

The CryptoCell has no Poly1305 engine. There, the authenticator runs in software.

Input data may be anywhere in memory, including flash.

Re-exports§

pub use hash::Buffer;
pub use hash::DigestContext;
pub use hash::HashAlgorithm;
pub use hash::HashContext;
pub use hash::HmacContext;
pub use hash::Sha1;
pub use hash::Sha224;
pub use hash::Sha256;

Structs§

AesCbc
AES in CBC (cipher block chaining) mode.
AesCcm
AES in CCM (counter with CBC-MAC) authenticated mode, as in NIST SP 800-38C.
AesCmac
AES-CMAC message authentication code, as in NIST SP 800-38B.
AesContext
State of an AES operation in progress. Created by Symmetric::aes_start.
AesCtr
AES in CTR (counter) mode, as in NIST SP 800-38A.
AesEcb
AES in ECB (electronic codebook) mode.
ChaChaContext
State of a ChaCha keystream in progress. Created by Symmetric::chacha_start.
ChaChaPolyContext
State of an in-progress ChaCha-Poly1305 operation, created by Symmetric::chachapoly_start.
HashContext
State of a hash computation in progress. Created by Symmetric::hash_start.
HmacContext
State of an HMAC computation in progress. Created by Symmetric::hmac_start.
Sha1
SHA-1.
Sha224
SHA-224.
Sha256
SHA-256.
Symmetric
Driver for the symmetric crypto engines: AES, hash and ChaCha.

Enums§

ChaChaVariant
Number of rounds of the ChaCha block function.
Direction
Cipher direction.
Error
Symmetric crypto error.

Constants§

AES_BLOCK_LEN
AES block length in bytes.
CHACHA_BLOCK_LEN
ChaCha20 block length in bytes.
CHACHA_KEY_LEN
ChaCha20 key length in bytes.
CHACHA_NONCE_LEN
ChaCha20 nonce length in bytes.

Traits§

AuthenticatedCipher
AES cipher mode that accepts additional authenticated data. Implemented by AesCcm and AesGcm.
Buffer
Fixed-size byte buffer. Implemented for [u8; N].
Cipher
AES cipher mode. Implemented by AesEcb, AesCbc, AesCtr, AesCmac, AesCcm and AesGcm.
DigestContext
A hash or HMAC context. Implemented by HashContext and HmacContext.
HashAlgorithm
Hash algorithm. Implemented by Sha1, Sha224, Sha256 and, on CRACEN, the SHA-512 family.