Class: MasterKeyManager

MasterKeyManager(masterKeyFileName, saltFileName)

This class encapsulates the master key in such a way that it is harder to be leaked.

The reason why it is a class and not a simple module is, so that we can move it to another file without exposing the functions to other modules except the keychain. Other files can use it, but they won't be able to decrypt stuff because they don't have access to the object that holds the real master key.

The master key is stored in a file that is encrypted. The encryption is done by another key that is derived from the secret that is supplied by the user. This derivation needs a salt, that also stored in a file. So the loading process of the master key works like this:

  1. load the salt file
  2. derive a symmetric encryption key from the secret and the salt
  3. load the master key file
  4. decrypt the master key with the derived symmetric key and store it in memory until it is unloaded

Constructor

new MasterKeyManager(masterKeyFileName, saltFileName)

Parameters:
Name Type Description
masterKeyFileName string

File that stores the encrypted master key
saltFileName string

File that stores the salt for deriving the encryption key from the secret

Constructs a new master key manager.

Source:

Classes

MasterKeyManager

Methods

(async) loadOrCreateMasterKey(secret) → {Promise.<void>}

Parameters:
Name Type Description
secret string

Loads the stored master key or create a new one if none was previously created.

This will calculate a derived key from the secret and then:

  • master-key file missing: create a new master-key + file encrypted with this derived key
  • master-key file exists: load the master-key from file and decrypt it with this derived key

Function will throw if the secret does not match the already existing master-key file.

Source:
Returns:

Type: Promise.<void>

unloadMasterKey()

Purges the memory from memory.

Source:

ensureMasterKeyLoaded()

Ensures, that the master is loaded, if not it throws.

Source:

(async) changeSecret(oldSecret, newSecret) → {Promise.<void>}

Parameters:
Name Type Description
oldSecret string
newSecret string

Changes the secret needed to unlock the master-key.

This can be done with or without a loaded master key. Throws if the oldSecret is wrong.

Source:
Returns:

Type: Promise.<void>

encryptDataWithMasterKey(data) → {Uint8Array}

Parameters:
Name Type Description
data Uint8Array

Encrypt data with the master key.

Only works if the master key was previously set.

Source:
Returns:

Type: Uint8Array

decryptDataWithMasterKey(cypherAndNonce) → {Uint8Array}

Parameters:
Name Type Description
cypherAndNonce Uint8Array

The data to decrypt

Decrypt data with the master key.

Only works if the master key was previously set.

Source:
Returns:

Type: Uint8Array