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 provider

• deleteKeyPair- method to delete a key pair from the provider

• sign- method to sign over some block of data with the given key pair within the provider

Notably, ExternalCryptoProviders must also implement a unique enclaveId identifier. This identifier should be kept unique and constant.

The iOS and Android SDK provides extensive documentation about how each method and variable of the interface must be implemented. Additionally, the AndroidHardwareCryptoProvider and iOSHardwareCryptoProvider default implementations can be used as a reference.

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.

Swift

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()

Kotlin

val appContext: Context // Android application context
val myCustomCryptoProvider: ExternalCryptoProvider<*,*> // some implementation of the interface

val networkConfiguration = NetworkConfiguration(
    sovConfiguration = null,
    cheqdConfiguration = NetworkConfiguration.Cheqd()
)

val agentConfiguration = AgentConfiguration(
    networkConfiguration = networkConfiguration
)

val agent: SudoDIEdgeAgent = SudoDIEdgeAgent.builder()
    .setContext(appContext)
    .setAgentConfiguration(agentConfiguration)
    .registerExternalCryptoProvider(myCustomCryptoProvider)
    .registerExternalCryptoProvider(AndroidHardwareCryptoProvider())
    .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:

Swift

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
}

Kotlin

val agent: SudoDIEdgeAgent

val hardwareEnclaveOptions = CreateKeyPairEnclaveOptions.External(
    providerClass = AndroidHardwareCryptoProvider::class,
    providerOptions = AndroidHardwareCryptoProvider.CreateKeyPairOptions(
        hardwarePreference = AndroidHardwareCryptoProvider.HardwarePreference.STRONGBOX_TEE_FALLBACK
    )
)

try {
    val createdDid = agent.dids.createDid(
        options = CreateDidOptions.DidKey(
            keyType = DidKeyType.ED25519,
            enclaveOptions = hardwareEnclaveOptions
        )
    )
} catch (e: DidsModule.CreateDidException) {
    // handle error
}

Check out our sample apps for a reference on how these secure hardware cryptography providers can be utilized.