Key Management

Manage the encryption keys associated with virtual card and transaction data.

A fundamental aspect of using Sudo Platform SDKs is that user data is encrypted using keys that ensure that only the user who the data belongs to can decrypt it.

The Virtual Cards SDK uses two keys to achieve this. A symmetric key used by the SDK to seal user specific data associated with virtual cards and a public/private key pair with the public key used by the service to encrypt virtual card details, such as card number and expiry date, as well as transaction information.

Loss of these keys results in an inability of the user to decrypt the virtual card details and transactions. As such, keys should be backed up to external secure storage. To backup the keys, create a key archive from the key manager being used by the Virtual Cards SDK.

For applications where the same user may use multiple devices, all devices must have access to the same keys. These keys must be shared between the devices by securely transferring the key archive from one device to the other.

The Sudo Platform Password Manager is a good solution for storage of such archives and synchronization of archives between devices.

Creating Keys

The createKeysIfAbsent method is used to provide control of key creation time and detection of whether new keys have been created by the SDK. Keys must be created before a virtual card is created. Deferring key creation until the user creates their first virtual card can help minimize the risk that keys get created and not backed up.

Typescript

try {
  const result = await virtualCardsClient.createKeysIfAbsent()
  if (result.symmetricKey.created || result.keyPair.created) {
    // Prompt user or automatically handle backing up of new key or keys
  }
} catch (error) {
  // Handle/notify user of errors
}

Swift

do {
  let result = try await virtualCardsClient.createKeysIfAbsent()
  if (result.symmetricKey.created || result.keyPair.created) {
    // Prompt user or automatically handle backing up of new key or keys
  }
catch {
  // Handle/notify user of errors
}

Kotlin

launch {
    try {
        val result = withContext(Dispatchers.IO) {
            virtualCardsClient.createKeysIfAbsent()
        }
        if (result.symmetricKey.created || result.keyPair.created) {
            // Prompt user or automatically handle backing up of new key or keys
        }
    } catch (e: VirtualCardException) {
        // Handle/notify user of exception
    }
 }