Skip to content
Brett Sutton edited this page Aug 31, 2021 · 5 revisions


DVault was designed to make protecting (encrypting) files and directories simple and secure.

When protecting a file DVault uses the terms 'lock' and 'unlock' to indicate the process of protecting (locking) a file and opening (unlocking) a file.

When you lock a file or directory with DVault it creates a single self contained 'vault' file.

DVault uses a passphrase to protected files, however you only need your passphrase when opening a vault.

DVault works as a simple interactive command line tool but is also designed to be called by other scripts.

DVault supports Linux, Mac OSX and Windows.


For those interested in the gory technical details see the section on RSA and AES below.

Locking a file

When you lock a file with DVault the original file is deleted and replaced with a .vault file which we call a vault.

e.g. important.txt becomes important.txt.vault.

When you unlock a file the vault is deleted and your original file is restored.

e.g. important.txt.vault becomes important.txt

Initialise DVault

After installing DVault you need to run a one time initialisation process:

dvault init
 > Enter passphrase:
 > Confirm passphrase:
 > Generating keys; be patient, this make take a few of minutes.
 > Keys save to ~/.dvault
 > You now need to securely store your passphrase and your .dvault file.

Does the user really need to backup their .dvault file?

We store a copy of it in every vault from where it can be recovered.

If they don't have any vaults to recover the .dvault from then they don't need to recover their .dvault as they can simply create a new one.

Lock the file

To lock a file:

dvault lock important.txt
 > Vault important.txt.vault has been created.

Unlock the file

dvault unlock important.txt.vault
 > Passphrase:
 > Unlocked to important.txt
 > Vault has been unlocked and important.txt restored.

As a .vault file contains the original keys the vault can be copied to any machine and provided you know the passphrase you can always unlock the file.

Send a vault to a friend

If you want to send a vault to a friend you can create a vault using a single use passphrase which you can share with a friend.

Unlike the lock command, the share command leaves your original file intact and creates the .vault file along side it.

The first time you share a file with a friend DVault will generate a unique set of keys for that friend and store those keys in your .dvault file attached to their email address.

The first time you send a vault to a friend it can take a few minutes to generate the keys for them.

TODO: Could we run a background isolate that generates multiple sets of keys when dvault init is first called so we have multiple key sets ready to go. When then permanently assign a key pair to an email address.

If we run out of keys the share command will need to generate keys and ask the user to wait. Again we would generate additional keys (one pair per cpu - 1).

The private key of each sharable key pair is still encrypted using the primary users pass phrase. When we create a shareable vault we copy the assigned keys into the vault and re-encrypt the primary key with the one time pass phrase.

dvault share important.txt
  > Looks like you are going to share a vault with a friend.
  > When prompted enter a passphrase that you can give to your friend.
  > Enter passphrase:
  > Confirm passphrase:
  > Enter your friends email address: 
  > Generating keys; be patient, this make take a few of minutes.
  > Vault important.txt.vault has been created.
  > Call your friend and given them the passphase or send it to them via
  > some other secure means. 
  > Email 'imporantant.txt.vault to your friend'
  > You may also want to send them the following instruction.
  > Please find the attached vault file which contains the documents discussed.
  > To unlock the vault you will need to download and install DVault from
  > The above link also contains instructions on how to unlock the vault.
  > I will ring with the required passphrase shortly.

Change your passphrase

To change your pass phrase use:

dvault passphrase
 > Old passphrase:
 > New passphrase:
 > Confirm New passprhase: 
 > Storing your passphrase.
 > You MUST now securely store your passphrass.

Changing your passphrase can be dangerous as existing vaults will be locked using your old passphrase.

DVault helps reduce this risk by keep a track of your old pass phrases.

If you try to unlock an old vault, DVault will know to use the original pass phrase used when creating the vault.

If we copy the old passphrases into every vault we create, then in theory we could recover old passphrases from vaults. So if the user deletes the .dvault file they only need to find a vault they can open and we then have access to all of their old pass phrases and can restore their .dvault file. Every time we open a vault we could check for a list of passphrases and add any we don't have back into the .dvault. In this way if a .dvault was deleted (multiple times) over time we could recover a full list of pass phrases.

Recover .dvault file

The best way to recover your .dvault file is to not lose it in the first place.

Make certain you have a backup of your .dvault file stored in a secure place.

If you accidently delete your .dvault file all is not lost.

If you know your pass phrase the .dvault file can be recovered from any vault by running the recover command.

dvault recover some_old_vault.vault
 > Passphrase: 
 > Recovering .dvault ...
 > Recovery complete.

Is recover a good name or does it make the user think we can recover an old vault?

If you don't have any vaults then you can simply reinitialise dvault:

dvault init

Installing DVault

There are a couple of ways you can install DVault:

DVault is written in dart so if you have dart installed you can install DVault by running:

pub global activate dvault

The DVault project also provides binaries for each of the supported platforms.

You can download the latest version from one of the following links:

Linux Windows Mac OSX

Initialising DVault

Once you have installed DVault you need to initialise it:

dvault init

DVault will ask you for a passphrase which is used to lock and unlock each vault you create.


When you initialise DVault it generates a set of keys and stores them in your home directory in a file called .dvault.

You are now ready to create vaults.

Advanced initialisation

As well as the simple initialisation described above dvault provides some advanced options for more specialised usages of dvault.

If you need to automate the initialisation of DVault then we support a number of ways to pass in the passphrase.

To change how the passphrase is acquired we use the --cue switch (or -c).

dvault init --cue=ask 

In order from most secure to least secure:

Method Description Example Notes
ask dvault will prompt the user for the passphrase dvault init or dvault init --cue=ask This is the default method and the most secure.
stdin Pipe the passphrase in via standard in `echo 'my passphrase' dvault init --cue=stdin`
env Pass the passphrase via the environment variable DVAULT_PASSPHRASE export DVAULT_PASSPHRASE="my passphrase";dvault init --cue=env
arg Pass the passphrase via a command argument dvault init --cue=arg -P="my passphrase" If you use the -P option you don't actually need to provide the --cue=arg option as its assumed. You can't use the -P option with any other --cue option.

Reporting Security Vulnerabilities and Issues

Security Vulnerabilities should be emailed to:

bsutton at noojee dot com dot au.

All other issues should be raised via the standard github issue tracker.

Vault file format

A DVault vault is a zip file.

You can use any zip tool to unzip the vault and inspect the contents.

Each file added to the vault is individually encrypted, so if need be, you can extract a single file from a vault.

If you encrypt a single file called 'important.txt' to a vault the structure of the vault file is:

dvault lock important.txt
> Vault important.txt.vault has been created.

Contents of important.txt.vault


The .dvault file contains the keys used to encrypt/decrypt the contents of the vault and are protected by your passphrase.

You can also add an entire directory tree to a vault.

If you have the directory tree:


To add the home directory and its immediate contents use:

dvault locked /home
 > Vault home.vault has been created.

Contents of home.vault


You can see from the above listing that the file names are mangaled but the

If the vault was created with the --share option then the contents of the file changes:

dvault unlock --share important.txt
 > Vault has been unlocked and imporant.txt restored.

Contents of important.txt.vault


The presense of the .shared file tells DVault that this file has been shared between two parties and uses a single use passphrase. The unlock process is essentially the same however the messages displayed to the user change to provide some additional guidance to the reciever of the vault.

.dvault format

The .dvault file is stored in your home directory and copied into each vault that you create with the exception of vault's created with the share command. Vaults created via the shared command contain an alternate set of keys.....

The .dvault file contains the RSA Keys and a salted copy of your passphrase. The RSA Private key is encrypted using your passphrase using AES as described in the Technical Details section.

salt: <passphrase salt>
passphrase_hash: <hash of passphrase>
 <encrypted private key>

 <contents of public key>                    
<enrypted list of old pass phrases>

Technical details

DVault is intended to be encryption for everyone so we try to avoid technical terminology when describing how DVault works.

But for those that care, we provide the following details on how DVault works.

DVault init generates an RSA key pair which is stored in ~/.dvault.

On Linux and OSX the file permissions is set to 600. On Windows: TODO what do we do on windows?

The private key is encrypted using a 128 bit AES key derived from the entered passphrase. The passphrase is stretched to the full 128 bits with the following algorithm. The interaction count left at the default value of 100.

The specific algorithm is:

  class StrongKey extends Key {
  StrongKey.fromPassPhrase(String passPhrase) : super.fromUtf8(passPhrase);

  Key secureStretch(Uint8List salt) {
    return stretch(256, iterationCount: 100000, salt: salt);

  Key stretch(int desiredKeyLength, {int iterationCount = 100, Uint8List salt}) {
    final params = Pbkdf2Parameters(salt, iterationCount, desiredKeyLength);
    final pbkdf2 = PBKDF2KeyDerivator(Mac('SHA-512/HMAC'))..init(params);

    return Key(pbkdf2.process(bytes));

  static Uint8List get generateSalt => SecureRandom(256).bytes;

DVault is based on pointycastle which is a Dart port of the bouncycastle java encryption library.

The DVault code is open source and can be viewed at: dvault.


  • If someone gets hold of your passphrase they can unlock all of your vaults.
    • DVault is an offline encrypt/decryption tool. As such it has no means of revoking a set of keys that have been compromised.
  • The integrity of the DVaults encryption techniques have not be verified by a third party.