espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-09-20 16:07:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

[crypto] rename storage import/export to save/read and polish docs (#13555)

Browse Source 
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`.
This commit is contained in:
Abtin Keshavarzian
2026-08-28 20:29:23 -07:00
committed by GitHub
parent 5568af7983
commit b1d84ebbec
8 changed files with 83 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/core/crypto/ecdsa.hpp
+18 -19
View File
@@ -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; }
src/core/crypto/storage.cpp
+2 -2
View File
@@ -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);
src/core/crypto/storage.hpp
+36 -36
View File
@@ -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<otCryptoKeyType>(aKeyType),
static_cast<otCryptoKeyAlgorithm>(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.
src/core/mac/mac_types.cpp
+6 -6
View File
@@ -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();
src/core/meshcop/dataset_manager.cpp
+3 -3
View File
@@ -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:
src/core/meshcop/tcat_agent.cpp
+4 -4
View File
@@ -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<const uint8_t *>(aBuf), aBufLen));
SuccessOrExit(error = Crypto::Storage::SaveKey(keyRef, Crypto::Storage::kKeyTypeHmac,
Crypto::Storage::kKeyAlgorithmHmacSha256,
Crypto::Storage::kUsageSignHash, Crypto::Storage::kTypeVolatile,
reinterpret_cast<const uint8_t *>(aBuf), aBufLen));
cryptoKey.SetAsKeyRef(keyRef);
#else
cryptoKey.Set(reinterpret_cast<const uint8_t *>(aBuf), static_cast<uint16_t>(aBufLen));
src/core/net/srp_client.cpp
+1 -1
View File
@@ -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());
}
src/core/thread/key_manager.cpp
+13 -12
View File
@@ -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)
{