Skip to main content
Version: v0.13

KMS Providers

The IDK supports multiple key management system (KMS) providers, allowing you to store cryptographic keys in the most appropriate backend for your use case. Multiple providers can be active simultaneously.

Available Providers​

Provider TypePlatformsUse Case
SOFTWAREAllIn-memory or file-based keys for development and testing
MOBILEiOS, AndroidHardware-backed keys using Secure Enclave or Android Keystore
AWS_KMSJVMCloud-hosted HSM keys with AWS Key Management Service
AZURE_KEYVAULTJVM, JSCloud-hosted HSM keys with Azure Key Vault
RESTAllRemote KMS accessed via REST API

Provider Capabilities Comparison​

Platform Availability​

ProviderAndroidiOSJVM/ServerWeb/JS
Software✓✓ (Keychain)✓✓ (WebCrypto)
Mobile✓ (Keystore)✓ (Secure Enclave)✗✗
AWS KMS✗✗✓✗
Azure Key Vault✗✗✓✓
REST Client✓✓✓✓

Key Operations​

OperationSoftwareMobileAWS KMSAzureREST
Generate Key✓✓✓✓✓
Import Key✓✗✓✓✓
Export Key✓✗✗✗✓
Delete Key✓✓✓✓✓
List Keys✓✓✓✓✓

Cryptographic Operations​

OperationSoftwareMobileAWS KMSAzureREST
Sign✓✓✓✓✓
Verify✓✓✓✓✓
Encrypt✓ (GCM)✗✓✓✗
Decrypt✓ (GCM)✗✓✓✗
Key Wrap✓ (RSA-OAEP, AES-KW)✗✓✓✗
Key Unwrap✓ (RSA-OAEP, AES-KW)✗✓✓✗
Key Agreement (ECDH)✓✗✓✗✗

Supported Key Types and Curves​

ProviderEC CurvesRSA Key Sizes
SoftwareP-256, P-384, P-5212048, 3072, 4096
MobileP-256, P-384, P-5212048, 3072, 4096
AWS KMSP-256, P-384, P-5212048, 3072, 4096
Azure Key VaultP-256, P-384, P-521, secp256k12048
REST ClientP-256, P-384, P-5212048, 3072, 4096

Signature Algorithms​

AlgorithmSoftwareMobileAWS KMSAzureREST
ECDSA + SHA-256✓✓✓✓✓
ECDSA + SHA-384✓✓✓✓✓
ECDSA + SHA-512✓✓✓✓✓
RSA PKCS#1 + SHA-256✓✓✓✓✓
RSA PKCS#1 + SHA-384✓✓✓✓✓
RSA PKCS#1 + SHA-512✓✓✓✓✓
RSA-PSS + SHA-256✓✓✓✓✓
RSA-PSS + SHA-384✓✓✓✓✓
RSA-PSS + SHA-512✓✓✓✓✓

Content Encryption Algorithms​

AlgorithmSoftwareMobileAWS KMSAzure
A128GCM✓✗✓✓
A192GCM✓✗✓✓
A256GCM✓✗✓✓
A128CBC-HS256✗✗✓✓
A192CBC-HS384✗✗✓✓
A256CBC-HS512✗✗✓✓

Key Wrapping Algorithms​

AlgorithmSoftwareMobileAWS KMSAzure
RSA-OAEP✓✗✓✓
RSA-OAEP-256✓✗✓✓
RSA-OAEP-512✓✗✗✗
RSA1_5✗✗✗✓
A128KW✓✗✓✓
A192KW✓✗✓✓
A256KW✓✗✓✓

Key Agreement Algorithms​

AlgorithmSoftwareMobileAWS KMSAzure
ECDH-ES✓✗✓✗
ECDH-ES+A128KW✓✗✗✗
ECDH-ES+A192KW✓✗✗✗
ECDH-ES+A256KW✓✗✗✗

Storage and Security​

FeatureSoftwareMobileAWS KMSAzureREST
Hardware BackingOptional✓✓ (HSM)✓ (HSM)Depends on backend
Private Key Export✓✗✗✗Depends on backend
Persistent Storage✓✓✓✓✓
Ephemeral Storage✓✓✗✗✓
Certificate Generation✓✗✗✗✗
Certificate Import✓✗✗✗✗

Provider Selection Quick Reference​

Use CaseRecommended Provider
Production mobile walletMobile
Development and testingSoftware
Server-side with AWS infrastructureAWS KMS
Server-side with Azure infrastructureAzure Key Vault
Delegated signing to remote serviceREST Client
Cross-platform with hardware preferenceSoftware (uses native APIs when available)

Provider Capabilities​

Each provider declares its capabilities. Query them to understand what operations are available:

val provider = keyManager.getProviderById("software")
val capabilities = provider.getCapabilities()

// Storage capabilities
println("Storage types: ${capabilities.storageTypes.joinToString()}")  // PERSISTENT, EPHEMERAL
println("Supports import: ${capabilities.supportsKeyImport}")
println("Supports export: ${capabilities.supportsKeyExport}")
println("Exposes private keys: ${capabilities.exposePrivateKeys}")

// Cryptographic capabilities
println("Key types: ${capabilities.supportedKeyTypes.joinToString()}")  // EC, RSA
println("Curves: ${capabilities.supportedCurves.joinToString()}")  // P_256, P_384, P_521
println("Digests: ${capabilities.supportedDigestAlgorithms.joinToString()}")

// Operations
println("Supports signing: ${capabilities.supportsSigning()}")
println("Supports encryption: ${capabilities.supportsEncryption()}")
println("Supports key agreement: ${capabilities.supportsKeyAgreement()}")
println("Hardware backing: ${capabilities.supportsHardwareBacking}")
println("X.509 support: ${capabilities.supportsX509}")

Software Provider​

The software provider stores keys in memory or on the filesystem. It's suitable for development, testing, and scenarios where hardware-backed storage isn't required.

Capabilities​

  • Storage: Persistent and ephemeral
  • Key Types: EC, RSA, Symmetric (oct)
  • Curves: P-256, P-384, P-521
  • Operations: Generate, import, export, delete, sign, verify, encrypt, decrypt, wrap, unwrap, key agreement
  • Signature Algorithms: ECDSA (SHA-256/384/512), RSA (SHA-256/384/512), RSA-PSS
  • Encryption Algorithms: A128GCM, A192GCM, A256GCM
  • Key Wrap Algorithms: RSA-OAEP, RSA-OAEP-256, RSA-OAEP-512, A128KW, A192KW, A256KW
  • Key Agreement: ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW

Configuration​

import com.sphereon.crypto.kms.provider.software.SoftwareKmsProviderConfig
import com.sphereon.crypto.kms.provider.software.SoftwareKmsProviderFactory

// Create software provider configuration
val softwareConfig = SoftwareKmsProviderConfig(
    id = "software",
    exposePrivateKeysDuringGeneration = true,
    keyStore = KeyStoreConfig(
        path = "/data/app/keys",
        overwriteAlias = true
    )
)

// Factory creates the provider instance
val factory: SoftwareKmsProviderFactory = ...
val softwareProvider = factory.create(softwareConfig, session.execution)

// Register with key manager
keyManager.registerProvider(softwareProvider, makeDefaultKms = true)

Mobile Provider​

The mobile provider uses platform-specific secure storage:

  • iOS: Secure Enclave for private key operations
  • Android: Android Keystore with hardware backing when available

This is the recommended provider for production mobile applications.

Capabilities​

  • Storage: Hardware-backed persistent
  • Key Types: EC (platform-dependent)
  • Curves: P-256 (most common)
  • Operations: Generate, sign, verify (no export of private keys)
  • Hardware Backing: Yes
  • Attestation: Platform-dependent

Key Characteristics​

  • Private keys never leave the secure hardware
  • Keys are bound to the device and cannot be exported
  • Biometric authentication can be required for key use
  • Keys persist across app restarts but may be deleted with app uninstall

AWS KMS Provider​

The AWS KMS provider integrates with Amazon Web Services Key Management Service.

Configuration​

import com.sphereon.crypto.kms.provider.aws.AwsKmsProviderConfig

val awsConfig = AwsKmsProviderConfig(
    id = "aws",
    region = "us-east-1",
    accessKeyId = System.getenv("AWS_ACCESS_KEY_ID"),
    secretAccessKey = System.getenv("AWS_SECRET_ACCESS_KEY"),
    endpointOverride = null  // Optional: for LocalStack testing
)

IAM Permissions​

The AWS credentials must have permissions for the following KMS actions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:CreateKey",
                "kms:Sign",
                "kms:Verify",
                "kms:GetPublicKey",
                "kms:DescribeKey",
                "kms:ScheduleKeyDeletion"
            ],
            "Resource": "*"
        }
    ]
}

Azure Key Vault Provider​

The Azure provider integrates with Azure Key Vault.

Configuration​

import com.sphereon.crypto.kms.provider.azure.AzureKmsProviderConfig

val azureConfig = AzureKmsProviderConfig(
    id = "azure",
    vaultUrl = "https://my-vault.vault.azure.net",
    tenantId = "12345678-1234-1234-1234-123456789012",
    clientId = "87654321-4321-4321-4321-210987654321",
    clientSecret = System.getenv("AZURE_CLIENT_SECRET")
)

Using Multiple Providers​

The KeyManagerService can work with multiple providers simultaneously. Specify the provider when generating keys:

// Generate a key using the default provider
val defaultKey = keyManager.generateKeyAsync(
    providerId = null,  // Uses default
    alias = "default-key",
    alg = SignatureAlgorithm.ECDSA_SHA256
)

// Generate a key in AWS KMS
val awsKey = keyManager.generateKeyAsync(
    providerId = "aws",
    alias = "aws-key",
    alg = SignatureAlgorithm.ECDSA_SHA256
)

// Generate a key in Azure Key Vault
val azureKey = keyManager.generateKeyAsync(
    providerId = "azure",
    alias = "azure-key",
    alg = SignatureAlgorithm.ECDSA_SHA256
)

// Generate a key in software provider
val softwareKey = keyManager.generateKeyAsync(
    providerId = "software",
    alias = "software-key",
    alg = SignatureAlgorithm.ECDSA_SHA256
)

Registering Providers​

Register custom or additional providers with the key manager:

// Register a provider
keyManager.registerProvider(
    provider = myCustomProvider,
    makeDefaultKms = false
)

// Register and make it the default
keyManager.registerProvider(
    provider = softwareProvider,
    makeDefaultKms = true
)

// Check the default provider
val defaultId = keyManager.defaultProviderId()
println("Default provider: $defaultId")

Provider Selection Guidelines​

When choosing a KMS provider:

Mobile Provider: Use for production mobile apps. Keys are hardware-backed and cannot be extracted, providing strong security guarantees.

Software Provider: Use for development, testing, or when you need to export keys. Not recommended for production mobile apps holding sensitive keys.

AWS KMS: Use when you need centralized key management, audit logging, or when keys must be accessible from multiple services.

Azure Key Vault: Similar to AWS KMS, use for Azure-centric architectures or when Azure compliance certifications are required.

Storage Types​

Providers support different storage types:

TypeDescription
NONENo storage, ephemeral keys only
EPHEMERALSession-scoped, keys lost on restart
PERSISTENTDisk or database storage, keys survive restart
HARDWAREHSM, Secure Enclave, or TPM backed

Supported Operations​

Providers may support different operations:

OperationDescription
GENERATE_KEYCreate new key pairs
IMPORT_KEYImport existing keys
EXPORT_KEYExport keys (if allowed)
DELETE_KEYRemove keys from storage
SIGNCreate signatures
VERIFYVerify signatures
ENCRYPTContent encryption
DECRYPTContent decryption
WRAP_KEYKey wrapping
UNWRAP_KEYKey unwrapping
KEY_AGREEMENTECDH key agreement