Utilize Alternative Cryptography Providers
Manage where cryptography operations are handled by the agent, for custom and high assurance use cases.
By default, the Edge Agent SDK utilizes software for cryptographic key management. These keys are managed by Askar, and encrypted at rest. However, in some use cases, such as those where higher assurance is required, alternative cryptography providers may be injected into the Edge Agent, allowing key management to occur outside of the agent's software.
These custom cryptography providers may utilize whatever provider is desired, such as: device embedded hardware security modules (HSMs), external HSMs (e.g. hardware tokens), cloud HSMs, etc.
In addition to allowing custom cryptography providers, we provide default cryptography provider implementations for iOS and Android which utilize the device's secure hardware for key management.
Implement a Custom Provider
Custom cryptography providers must conform to the ExternalCryptoProvider
interface/protocol. To implement ExternalCryptoProvider
, essential key usage and management functionality must be fulfilled:
createKeyPair
- method to create and store a key pair with the providerdeleteKeyPair
- method to delete a key pair from the providersign
- method to sign over some block of data with the given key pair within the provider
Notably, ExternalCryptoProvider
s must also implement a unique enclaveId
identifier. This identifier should be kept unique and constant.
Register the Provider
After implementing a custom provider, or if simply using the default AndroidHardwareCryptoProvider
/iOSHardwareCryptoProvider
implementations, an instance of that provider must be registered when building the agent instance.
To do this, the additional registerExternalCryptoProvider
method should be used with the agent builder (see Builder). Multiple crypto providers can be registered, so long as they are unique.
let myCustomCryptoProvider: any ExternalCryptoProvider // some implementation of the protocol
let networkConfiguration = NetworkConfiguration(
sovConfiguration: nil,
cheqdConfiguration: NetworkConfiguration.Cheqd()
)
let agentConfiguration = AgentConfiguration(networkConfiguration: networkConfiguration)
let agent = try SudoDIEdgeAgentBuilder()
.setAgentConfiguration(agentConfiguration: agentConfiguration)
.registerExternalCryptoProvider(provider: myCustomCryptoProvider)
.registerExternalCryptoProvider(provider: IOSHardwareCryptoProvider())
.build()
Utilizing the Provider
Once a provider instance is registered with the agent, the agent can be instructed to utilize that specific provider class via the configuration options for some operations.
Create a DID backed by a Custom Cryptography Provider
One such operation where custom cryptography providers can be utilized, is during DID creation when the underlying DID key is generated. Utilizing a custom provider here means that the created DID will have a cryptographic key which is backed by that provider. Then in subsequent usages of that DID, such as binding it to an incoming credential or presenting a credential, the custom provider will be invoked whenever the DID's signature is required.
By default, the key pair for a new DID will be generated using the agent's internal software (see Create DIDs). However this can be changed with the CreateKeyPairEnclaveOptions
options in the CreateDidOptions
for did:key and did:jwk DIDs. For instance, to create a did:key using the device's secure hardware key management:
let agent: SudoDIEdgeAgent
do {
let createdDid = try await agent.dids.createDid(
options: .didKey(
keyType: .ed25519,
enclaveOptions: .external(.init(
providerClass: IOSHardwareCryptoProvider.self,
providerOptions: .init()
))
)
)
} catch {
// handle error
}
Check out our sample apps for a reference on how these secure hardware cryptography providers can be utilized.
Last updated