From b1d84ebbec007c2adab073482be94a469320ecbd Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Fri, 28 Aug 2026 20:29:23 -0700 Subject: [PATCH] [crypto] rename storage import/export to save/read and polish docs (#13555) While "import" and "export" terminology is common when implementing storage platform APIs (such as `otPlatCryptoImportKey()` and `otPlatCryptoExportKey()`), within OpenThread core, `SaveKey()` and `ReadKey()` are much clearer and more intuitive. They also match the established core convention used for non-volatile storage in `Settings` (e.g., `Save...()` and `Read...()`). This commit: - Renames `Crypto::Storage::ImportKey()` to `SaveKey()`. - Renames `Crypto::Storage::ReadKey()` from `ExportKey()`. - Renames `Ecdsa::KeyPairAsRef::ImportKeyPair()` to `SaveKeyPair()`. - Updates all callers across core (`KeyManager`, `KeyMaterial`, `DatasetManager`, `TcatAgent`, and `SrpClient`). - Cleans up and modernizes Doxygen documentation to emphasize that this is general-purpose secure storage (rather than PSA ITS being the only option). - Fixes various typos and formatting issues in Doxygen comments across `storage.hpp`, `storage.cpp`, and `ecdsa.hpp`. --- src/core/crypto/ecdsa.hpp | 37 +++++++------- src/core/crypto/storage.cpp | 4 +- src/core/crypto/storage.hpp | 72 ++++++++++++++-------------- src/core/mac/mac_types.cpp | 12 ++--- src/core/meshcop/dataset_manager.cpp | 6 +-- src/core/meshcop/tcat_agent.cpp | 8 ++-- src/core/net/srp_client.cpp | 2 +- src/core/thread/key_manager.cpp | 25 +++++----- 8 files changed, 83 insertions(+), 83 deletions(-) diff --git a/src/core/crypto/ecdsa.hpp b/src/core/crypto/ecdsa.hpp index 1e3e5defb..7e689a738 100644 --- a/src/core/crypto/ecdsa.hpp +++ b/src/core/crypto/ecdsa.hpp @@ -198,7 +198,7 @@ public: #if OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE /** - * Represents a key pair (public and private keys) as a PSA KeyRef. + * Represents a key pair (public and private keys) as a `KeyRef`. */ class KeyPairAsRef { @@ -206,12 +206,12 @@ public: /** * Initializes a `KeyPairAsRef`. * - * @param[in] aKeyRef PSA key reference to use while using the keypair. + * @param[in] aKeyRef Key reference to use with the key pair. */ explicit KeyPairAsRef(otCryptoKeyRef aKeyRef = 0) { mKeyRef = aKeyRef; } /** - * Generates a new keypair and imports it into PSA ITS. + * Generates a new key pair and saves it in secure storage. * * @retval kErrorNone A new key pair was generated successfully. * @retval kErrorNoBufs Failed to allocate buffer for key generation. @@ -221,29 +221,28 @@ public: Error Generate(void) const { return otPlatCryptoEcdsaGenerateAndImportKey(mKeyRef); } /** - * Imports a new keypair into PSA ITS. + * Saves a new key pair into secure storage. * - * @param[in] aKeyPair KeyPair to be imported in DER format. + * @param[in] aKeyPair The key pair to be saved in DER format. * - * @retval kErrorNone A key pair was imported successfully. + * @retval kErrorNone A key pair was saved successfully. * @retval kErrorNotCapable Feature not supported. - * @retval kErrorFailed Failed to import the key. + * @retval kErrorFailed Failed to save the key. */ - Error ImportKeyPair(const KeyPair &aKeyPair) + Error SaveKeyPair(const KeyPair &aKeyPair) { - return Crypto::Storage::ImportKey(mKeyRef, Storage::kKeyTypeEcdsa, Storage::kKeyAlgorithmEcdsa, - (Storage::kUsageSignHash | Storage::kUsageVerifyHash), - Storage::kTypePersistent, aKeyPair.GetDerBytes(), - aKeyPair.GetDerLength()); + return Crypto::Storage::SaveKey(mKeyRef, Storage::kKeyTypeEcdsa, Storage::kKeyAlgorithmEcdsa, + (Storage::kUsageSignHash | Storage::kUsageVerifyHash), + Storage::kTypePersistent, aKeyPair.GetDerBytes(), aKeyPair.GetDerLength()); } /** - * Gets the associated public key from the keypair referenced by mKeyRef. + * Gets the associated public key from the key pair referenced by mKeyRef. * * @param[out] aPublicKey A reference to a `PublicKey` to output the value. * * @retval kErrorNone Public key was retrieved successfully, and @p aPublicKey is updated. - * @retval kErrorFailed There was a error exporting the public key from PSA. + * @retval kErrorFailed Failed to retrieve the public key from secure storage. */ Error GetPublicKey(PublicKey &aPublicKey) const { @@ -251,7 +250,7 @@ public: } /** - * Calculates the ECDSA signature for a hashed message using the private key from keypair + * Calculates the ECDSA signature for a hashed message using the private key from key pair * referenced by mKeyRef. * * Uses the deterministic digital signature generation procedure from RFC 6979. @@ -270,16 +269,16 @@ public: } /** - * Gets the Key reference for the keypair stored in the PSA. + * Gets the key reference for the key pair stored in secure storage. * - * @returns The PSA key ref. + * @returns The key reference. */ otCryptoKeyRef GetKeyRef(void) const { return mKeyRef; } /** - * Sets the Key reference. + * Sets the key reference. * - * @param[in] aKeyRef PSA key reference to use while using the keypair. + * @param[in] aKeyRef Key reference to use with the key pair. */ void SetKeyRef(otCryptoKeyRef aKeyRef) { mKeyRef = aKeyRef; } diff --git a/src/core/crypto/storage.cpp b/src/core/crypto/storage.cpp index bdcfb9eed..3707eafa0 100644 --- a/src/core/crypto/storage.cpp +++ b/src/core/crypto/storage.cpp @@ -28,7 +28,7 @@ /** * @file - * This file includes implementation for Crypto Internal Trusted Storage (ITS) APIs. + * This file includes implementation for cryptographic secure storage APIs. */ #include "crypto/storage.hpp" @@ -47,7 +47,7 @@ Error Key::ExtractKey(uint8_t *aKeyBuffer, uint16_t &aKeyLength) const OT_ASSERT(IsKeyRef()); - SuccessOrAssert(Crypto::Storage::ExportKey(GetKeyRef(), aKeyBuffer, aKeyLength, readKeyLength)); + SuccessOrAssert(Crypto::Storage::ReadKey(GetKeyRef(), aKeyBuffer, aKeyLength, readKeyLength)); VerifyOrExit(readKeyLength <= aKeyLength, error = kErrorNoBufs); diff --git a/src/core/crypto/storage.hpp b/src/core/crypto/storage.hpp index d2a1d9668..10ac5f14d 100644 --- a/src/core/crypto/storage.hpp +++ b/src/core/crypto/storage.hpp @@ -28,7 +28,7 @@ /** * @file - * This file includes definitions for Crypto Internal Trusted Storage (ITS) APIs. + * This file includes definitions for cryptographic secure storage. */ #ifndef OT_CORE_CRYPTO_STORAGE_HPP_ @@ -95,7 +95,7 @@ enum StorageType : uint8_t }; /** - * This datatype represents the key reference. + * Represents a key reference. */ typedef otCryptoKeyRef KeyRef; @@ -110,7 +110,7 @@ class KeyRefManager : public InstanceLocator { public: /** - * Represents difference `KeyRef` types. + * Represents different `KeyRef` types. */ enum Type : uint8_t { @@ -154,7 +154,7 @@ public: } /** - * Delete all the persistent keys. + * Deletes all the persistent keys. */ void DestroyPersistentKeys(void); @@ -183,7 +183,7 @@ private: #endif // OPENTHREAD_FTD || OPENTHREAD_MTD /** - * Determine if a given `KeyRef` is valid or not. + * Determines whether a given `KeyRef` is valid. * * @param[in] aKeyRef The `KeyRef` to check. * @@ -193,27 +193,27 @@ private: inline bool IsKeyRefValid(KeyRef aKeyRef) { return (aKeyRef < kInvalidKeyRef); } /** - * Import a key into PSA ITS. + * Saves a key in secure storage. * * @param[in,out] aKeyRef Reference to the key ref to be used for crypto operations. * @param[in] aKeyType Key Type encoding for the key. * @param[in] aKeyAlgorithm Key algorithm encoding for the key. * @param[in] aKeyUsage Key Usage encoding for the key. * @param[in] aStorageType Key storage type. - * @param[in] aKey Actual key to be imported. - * @param[in] aKeyLen Length of the key to be imported. + * @param[in] aKey Actual key to be saved. + * @param[in] aKeyLen Length of the key to be saved. * - * @retval kErrorNone Successfully imported the key. - * @retval kErrorFailed Failed to import the key. + * @retval kErrorNone Successfully saved the key. + * @retval kErrorFailed Failed to save the key. * @retval kErrorInvalidArgs @p aKey was set to `nullptr`. */ -inline Error ImportKey(KeyRef &aKeyRef, - KeyType aKeyType, - KeyAlgorithm aKeyAlgorithm, - int aKeyUsage, - StorageType aStorageType, - const uint8_t *aKey, - size_t aKeyLen) +inline Error SaveKey(KeyRef &aKeyRef, + KeyType aKeyType, + KeyAlgorithm aKeyAlgorithm, + int aKeyUsage, + StorageType aStorageType, + const uint8_t *aKey, + size_t aKeyLen) { return otPlatCryptoImportKey(&aKeyRef, static_cast(aKeyType), static_cast(aKeyAlgorithm), aKeyUsage, @@ -221,24 +221,24 @@ inline Error ImportKey(KeyRef &aKeyRef, } /** - * Export a key stored in PSA ITS. + * Reads a key stored in secure storage. * * @param[in] aKeyRef The key ref to be used for crypto operations. - * @param[out] aBuffer Pointer to the buffer where key needs to be exported. - * @param[in] aBufferLen Length of the buffer passed to store the exported key. - * @param[out] aKeyLen Reference to variable to return the length of the exported key. + * @param[out] aBuffer Pointer to the buffer to output the read key. + * @param[in] aBufferLen Length of @p aBuffer (in bytes). + * @param[out] aKeyLen Reference to a variable to return the length of the read key (in bytes). * - * @retval kErrorNone Successfully exported @p aKeyRef. - * @retval kErrorFailed Failed to export @p aKeyRef. - * @retval kErrorInvalidArgs @p aBuffer was `nullptr`. + * @retval kErrorNone Successfully read the key. + * @retval kErrorFailed Failed to read the key. + * @retval kErrorInvalidArgs @p aBuffer was `nullptr` or @p aBufferLen was too short. */ -inline Error ExportKey(KeyRef aKeyRef, uint8_t *aBuffer, size_t aBufferLen, size_t &aKeyLen) +inline Error ReadKey(KeyRef aKeyRef, uint8_t *aBuffer, size_t aBufferLen, size_t &aKeyLen) { return otPlatCryptoExportKey(aKeyRef, aBuffer, aBufferLen, &aKeyLen); } /** - * Destroy a key stored in PSA ITS. + * Destroys a key stored in secure storage. * * @param[in] aKeyRef The key ref to be removed. */ @@ -251,12 +251,12 @@ inline void DestroyKey(KeyRef aKeyRef) } /** - * Check if the keyRef passed has an associated key in PSA ITS. + * Checks whether a given key reference has an associated key saved in secure storage. * - * @param[in] aKeyRef The Key Ref for to check. + * @param[in] aKeyRef The key reference to check. * - * @retval true Key Ref passed has a key associated in PSA. - * @retval false Key Ref passed is invalid and has no key associated in PSA. + * @retval TRUE Key reference has an associated key saved in storage. + * @retval FALSE Key reference is invalid or has no key associated in storage. */ inline bool HasKey(KeyRef aKeyRef) { return otPlatCryptoHasKey(aKeyRef); } @@ -340,12 +340,12 @@ public: } /** - * Gets the pointer to the bye array containing the key. + * Gets the pointer to the byte array containing the key. * * If `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` is enabled and `IsKeyRef()` returns `true`, then this * method returns `nullptr`. * - * @returns The pointer to the byte array containing the key, or `nullptr` if the `Key` represents a `KeyRef` + * @returns The pointer to the byte array containing the key, or `nullptr` if the `Key` represents a `KeyRef`. */ const uint8_t *GetBytes(void) const { return mKey; } @@ -356,7 +356,7 @@ public: * method returns zero. * * @returns The key length (number of bytes in the byte array from `GetBytes()`), or zero if `Key` represents a - * `keyRef`. + * `KeyRef`. */ uint16_t GetLength(void) const { return mKeyLength; } @@ -364,7 +364,7 @@ public: /** * Indicates whether or not the key is represented as a `KeyRef`. * - * @retval TRUE The `Key` represents a `KeyRef` + * @retval TRUE The `Key` represents a `KeyRef`. * @retval FALSE The `Key` represents a literal key. */ bool IsKeyRef(void) const { return (mKey == nullptr); } @@ -391,7 +391,7 @@ public: } /** - * Extracts and return the literal key when the key is represented as a `KeyRef` + * Extracts and returns the literal key when the key is represented as a `KeyRef`. * * MUST be used when `IsKeyRef()` returns `true`. * @@ -424,7 +424,7 @@ public: */ explicit LiteralKey(const Key &aKey); - /* + /** * Gets the pointer to the byte array containing the literal key. * * @returns The pointer to the byte array containing the literal key. diff --git a/src/core/mac/mac_types.cpp b/src/core/mac/mac_types.cpp index 79de7682c..7136d9daa 100644 --- a/src/core/mac/mac_types.cpp +++ b/src/core/mac/mac_types.cpp @@ -300,11 +300,11 @@ void KeyMaterial::SetFrom(const Key &aKey, bool aIsExportable) DestroyKey(); - SuccessOrAssert(Crypto::Storage::ImportKey(keyRef, Crypto::Storage::kKeyTypeAes, - Crypto::Storage::kKeyAlgorithmAesEcb, - (aIsExportable ? Crypto::Storage::kUsageExport : 0) | - Crypto::Storage::kUsageEncrypt | Crypto::Storage::kUsageDecrypt, - Crypto::Storage::kTypeVolatile, aKey.GetBytes(), Key::kSize)); + SuccessOrAssert(Crypto::Storage::SaveKey(keyRef, Crypto::Storage::kKeyTypeAes, + Crypto::Storage::kKeyAlgorithmAesEcb, + (aIsExportable ? Crypto::Storage::kUsageExport : 0) | + Crypto::Storage::kUsageEncrypt | Crypto::Storage::kUsageDecrypt, + Crypto::Storage::kTypeVolatile, aKey.GetBytes(), Key::kSize)); SetKeyRef(keyRef); } @@ -323,7 +323,7 @@ void KeyMaterial::ExtractKey(Key &aKey) const { size_t keySize; - SuccessOrAssert(Crypto::Storage::ExportKey(GetKeyRef(), aKey.m8, Key::kSize, keySize)); + SuccessOrAssert(Crypto::Storage::ReadKey(GetKeyRef(), aKey.m8, Key::kSize, keySize)); } #else aKey = GetKey(); diff --git a/src/core/meshcop/dataset_manager.cpp b/src/core/meshcop/dataset_manager.cpp index 9eb9e360f..1e3f4ff61 100644 --- a/src/core/meshcop/dataset_manager.cpp +++ b/src/core/meshcop/dataset_manager.cpp @@ -799,8 +799,8 @@ void DatasetManager::SaveTlvInSecureStorageAndClearValue(Dataset &aDataset, Tlv: VerifyOrExit(tlv != nullptr); VerifyOrExit(tlv->GetLength() > 0); - SuccessOrAssert(ImportKey(aKeyRef, kKeyTypeRaw, kKeyAlgorithmVendor, kUsageExport, kTypePersistent, tlv->GetValue(), - tlv->GetLength())); + SuccessOrAssert(SaveKey(aKeyRef, kKeyTypeRaw, kKeyAlgorithmVendor, kUsageExport, kTypePersistent, tlv->GetValue(), + tlv->GetLength())); memset(tlv->GetValue(), 0, tlv->GetLength()); @@ -819,7 +819,7 @@ Error DatasetManager::ReadTlvFromSecureStorage(Dataset &aDataset, Tlv::Type aTlv VerifyOrExit(tlv != nullptr); VerifyOrExit(tlv->GetLength() > 0); - SuccessOrExit(error = ExportKey(aKeyRef, tlv->GetValue(), tlv->GetLength(), readLength)); + SuccessOrExit(error = ReadKey(aKeyRef, tlv->GetValue(), tlv->GetLength(), readLength)); VerifyOrExit(readLength == tlv->GetLength(), error = OT_ERROR_FAILED); exit: diff --git a/src/core/meshcop/tcat_agent.cpp b/src/core/meshcop/tcat_agent.cpp index c35a6e3cb..30b462311 100644 --- a/src/core/meshcop/tcat_agent.cpp +++ b/src/core/meshcop/tcat_agent.cpp @@ -919,10 +919,10 @@ Error TcatAgent::CalculateHash(uint64_t aChallenge, const char *aBuf, size_t aBu #if OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE Crypto::Storage::KeyRef keyRef; - SuccessOrExit(error = Crypto::Storage::ImportKey(keyRef, Crypto::Storage::kKeyTypeHmac, - Crypto::Storage::kKeyAlgorithmHmacSha256, - Crypto::Storage::kUsageSignHash, Crypto::Storage::kTypeVolatile, - reinterpret_cast(aBuf), aBufLen)); + SuccessOrExit(error = Crypto::Storage::SaveKey(keyRef, Crypto::Storage::kKeyTypeHmac, + Crypto::Storage::kKeyAlgorithmHmacSha256, + Crypto::Storage::kUsageSignHash, Crypto::Storage::kTypeVolatile, + reinterpret_cast(aBuf), aBufLen)); cryptoKey.SetAsKeyRef(keyRef); #else cryptoKey.Set(reinterpret_cast(aBuf), static_cast(aBufLen)); diff --git a/src/core/net/srp_client.cpp b/src/core/net/srp_client.cpp index be321a8e8..86e4c6b03 100644 --- a/src/core/net/srp_client.cpp +++ b/src/core/net/srp_client.cpp @@ -1267,7 +1267,7 @@ Error Client::ReadOrGenerateKey(KeyInfo &aKeyInfo) if (error == kErrorNone) { - if (aKeyInfo.ImportKeyPair(keyPair) != kErrorNone) + if (aKeyInfo.SaveKeyPair(keyPair) != kErrorNone) { SuccessOrExit(error = aKeyInfo.Generate()); } diff --git a/src/core/thread/key_manager.cpp b/src/core/thread/key_manager.cpp index 381110326..59f3ecf1b 100644 --- a/src/core/thread/key_manager.cpp +++ b/src/core/thread/key_manager.cpp @@ -568,7 +568,7 @@ void KeyManager::GetNetworkKey(NetworkKey &aNetworkKey) const { size_t keyLen; - SuccessOrAssert(Crypto::Storage::ExportKey(mNetworkKeyRef, aNetworkKey.m8, NetworkKey::kSize, keyLen)); + SuccessOrAssert(Crypto::Storage::ReadKey(mNetworkKeyRef, aNetworkKey.m8, NetworkKey::kSize, keyLen)); OT_ASSERT(keyLen == NetworkKey::kSize); } else @@ -587,7 +587,7 @@ void KeyManager::GetPskc(Pskc &aPskc) const { size_t keyLen; - SuccessOrAssert(Crypto::Storage::ExportKey(mPskcRef, aPskc.m8, Pskc::kSize, keyLen)); + SuccessOrAssert(Crypto::Storage::ReadKey(mPskcRef, aPskc.m8, Pskc::kSize, keyLen)); OT_ASSERT(keyLen == Pskc::kSize); } else @@ -609,9 +609,10 @@ void KeyManager::StoreNetworkKey(const NetworkKey &aNetworkKey, bool aOverWriteE if (!aOverWriteExisting) { - // Check if there is already a network key stored in ITS. If - // stored, and we are not overwriting the existing key, - // return without doing anything. + // Check if there is already a network key stored in secure + // storage. If stored, and we are not overwriting the existing + // key, return without doing anything. + if (Crypto::Storage::HasKey(keyRef)) { ExitNow(); @@ -620,10 +621,10 @@ void KeyManager::StoreNetworkKey(const NetworkKey &aNetworkKey, bool aOverWriteE Crypto::Storage::DestroyKey(keyRef); - SuccessOrAssert(Crypto::Storage::ImportKey(keyRef, Crypto::Storage::kKeyTypeHmac, - Crypto::Storage::kKeyAlgorithmHmacSha256, - Crypto::Storage::kUsageSignHash | Crypto::Storage::kUsageExport, - Crypto::Storage::kTypePersistent, aNetworkKey.m8, NetworkKey::kSize)); + SuccessOrAssert(Crypto::Storage::SaveKey(keyRef, Crypto::Storage::kKeyTypeHmac, + Crypto::Storage::kKeyAlgorithmHmacSha256, + Crypto::Storage::kUsageSignHash | Crypto::Storage::kUsageExport, + Crypto::Storage::kTypePersistent, aNetworkKey.m8, NetworkKey::kSize)); exit: if (mNetworkKeyRef != keyRef) @@ -640,9 +641,9 @@ void KeyManager::StorePskc(const Pskc &aPskc) Crypto::Storage::DestroyKey(keyRef); - SuccessOrAssert(Crypto::Storage::ImportKey(keyRef, Crypto::Storage::kKeyTypeRaw, - Crypto::Storage::kKeyAlgorithmVendor, Crypto::Storage::kUsageExport, - Crypto::Storage::kTypePersistent, aPskc.m8, Pskc::kSize)); + SuccessOrAssert(Crypto::Storage::SaveKey(keyRef, Crypto::Storage::kKeyTypeRaw, Crypto::Storage::kKeyAlgorithmVendor, + Crypto::Storage::kUsageExport, Crypto::Storage::kTypePersistent, aPskc.m8, + Pskc::kSize)); if (mPskcRef != keyRef) {