Expose additional functions of the crypto engine to user (#2923)
* 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>
This commit is contained in:
twisted-pear
co-authored by
twisted_pear
hedger
あく
twisted_pear
hedger
あく
parent
fb63e53d9a
commit
c976ff11bf
@@ -1,6 +1,40 @@
|
||||
/**
|
||||
* @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
|
||||
|
||||
@@ -12,10 +46,27 @@
|
||||
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 enencrypted key */
|
||||
FuriHalCryptoKeyTypeSimple, /**< Simple unencrypted key */
|
||||
FuriHalCryptoKeyTypeEncrypted, /**< Encrypted with Master key */
|
||||
} FuriHalCryptoKeyType;
|
||||
|
||||
@@ -32,40 +83,89 @@ typedef struct {
|
||||
uint8_t* data;
|
||||
} FuriHalCryptoKey;
|
||||
|
||||
/** Initialize cryptography layer This includes AES engines, PKA and RNG
|
||||
*/
|
||||
/** 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();
|
||||
|
||||
bool furi_hal_crypto_verify_enclave(uint8_t* keys_nb, uint8_t* valid_keys_nb);
|
||||
|
||||
bool furi_hal_crypto_verify_key(uint8_t key_slot);
|
||||
|
||||
/** Store key in crypto storage
|
||||
/** Verify factory provisioned keys
|
||||
*
|
||||
* @param key FuriHalCryptoKey to store. Only Master, Simple or
|
||||
* Encrypted
|
||||
* @param slot pinter to int where store slot number will be saved
|
||||
* @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_store_add_key(FuriHalCryptoKey* key, uint8_t* slot);
|
||||
bool furi_hal_crypto_enclave_store_key(FuriHalCryptoKey* key, uint8_t* slot);
|
||||
|
||||
/** Init AES engine and load key from crypto store
|
||||
/** Init AES engine and load key from crypto enclave
|
||||
*
|
||||
* @param slot store slot number
|
||||
* @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_store_load_key(uint8_t slot, const uint8_t* iv);
|
||||
bool furi_hal_crypto_enclave_load_key(uint8_t slot, const uint8_t* iv);
|
||||
|
||||
/** Unload key engine and deinit AES engine
|
||||
/** Unload key and deinit AES engine
|
||||
*
|
||||
* @param slot store slot number
|
||||
* @warning Use only with furi_hal_crypto_enclave_load_key()
|
||||
*
|
||||
* @param slot enclave slot
|
||||
*
|
||||
* @return true on success
|
||||
*/
|
||||
bool furi_hal_crypto_store_unload_key(uint8_t slot);
|
||||
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
|
||||
*
|
||||
@@ -87,6 +187,109 @@ bool furi_hal_crypto_encrypt(const uint8_t* input, uint8_t* output, size_t size)
|
||||
*/
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user