-
-
Notifications
You must be signed in to change notification settings - Fork 0
Home
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.
TECHNICAL GIBBERISH
For those interested in the gory technical details see the section on RSA and AES below.
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
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.
To lock a file:
dvault lock important.txt
> Vault important.txt.vault has been created.
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.
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.
> **** DO NOT USE YOUR NORMAL DVAULT PASSPHRASE ****
> 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.
> **** DO NOT EMAIL OR TWEET THE PASSPHRASE ****
> 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
> https://github.com/bsutton/dvault/wiki/Shared-Vault
> The above link also contains instructions on how to unlock the vault.
> I will ring with the required passphrase shortly.
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.
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
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
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.
IF YOU FORGET YOUR PASSPHRASE YOU ARE SCREWED. Store it somewhere safely.
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.
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. |
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.
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
/.dvault
/encrypted/important.txt
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:
/home/one.txt
/home/two.txt
/home/user/three.txt
To add the home directory and its immediate contents use:
dvault locked /home
> Vault home.vault has been created.
Contents of home.vault
/.dvault
/.directory
/encrypted/00000001/asdfwvasd
/encrypted/00000001/asdfe
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
/.dvault
/.shared
/encrypted/important.txt
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.
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.
version:1
salt: <passphrase salt>
passphrase_hash: <hash of passphrase>
iv:<IV>
---- BEGIN DVAULT PRIVATE KEY ----
<encrypted private key>
---- END DVAULT PRIVATE KEY ----
---- BEGIN DVAULT PUBLIC KEY ----
<contents of public key>
---- END DVAULT PUBLIC KEY ----
---- BEGIN OLD PASSPHRASES ----
<enrypted list of old pass phrases>
---- END OLD PASSPHRASES ----
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);
}
@override
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.