unleashed-firmware/firmware/targets/furi_hal_include/furi_hal_crypto.h
twisted-pear c976ff11bf
Expose additional functions of the crypto engine to user ()
* Allow loading user supplied keys and add CTR mode
* Add GCM mode to furi_hal_crypto
* Split up CTR and GCM code, add flag for adv crypto
* Add convenience functions for GCM crypto
* Run fbt format
* Update GCM to support additional auth data
* Update APIs
* FuriHal: update crypto documentation, method names and usage
* Clean up code for key (un)loading, GCM and CTR
  - get rid of goto
  - do not use furi_hal_bt_is_alive() when not using secure enclave
  - give defines a type and wrap in ()
* Add unit test for CTR and GCM crypto
* FuriHal: const in crypto unit tests, cortex timer for crypto operations timeouts
* FuriHal: update crypto docs

Co-authored-by: twisted_pear <twstd@posteo.net>
Co-authored-by: hedger <hedger@users.noreply.github.com>
Co-authored-by: あく <alleteam@gmail.com>
2023-08-10 17:44:46 +09:00

296 lines
10 KiB
C

/**
* @file furi_hal_crypto.h
*
* Cryptography HAL API
*
* !!! READ THIS FIRST !!!
*
* Flipper was never designed to be secure, nor it passed cryptography audit.
* Despite of the fact that keys are stored in secure enclave there are some
* types of attack that can be performed against AES engine to recover
* keys(theoretical). Also there is no way to securely deliver user keys to
* device and never will be. In addition device is fully open and there is no
* way to guarantee safety of your data, it can be easily dumped with debugger
* or modified code.
*
* Secure enclave on WB series is implemented on core2 FUS side and can be used
* only if core2 alive. Enclave is responsible for storing, loading and
* unloading keys to and from enclave/AES in secure manner(AES engine key
* registers will be locked when key from enclave loaded)
*
* There are 11 keys that we provision at factory:
* - 0 - Master key for secure key delivery. Impossible to use for anything but
* key provisioning. We don't plan to use it too.
* - 1 - 10 - Keys used by firmware. All devices got the same set of keys. You
* also can use them in your applications.
*
* Also there is a slot 11 that we use for device unique key. This slot is
* intentionally left blank till the moment of first use, so you can ensure that
* we don't know your unique key. Also you can provision this key by your self
* with crypto cli or API.
*
* Other slots can be used for your needs. But since enclave is sequential
* append only, we can not guarantee you that slots you want are free. NEVER USE
* THEM FOR PUBLIC APPLICATIONS.
*
* Also you can directly load raw keys into AES engine and use it for your
* needs.
*/
#pragma once
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/** Factory provisioned master key slot. Should never be used. */
#define FURI_HAL_CRYPTO_ENCLAVE_MASTER_KEY_SLOT (0u)
/** Factory provisioned keys slot range. All of them are exactly same on all flippers. */
#define FURI_HAL_CRYPTO_ENCLAVE_FACTORY_KEY_SLOT_START (1u)
#define FURI_HAL_CRYPTO_ENCLAVE_FACTORY_KEY_SLOT_END (10u)
/** Device unique key slot. This key generated on first use or provisioned by user. Use furi_hal_crypto_enclave_ensure_key before using this slot. */
#define FURI_HAL_CRYPTO_ENCLAVE_UNIQUE_KEY_SLOT (11u)
/** User key slot range. This slots can be used for your needs, but never use them in public apps. */
#define FURI_HAL_CRYPTO_ENCLAVE_USER_KEY_SLOT_START (12u)
#define FURI_HAL_CRYPTO_ENCLAVE_USER_KEY_SLOT_END (100u)
/** [Deprecated] Indicates availability of advanced crypto functions, will be dropped before v1.0 */
#define FURI_HAL_CRYPTO_ADVANCED_AVAIL 1
/** FuriHalCryptoKey Type */
typedef enum {
FuriHalCryptoKeyTypeMaster, /**< Master key */
FuriHalCryptoKeyTypeSimple, /**< Simple unencrypted key */
FuriHalCryptoKeyTypeEncrypted, /**< Encrypted with Master key */
} FuriHalCryptoKeyType;
/** FuriHalCryptoKey Size in bits */
typedef enum {
FuriHalCryptoKeySize128,
FuriHalCryptoKeySize256,
} FuriHalCryptoKeySize;
/** FuriHalCryptoKey */
typedef struct {
FuriHalCryptoKeyType type;
FuriHalCryptoKeySize size;
uint8_t* data;
} FuriHalCryptoKey;
/** FuriHalCryptoGCMState Result of a GCM operation */
typedef enum {
FuriHalCryptoGCMStateOk, /**< operation successful */
FuriHalCryptoGCMStateError, /**< error during encryption/decryption */
FuriHalCryptoGCMStateAuthFailure, /**< tags do not match, auth failed */
} FuriHalCryptoGCMState;
/** Initialize cryptography layer(includes AES engines, PKA and RNG) */
void furi_hal_crypto_init();
/** Verify factory provisioned keys
*
* @param keys_nb The keys number of
* @param valid_keys_nb The valid keys number of
*
* @return true if all enclave keys are intact, false otherwise
*/
bool furi_hal_crypto_enclave_verify(uint8_t* keys_nb, uint8_t* valid_keys_nb);
/** Ensure that requested slot and slots before this slot contains keys.
*
* This function is used to provision FURI_HAL_CRYPTO_ENCLAVE_UNIQUE_KEY_SLOT. Also you
* may want to use it to generate some unique keys in user key slot range.
*
* @warning Because of the sequential nature of the secure enclave this
* method will generate key for all slots from
* FURI_HAL_CRYPTO_ENCLAVE_FACTORY_KEY_SLOT_END to the slot your requested.
* Keys are generated using on-chip RNG.
*
* @param[in] key_slot The key slot to enclave
*
* @return true if key exists or created, false if enclave corrupted
*/
bool furi_hal_crypto_enclave_ensure_key(uint8_t key_slot);
/** Store key in crypto enclave
*
* @param key FuriHalCryptoKey to be stored
* @param slot pointer to int where enclave slot will be stored
*
* @return true on success
*/
bool furi_hal_crypto_enclave_store_key(FuriHalCryptoKey* key, uint8_t* slot);
/** Init AES engine and load key from crypto enclave
*
* @warning Use only with furi_hal_crypto_enclave_unload_key()
*
* @param slot enclave slot
* @param[in] iv pointer to 16 bytes Initialization Vector data
*
* @return true on success
*/
bool furi_hal_crypto_enclave_load_key(uint8_t slot, const uint8_t* iv);
/** Unload key and deinit AES engine
*
* @warning Use only with furi_hal_crypto_enclave_load_key()
*
* @param slot enclave slot
*
* @return true on success
*/
bool furi_hal_crypto_enclave_unload_key(uint8_t slot);
/** Init AES engine and load supplied key
*
* @warning Use only with furi_hal_crypto_unload_key()
*
* @param[in] key pointer to 32 bytes key data
* @param[in] iv pointer to 16 bytes Initialization Vector data
*
* @return true on success
*/
bool furi_hal_crypto_load_key(const uint8_t* key, const uint8_t* iv);
/** Unload key and de-init AES engine
*
* @warning Use this function only with furi_hal_crypto_load_key()
*
* @return true on success
*/
bool furi_hal_crypto_unload_key(void);
/** Encrypt data
*
* @param input pointer to input data
* @param output pointer to output data
* @param size input/output buffer size in bytes
*
* @return true on success
*/
bool furi_hal_crypto_encrypt(const uint8_t* input, uint8_t* output, size_t size);
/** Decrypt data
*
* @param input pointer to input data
* @param output pointer to output data
* @param size input/output buffer size in bytes
*
* @return true on success
*/
bool furi_hal_crypto_decrypt(const uint8_t* input, uint8_t* output, size_t size);
/** Encrypt the input using AES-CTR
*
* Decryption can be performed by supplying the ciphertext as input. Inits and
* deinits the AES engine internally.
*
* @param[in] key pointer to 32 bytes key data
* @param[in] iv pointer to 12 bytes Initialization Vector data
* @param[in] input pointer to input data
* @param[out] output pointer to output data
* @param length length of the input and output in bytes
*
* @return true on success
*/
bool furi_hal_crypto_ctr(
const uint8_t* key,
const uint8_t* iv,
const uint8_t* input,
uint8_t* output,
size_t length);
/** Encrypt/decrypt the input using AES-GCM
*
* When decrypting the tag generated needs to be compared to the tag attached to
* the ciphertext in a constant-time fashion. If the tags are not equal, the
* decryption failed and the plaintext returned needs to be discarded. Inits and
* deinits the AES engine internally.
*
* @param[in] key pointer to 32 bytes key data
* @param[in] iv pointer to 12 bytes Initialization Vector data
* @param[in] aad pointer to additional authentication data
* @param aad_length length of the additional authentication data in bytes
* @param[in] input pointer to input data
* @param[out] output pointer to output data
* @param length length of the input and output in bytes
* @param[out] tag pointer to 16 bytes space for the tag
* @param decrypt true for decryption, false otherwise
*
* @return true on success
*/
bool furi_hal_crypto_gcm(
const uint8_t* key,
const uint8_t* iv,
const uint8_t* aad,
size_t aad_length,
const uint8_t* input,
uint8_t* output,
size_t length,
uint8_t* tag,
bool decrypt);
/** Encrypt the input using AES-GCM and generate a tag
*
* Inits and deinits the AES engine internally.
*
* @param[in] key pointer to 32 bytes key data
* @param[in] iv pointer to 12 bytes Initialization Vector data
* @param[in] aad pointer to additional authentication data
* @param aad_length length of the additional authentication data in bytes
* @param[in] input pointer to input data
* @param[out] output pointer to output data
* @param length length of the input and output in bytes
* @param[out] tag pointer to 16 bytes space for the tag
*
* @return FuriHalCryptoGCMStateOk on success, FuriHalCryptoGCMStateError on
* failure
*/
FuriHalCryptoGCMState furi_hal_crypto_gcm_encrypt_and_tag(
const uint8_t* key,
const uint8_t* iv,
const uint8_t* aad,
size_t aad_length,
const uint8_t* input,
uint8_t* output,
size_t length,
uint8_t* tag);
/** Decrypt the input using AES-GCM and verify the provided tag
*
* Inits and deinits the AES engine internally.
*
* @param[in] key pointer to 32 bytes key data
* @param[in] iv pointer to 12 bytes Initialization Vector data
* @param[in] aad pointer to additional authentication data
* @param aad_length length of the additional authentication data in bytes
* @param[in] input pointer to input data
* @param[out] output pointer to output data
* @param length length of the input and output in bytes
* @param[out] tag pointer to 16 bytes tag
*
* @return FuriHalCryptoGCMStateOk on success, FuriHalCryptoGCMStateError on
* failure, FuriHalCryptoGCMStateAuthFailure if the tag does not
* match
*/
FuriHalCryptoGCMState furi_hal_crypto_gcm_decrypt_and_verify(
const uint8_t* key,
const uint8_t* iv,
const uint8_t* aad,
size_t aad_length,
const uint8_t* input,
uint8_t* output,
size_t length,
const uint8_t* tag);
#ifdef __cplusplus
}
#endif