External Key Method

Back up your end users device's key shares using an external key.

Following this method, your application must be able to create an encryption key that is used to perform the backup; then during recovery, the application must be able to provide a decryption key.

See also:

Back up mobile device's key shares

To back up mobile device's key shares, Fordefi supports passing an AES 256-bit symmetric key that you generate into the backupKeyset method. Once the method is used, an encrypted version of the end user's key share will be uploaded to Fordefi's cloud for storage.

Here's how:

const backupKeysetFn = async (keysetId: string, encryptionKey?: string) => {
    try {
        const backupOptions: ExternalBackupOptions =  {
            encryptionKeyType: EncryptionAES256,
            encryptionKey: encryptionKey,
        };
        const result = await backupKeyset(keysetId, backupOptions);
        console.debug(`Update Keyset Backup result ${result}`);
    } catch (error: unknown) {
        const sdkError = error as FordefiSdkErrorResult;
        console.error(`Update Keyset Backup failed ${error}`);
    }
};

import com.fordefi.fordefi.Fordefi
import com.fordefi.fordefi.FordefiError
import com.fordefi.fordefi.FordefiExternalEncryption
import com.fordefi.fordefi.FordefiExternalEncryptionKeyType

class MainActivity : ComponentActivity() {
    private var fordefi: Fordefi? = null
    private val keysetID = "<KEYSET_ID>"
		private val encryptionKey = "<ENCRYPTION_KEY>"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
				val encryption = FordefiExternalEncryption(encryptionKey, FordefiExternalEncryptionKeyType.AES256)
        fordefi!!.backupKeyset(
            keysetID,
            encryption) { error ->
            handleBackupKeyset(keysetID, error)
            }
		}

    private fun handleBackupKeyset(keysetID: String, error: FordefiError?) {
        if (error == null) {
            Log.i("FordefiSDK", "Keyset $keysetID was backup successfully")
				} else {
            Log.i("FordefiSDK", 
                String.format("Failed to backup keyset $keysetID: %s", error.description())
            )
        }
    }
}

import FordefiSdk

class ViewController: UIViewController {
    private var fordefi: Fordefi?
    private let keysetID = "<KEYSET_ID>"
    private let encryptionKey = "<ENCRYPTION_KEY>"

    override func viewDidAppear(_ animated: Bool) {
        ...
			self.fordefi?.backupKeyset(keysetID: self.keysetID,
             encryption: FordefiExternalEncryption(
								key: self.encryptionKey,
								type: FordefiExternalEncryptionKeyType.aes256),
	           completionHandler: { error in
		            self.handleBackupKeyset(error: error)
        })
    }

		private func handleBackupKeyset(error: FordefiError?) {
        if error != nil {
            print("Faield to backup keyset. Error: \(error!.errorDescription!)")
            return
        }
    }
}

Recover the device key share

To recover the device key share, pass into the recoverKeyset method the symmetric key used to encrypt the key share. Fordefi's SDK will download the encrypted share from the storage, decrypt, and load it into the SDK.

For example:

const recoverKeysetFn = async (keysetId: string, encryptionKey?: string) => {
    try {
        const backupOptions: ExternalBackupOptions = {
            encryptionKeyType: EncryptionAES256,
            encryptionKey: encryptionKey,
        };
        const result = await recoverKeyset(keysetId, backupOptions);
        console.debug(`Recover Keyset result ${result}`);
    } catch (error: unknown) {
        const sdkError = error as FordefiSdkErrorResult;
        console.error(`Recover Keyset failed ${error}`);
    }
};

import com.fordefi.fordefi.Fordefi
import com.fordefi.fordefi.FordefiError
import com.fordefi.fordefi.FordefiExternalDecryption
import com.fordefi.fordefi.FordefiExternalEncryptionKeyType

class MainActivity : ComponentActivity() {
    private var fordefi: Fordefi? = null
    private val keysetID = "<KEYSET_ID>"
		private val encryptionKey = "<ENCRYPTION_KEY>"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
				val decryption = FordefiExternalDecryption(encryptionKey, FordefiExternalEncryptionKeyType.AES256)
        fordefi!!.recoverKeyset(keysetID, decryption) {
            handleRecoverKeyset(keysetID, error)
        }
		}

    private fun handleRecoverKeyset(keysetID: String, error: FordefiError?) {
        if (error == null) {
            Log.i("FordefiSDK", "Keyset $keysetID was recovered successfully")
				} else {
            Log.i("FordefiSDK", 
                String.format("Failed to recover keyset $keysetID: %s", error.description())
            )
        }
    }
}

import FordefiSdk

class ViewController: UIViewController {
    private var fordefi: Fordefi?
    private let keysetID = "<KEYSET_ID>"
    private let encryptionKey = "<ENCRYPTION_KEY>"

    override func viewDidAppear(_ animated: Bool) {
        ...
			self.fordefi?.recoverKeyset(keysetID: self.keysetID,
                 decryption: FordefiExternalDecryption(key: self.encryptionKey,
                         type: FordefiExternalEncryptionKeyType.aes256),
                 completionHandler: { error in
            self.handleRecoverKeyset(error: error)
        })
    }

		private func handleRecoverKeyset(error: FordefiError?) {
        if error != nil {
            print("Failed to recover keyset. Error: \(error!.errorDescription!)")
            return
        }
    }
}

📘

Note

In future versions, additional backup methods will be supported.