Backup Archive Encryption

This document will eventually describe in minute detail the scheme that we use to encrypt and decrypt backups.

class ArchiveEncryptionState()

ArchiveEncryptionState encapsulates key primitives and wrapped secrets that can be safely serialized to the filesystem. An ArchiveEncryptionState is used to compute the necessary keys for encrypting a backup archive.

ArchiveEncryptionState.ArchiveEncryptionState

ArchiveEncryptionState.backupAuthKey

type: CryptoKey

The AES-GCM key that will be used to authenticate the owner of the backup.

ArchiveEncryptionState.nonce

type: Uint8Array

A nonce computed when wrapping the private key and OSKeyStore secret.

ArchiveEncryptionState.publicKey

type: CryptoKey

The RSA-OAEP public key that will be used to derive keys for encrypting backups.

ArchiveEncryptionState.salt

type: Uint8Array

A salt computed for the PBKDF2 stretching of the recovery code.

ArchiveEncryptionState.wrappedSecrets

type: Uint8Array

The wrapped static secrets, including the RSA-OAEP private key, and the OSKeyStore secret.

ArchiveEncryptionState.GENERATED_RECOVERY_CODE_LENGTH

type: number

The number of characters to generate with a CSRNG (crypto.getRandomValues) if no recovery code is passed in to enable();

ArchiveEncryptionState.VERSION

type: number

The current version number of the ArchiveEncryptionState. This is encoded in the serialized state, and is also used during calculation of the salt in enable().

ArchiveEncryptionState.serialize()

Serializes an ArchiveEncryptionState instance into an object that can be safely persisted to disk.

Returns:

Promise.<object>

static ArchiveEncryptionState.initialize(stateDataOrRecoveryCode)

Constructs a new ArchiveEncryptionState. If a stateData object is passed, the ArchiveEncryptionState will attempt to be deserialized from it - otherwise, new state data will be generated automatically. This might reject if the user is prompted to authenticate to their OSKeyStore, and they cancel the authentication.

Arguments:

• stateDataOrRecoveryCode (object|string|undefined) – Either the object generated via serialize(), a recovery code to be used to generate the state, or undefined.

Returns:

Promise.<InitializationResult>