Developer Guide

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 backupKey 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 backupKeysFn = async (encryptionKey?: string) => {
    try {
        const backupOptions: ExternalBackupOptions =  {
            encryptionKeyType: EncryptionAES256,
            encryptionKey: encryptionKey,
        };
        const result = await backupKeys(backupOptions);
        console.debug(`Update Backup result ${result}`);
    } catch (error: unknown) {
        const sdkError = error as FordefiSdkErrorResult;
        console.error(`Update 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 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", "success")
				} else {
            Log.i("FordefiSDK", 
                String.format("Failed to backup keys: %s", error.description())
            )
        }
    }
}

import FordefiSdk

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

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

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

Recover the device key share

To recover the device key share, pass into the recoverKeys 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 recoverKeysFn = async (encryptionKey?: string) => {
    try {
        const backupOptions: ExternalBackupOptions = {
            encryptionKeyType: EncryptionAES256,
            encryptionKey: encryptionKey,
        };
        const result = await recoverKeyset(backupOptions);
        console.debug(`Recover Keys result ${result}`);
    } catch (error: unknown) {
        const sdkError = error as FordefiSdkErrorResult;
        console.error(`Recover Keys 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 encryptionKey = "<ENCRYPTION_KEY>"

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

    private fun handleRecoverKeyset(error: FordefiError?) {
        if (error == null) {
            Log.i("FordefiSDK", "Key was recovered successfully")
				} else {
            Log.i("FordefiSDK", 
                String.format("Failed to recover key: %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?.recoverKeys(
                 decryption: FordefiExternalDecryption(key: self.encryptionKey,
                         type: FordefiExternalEncryptionKeyType.aes256),
                 completionHandler: { error in
            self.handleRecoverKey(error: error)
        })
    }

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

📘

Note

In future versions, additional backup methods will be supported.