This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Cryptography

API Reference

group bt_crypto

Cryptography.

Functions

int bt_rand(void *buf, size_t len)

Generate random data.

A random number generation helper which utilizes the Bluetooth controller’s own RNG.

Parameters:

  • buf – Buffer to insert the random data

  • len – Length of random data to generate

Returns:

Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error

int bt_encrypt_le(const uint8_t key[16], const uint8_t plaintext[16], uint8_t enc_data[16])

AES encrypt little-endian data.

An AES encrypt helper is used to request the Bluetooth controller’s own hardware to encrypt the plaintext using the key and returns the encrypted data.

Parameters:

  • key – 128 bit LS byte first key for the encryption of the plaintext

  • plaintext – 128 bit LS byte first plaintext data block to be encrypted

  • enc_data – 128 bit LS byte first encrypted data block

Returns:

Zero on success or error code otherwise.

int bt_encrypt_be(const uint8_t key[16], const uint8_t plaintext[16], uint8_t enc_data[16])

AES encrypt big-endian data.

An AES encrypt helper is used to request the Bluetooth controller’s own hardware to encrypt the plaintext using the key and returns the encrypted data.

Parameters:

  • key – 128 bit MS byte first key for the encryption of the plaintext

  • plaintext – 128 bit MS byte first plaintext data block to be encrypted

  • enc_data – 128 bit MS byte first encrypted data block

Returns:

Zero on success or error code otherwise.

int bt_ccm_decrypt(const uint8_t key[16], uint8_t nonce[13], const uint8_t *enc_data, size_t len, const uint8_t *aad, size_t aad_len, uint8_t *plaintext, size_t mic_size)

Decrypt big-endian data with AES-CCM.

Decrypts and authorizes enc_data with AES-CCM, as described in https://tools.ietf.org/html/rfc3610.

Assumes that the MIC follows directly after the encrypted data.

Parameters:

  • key – 128 bit MS byte first key

  • nonce – 13 byte MS byte first nonce

  • enc_data – Encrypted data

  • len – Length of the encrypted data

  • aad – Additional authenticated data

  • aad_len – Additional authenticated data length

  • plaintext – Plaintext buffer to place result in

  • mic_size – Size of the trailing MIC (in bytes)

Return values:

  • 0 – Successfully decrypted the data.

  • -EINVAL – Invalid parameters.

  • -EBADMSG – Authentication failed.

int bt_ccm_encrypt(const uint8_t key[16], uint8_t nonce[13], const uint8_t *plaintext, size_t len, const uint8_t *aad, size_t aad_len, uint8_t *enc_data, size_t mic_size)

Encrypt big-endian data with AES-CCM.

Encrypts and generates a MIC from plaintext with AES-CCM, as described in https://tools.ietf.org/html/rfc3610.

Places the MIC directly after the encrypted data.

Parameters:

  • key – 128 bit MS byte first key

  • nonce – 13 byte MS byte first nonce

  • plaintext – Plaintext buffer to encrypt

  • len – Length of the encrypted data

  • aad – Additional authenticated data

  • aad_len – Additional authenticated data length

  • enc_data – Buffer to place encrypted data in

  • mic_size – Size of the trailing MIC (in bytes)

Return values:

  • 0 – Successfully encrypted the data.

  • -EINVAL – Invalid parameters.