Line data    Source code

       1           1 : /** @file
       2             :  *  @brief Bluetooth subsystem crypto APIs.
       3             :  */
       4             : 
       5             : /*
       6             :  * Copyright (c) 2017-2020 Nordic Semiconductor ASA
       7             :  * Copyright (c) 2015-2017 Intel Corporation
       8             :  *
       9             :  * SPDX-License-Identifier: Apache-2.0
      10             :  */
      11             : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_CRYPTO_H_
      12             : #define ZEPHYR_INCLUDE_BLUETOOTH_CRYPTO_H_
      13             : 
      14             : /**
      15             :  * @brief Cryptography
      16             :  * @defgroup bt_crypto Cryptography
      17             :  * @ingroup bluetooth
      18             :  * @{
      19             :  */
      20             : 
      21             : #include <stdbool.h>
      22             : #include <stdint.h>
      23             : 
      24             : #ifdef __cplusplus
      25             : extern "C" {
      26             : #endif
      27             : 
      28             : /** @brief Generate random data.
      29             :  *
      30             :  *  A random number generation helper which utilizes the Bluetooth
      31             :  *  controller's own RNG.
      32             :  *
      33             :  *  @param buf Buffer to insert the random data
      34             :  *  @param len Length of random data to generate
      35             :  *
      36             :  *  @return Zero on success or error code otherwise, positive in case
      37             :  *  of protocol error or negative (POSIX) in case of stack internal error
      38             :  */
      39           1 : int bt_rand(void *buf, size_t len);
      40             : 
      41             : /** @brief AES encrypt little-endian data.
      42             :  *
      43             :  *  An AES encrypt helper is used to request the Bluetooth controller's own
      44             :  *  hardware to encrypt the plaintext using the key and returns the encrypted
      45             :  *  data.
      46             :  *
      47             :  *  @param key 128 bit LS byte first key for the encryption of the plaintext
      48             :  *  @param plaintext 128 bit LS byte first plaintext data block to be encrypted
      49             :  *  @param enc_data 128 bit LS byte first encrypted data block
      50             :  *
      51             :  *  @return Zero on success or error code otherwise.
      52             :  */
      53           1 : int bt_encrypt_le(const uint8_t key[16], const uint8_t plaintext[16],
      54             :                   uint8_t enc_data[16]);
      55             : 
      56             : /** @brief AES encrypt big-endian data.
      57             :  *
      58             :  *  An AES encrypt helper is used to request the Bluetooth controller's own
      59             :  *  hardware to encrypt the plaintext using the key and returns the encrypted
      60             :  *  data.
      61             :  *
      62             :  *  @param key 128 bit MS byte first key for the encryption of the plaintext
      63             :  *  @param plaintext 128 bit MS byte first plaintext data block to be encrypted
      64             :  *  @param enc_data 128 bit MS byte first encrypted data block
      65             :  *
      66             :  *  @return Zero on success or error code otherwise.
      67             :  */
      68           1 : int bt_encrypt_be(const uint8_t key[16], const uint8_t plaintext[16],
      69             :                   uint8_t enc_data[16]);
      70             : 
      71             : 
      72             : /** @brief Decrypt big-endian data with AES-CCM.
      73             :  *
      74             :  *  Decrypts and authorizes @c enc_data with AES-CCM, as described in
      75             :  *  https://tools.ietf.org/html/rfc3610.
      76             :  *
      77             :  *  Assumes that the MIC follows directly after the encrypted data.
      78             :  *
      79             :  *  @param key       128 bit MS byte first key
      80             :  *  @param nonce     13 byte MS byte first nonce
      81             :  *  @param enc_data  Encrypted data
      82             :  *  @param len       Length of the encrypted data
      83             :  *  @param aad       Additional authenticated data
      84             :  *  @param aad_len   Additional authenticated data length
      85             :  *  @param plaintext Plaintext buffer to place result in
      86             :  *  @param mic_size  Size of the trailing MIC (in bytes)
      87             :  *
      88             :  *  @retval 0        Successfully decrypted the data.
      89             :  *  @retval -EINVAL  Invalid parameters.
      90             :  *  @retval -EBADMSG Authentication failed.
      91             :  */
      92           1 : int bt_ccm_decrypt(const uint8_t key[16], uint8_t nonce[13], const uint8_t *enc_data,
      93             :                    size_t len, const uint8_t *aad, size_t aad_len,
      94             :                    uint8_t *plaintext, size_t mic_size);
      95             : 
      96             : 
      97             : /** @brief Encrypt big-endian data with AES-CCM.
      98             :  *
      99             :  *  Encrypts and generates a MIC from @c plaintext with AES-CCM, as described in
     100             :  *  https://tools.ietf.org/html/rfc3610.
     101             :  *
     102             :  *  Places the MIC directly after the encrypted data.
     103             :  *
     104             :  *  @param key       128 bit MS byte first key
     105             :  *  @param nonce     13 byte MS byte first nonce
     106             :  *  @param plaintext Plaintext buffer to encrypt
     107             :  *  @param len       Length of the encrypted data
     108             :  *  @param aad       Additional authenticated data
     109             :  *  @param aad_len   Additional authenticated data length
     110             :  *  @param enc_data  Buffer to place encrypted data in
     111             :  *  @param mic_size  Size of the trailing MIC (in bytes)
     112             :  *
     113             :  *  @retval 0        Successfully encrypted the data.
     114             :  *  @retval -EINVAL  Invalid parameters.
     115             :  */
     116           1 : int bt_ccm_encrypt(const uint8_t key[16], uint8_t nonce[13],
     117             :                    const uint8_t *plaintext, size_t len, const uint8_t *aad,
     118             :                    size_t aad_len, uint8_t *enc_data, size_t mic_size);
     119             : 
     120             : #ifdef __cplusplus
     121             : }
     122             : #endif
     123             : /**
     124             :  * @}
     125             :  */
     126             : 
     127             : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CRYPTO_H_ */