@celo/encrypted-backup › "backup"

Module: "backup"

Index

Interfaces

Functions

Functions

createBackup

▸ createBackup(__namedParameters: object): Promise‹Result‹Backup, BackupError››

Defined in packages/sdk/encrypted-backup/src/backup.ts:246

Create a data backup, encrypting it with a hardened key derived from the given password or PIN.

privateremarks Most of this functions code is devoted to key generation starting with the input password or PIN and ending up with a hardened encryption key. It is important that the order and inputs to each step in the derivation be well considered and implemented correctly. One important requirement is that no output included in the backup acts as a "commitment" to the password or PIN value, except the final ciphertext. An example of an issue with this would be if a hash of the password and nonce were included in the backup. If a commitment to the password or PIN is included, an attacker can locally brute force that commitment to recover the password, then use that knowledge to complete the derivation.

Parameters:

▪ __namedParameters: object

Name Type Description
data Buffer‹› The secret data (e.g. BIP-39 mnemonic phrase) to be included in the encrypted backup.
hardening HardeningConfig Configuration for how the password should be hardened in deriving the key.
metadata undefined | object Arbitrary key-value data to include in the backup to identify it.
userSecret Buffer‹› Password, PIN, or other user secret to use in deriving the encryption key.

Returns: Promise‹Result‹Backup, BackupError››

createPasswordEncryptedBackup

▸ createPasswordEncryptedBackup(__namedParameters: object): Promise‹Result‹Backup, BackupError››

Defined in packages/sdk/encrypted-backup/src/backup.ts:202

Create a data backup, encrypting it with a hardened key derived from the given password.

remarks Because passwords have moderate entropy, the total number of guesses is restricted. * The user initially gets 5 attempts without delay. * Then the user gets two attempts every 5 seconds for up to 20 attempts. * Then the user gets two attempts every 30 seconds for up to 20 attempts. * Then the user gets two attempts every 5 minutes for up to 20 attempts. * Then the user gets two attempts every hour for up to 20 attempts. * Then the user gets two attempts every day for up to 20 attempts.

Following guidelines in NIST-800-63-3 it is strongly recommended that the caller apply a password blocklist to the users choice of password.

In order to handle the event of an ODIS service compromise, this configuration additionally hardens the password input with a computational hardening function. In particular, scrypt is used with IETF recommended parameters IETF recommended scrypt parameters

Parameters:

▪ __namedParameters: object

Name Type Description
data Buffer‹› The secret data (e.g. BIP-39 mnemonic phrase) to be included in the encrypted backup.
environment undefined | MAINNET | ALFAJORES -
metadata undefined | object Arbitrary key-value data to include in the backup to identify it.
password string Password to use in deriving the encryption key.

Returns: Promise‹Result‹Backup, BackupError››

createPinEncryptedBackup

▸ createPinEncryptedBackup(__namedParameters: object): Promise‹Result‹Backup, BackupError››

Defined in packages/sdk/encrypted-backup/src/backup.ts:150

Create a data backup, encrypting it with a hardened key derived from the given PIN.

remarks Using a 4 or 6 digit PIN for encryption requires an extremely restrictive rate limit for attempts to guess the PIN. This is enforced by ODIS through the SequentialDelayDomain with settings to allow the user (or an attacker) only a fixed number of attempts to guess their PIN.

Because PINs have very little entropy, the total number of guesses is very restricted. * On the first day, the client has 10 attempts. 5 within 10s. 5 more over roughly 45 minutes. * On the second day, the client has 5 attempts over roughly 2 minutes. * On the third day, the client has 3 attempts over roughly 40 seconds. * On the fourth day, the client has 2 attempts over roughly 10 seconds. * Overall, the client has 25 attempts over 4 days. All further attempts will be denied.

It is strongly recommended that the calling application implement a PIN blocklist to prevent the user from selecting a number of the most common PIN codes (e.g. blocking the top 25k PINs by frequency of appearance in the HIBP Passwords dataset). An example implementation can be seen in the Valora wallet. PIN blocklist implementation

In order to handle the event of an ODIS service compromise, this configuration additionally includes a circuit breaker service run by Valora. In the event of an ODIS compromise, the Valora team will take their service offline, preventing backups using the circuit breaker from being opened. This ensures that an attacker who has compromised ODIS cannot leverage their attack to forcibly open backups created with this function.

Parameters:

▪ __namedParameters: object

Name Type Description
data Buffer‹› The secret data (e.g. BIP-39 mnemonic phrase) to be included in the encrypted backup.
environment undefined | MAINNET | ALFAJORES -
metadata undefined | object Arbitrary key-value data to include in the backup to identify it.
pin string PIN to use in deriving the encryption key.

Returns: Promise‹Result‹Backup, BackupError››

openBackup

▸ openBackup(__namedParameters: object): Promise‹Result‹Buffer, BackupError››

Defined in packages/sdk/encrypted-backup/src/backup.ts:390

Open an encrypted backup file, using the provided password or PIN to derive the decryption key.

Parameters:

▪ __namedParameters: object

Name Type Description
backup Backup Backup structure including the ciphertext and key derivation information.
userSecret Buffer‹› Password, PIN, or other user secret to use in deriving the encryption key.

Returns: Promise‹Result‹Buffer, BackupError››