VESrepo
libVES.js
libVES.c
VESauth
$>ves
TOS
VES CLI Utility
Overview
VESvault: Simple, Safe and Secure Encryption At-rest
  • Simple
    • Browser-based PIN entry unlocks the User's cryptographic keychain.
    • The User can easily sync the encryption keys among multiple personal devices and browsers/apps.
  • Safe
    • The user can add redundant key locations for safety from key loss.
    • VESrecovery™ for recovering the key chain via friends' assistance without compromising the User's privacy.
  • Secure
    • Brute force protection with VESlocker hardware-grade PIN security.
    • End-to-end encryption using industry standard algorithms with cryptographic grade keys.
VES utility (default command: ves) is a platform independent command line tool, an interface to libVES.c API library.
VES utility operates with end-to-end encrypted data stored in the VESvault cloud repository.
The latest source code of libVES.c and VES utility can be found in the GitHub repository.
Pre-build for *nix and exe for win32 are available in the releases.
VES Utility Usage
ves -A myaccount@gmail.com -a ves://demo/myaccount@gmail.com/ -n -upf my.key
Log in to an existing VESvault account myaccount@gmail.com (VES utility will prompt to enter the password and the primary VESkey).
Create a new App Vault within an App Domain demo, assign an external ID myaccount@gmail.com (If an App Vault with the selected external ID already exists, an error message will be shown).
Generate a random VESkey for the App Vault, save it to a local file my.key.
ves -A myaccount@gmail.com -l
List all Vault Items stored in the Primary Vault.
ves -A myaccount@gmail.com -a ves://demo/myaccount@gmail.com/ -upf my.key
Output the currently stored VESkey for the App Vault ves://demo/myaccount@gmail.com/ to a file my.key.
ves: in the beginning of a URI can always be omitted
ves -a //demo/myaccount@gmail.com -uf my.key -o myItem1 -i "My Secret" -s "myfriend1@yahoo.com/My Friend <myfriend1@yahoo.com>"
Unlock the App Vault ves://demo/myaccount@gmail.com/ using a VESkey stored in a local file my.key. Store a secret text "My Secret" in a User Vault Item ves://demo/myItem1 (the App Domain for the item defaults to the App Vault's domain).
If the item didn't exist, it will be created.
Share the item with an App Vault ves://demo/myfriend1@yahoo.com/, so the VESkey for ves://demo/myfriend1@yahoo.com/ can be used to decrypt the content of this item.
If this App Vault didn't exist, create a temporary App Vault key belonging to a VESvault account myfriend1@yahoo.com.
If this VESvault account didn't exist, create a pending account and send a setup link to an email address myfriend1@yahoo.com.
ves -a //demo/myaccount@gmail.com/ -uf my.key -l
List all Vault Items stored in the App Vault ves://demo/myaccount@gmail.com/.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -ip
Print the content of the Vault Item ves://demo/myItem1. If the item didn't exist, or wasn t shared with App Vault ves://demo/myaccount@gmail.com/, an error will be thrown.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -s myfriend2@yahoo.com/
Share the Vault Item ves://demo/myItem1 with an App Vault ves://demo/myfriend2@yahoo.com/. If this App Vault doesn't exist, an error will be thrown.
The sharing status of the item with any other App Vaults will remain unchanged.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -S myaccount@gmail.com/,//x-my-domain/myfriend3@yahoo.com/myfriend3@yahoo.com
Share the Vault Item ves://demo/myItem1 with App Vaults ves://demo/myaccount@gmail.com/ and ves://x-my-domain/myfriend3@yahoo.com/.
The latter App Vault will be automatically created for user myfriend3@yahoo.com if it didn't exist.
If the item was shared with any other vaults, the sharing will be removed.
The sharing list must include an App Vault of the item's onwer, otherwise an error will be thrown.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -X
Explore the Vault Item ves://demo/myItem1 – display various information about the item in a human readable format.
Explore is the default action, -X can be omitted if no other actions are specified.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher1 -e -Pf test.txt -Cf encrypted.ves -s myfriend1@yahoo.com/
Create a stream cipher with a random key using the default algorithm. Store the cipher key in a User Vault Item ves://demo/myCipher1.
Encrypt an existing local file test.txt with the cipher, save the encrypted content to a local file encrypted.ves.
Share the cipher key with an existing App Vault /demo/myfriend1@yahoo.com.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher1 -d -Pf decrypted.txt -Cf encrypted.ves -ipf cipher.key
Decrypt a local file encrypted.ves using the stream cipher info stored in the Vault Item ves://demo/myCipher1.
Save the encrypted content to a local file decrypted.txt.
Save the raw binary cipher key data to a local file cipher.key.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher2 -c AES256GCM1K -if cipher.key -e -Pf test.txt -Cf encrypted2.ves
Create a stream cipher with a raw key loaded from a file cipher.key using algorithm AES256GCM1K.
Store the cipher info in a User Vault Item ves://demo/myCipher2.
Encrypt an existing local file test.txt with the cipher, save the encrypted content to a local file encrypted2.ves.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher2 -D
Delete the Vault Item ves://demo/myCipher2.
Deleted and overwritten items are stored in VESvault for some time, and can be accessed by their internal VESvault ID.
ves -a //demo/myaccount@gmail.com/ -uf my.key -l
List all Vault Items stored in the App Vault ves://demo/myaccount@gmail.com/.
Demo App Vault
The existing App Vault ves://demo/demo/, with App VESkey demo, can be used by anyone for test purposes.
Do not store any private information in the Demo App Vault. There is no privacy expectation associated with the Demo App Vault, as its VESkey is publicly available.
Command Line Options
Authentication and Vault Management
-a URI, --account=URI
Select an App Vault. REF is an App Vault URI, [ves:]//domain/externalID/.
This option is required for most operations.
-u VESKEY, --unlock=VESKEY
Unlock the App Vault using the VESKEY.
-uf FILE
Read the VESkey from FILE.
Since the command line arguments can be visible to other processes in the system, it is not secure to pass an opentext VESkey in a command line. This option is recommended to be used with -f modifier to read the VESkey from a file with restricted access - -uf FILENAME.
-up, -upf FILE
Print the VESkey that unlocks the App Vault selected with -a.
Since the App VESkeys are stored in the Primary Vault, this option is intended to be used in conjunction with -A.
If used with -f modifier - the App VESkey will be saved to the file that can be used later with -uf FILE.
-A LOGIN, --primary=LOGIN
Select a Primary Vault. LOGIN is an email address associated with a VESvault account, or a Primary Vault URI (ves:////userRef).
-T TOKEN, --token=TOKEN
Authorize the API session using a token created by another session or by delegate login.
-Tp, -Tpf FILE
Print the Session Token assigned to the current API session.
-L, --lock
Authorize the API session but keep the Vault locked.
If used with -A – do not ask for primary VESkey.
If used with -a – the App Vault needs to be unlocked to decrypt the session authorization token, lock the Vault upon that.
-n, --new
Create an App Vault identified by -a.
-a and -A are required. -G, -y and -u will be used when generating the Vault Key if provided.
Vault Item Operations:
-o URI, --vault-item=URI
Select a Vault Item for further actions. URI is a VES Vault Item URI, [ves:][//domain/]externalId or [ves:]///internalId.
-i DATA, item=DATA
Set the raw content of the Vault Item
-if FILE
Content for the Vault Item is to be retrieved from FILE.
Vault Items in VESvault repository are subject to 16K soft size limit. For large files, stream encryption should be used. See -e, -d, -P and -C.
-ip, -ipf FILE
Print the raw content of the Vault Item
-s URI[, URI...], --share=...
Share the Vault Items with specified Vaults identified by Vault URIs, [ves:][//domain/]externalId/[userRef]. Any previously existing shares will other vaults will remain intact.
-r URI[, URI...], --unshare=...
Stop sharing the Vault Item with the Vaults identified by URIs. Sharing with any other Vaults will remain intact.
-S URI[, URI...], --set-share=...
Share the Vault Items with the Vaults identified by the URIs, and only with these Vaults. Previously existing shares with any other Vaults will be removed.
The list of URIs must include the creator's Vault, otherwise the API will reject the action.
-m JSON, --meta=JSON
Specify plaintext metadata for the Vault Item. 16K size limit applies.
The Vault Item metadata is stored in an unencrypted form. Do not store any private information here, use cipher metadata -z instead.
-mp, -mpf FILE
Print JSON plaintext Vault Item metadata.
--delete
Delete the Vault Item
Deleted Vault Item can be accessed by internal id for some time - ves:///internalId. -U can be used to restore a deleted item.
-U, --force
Force the update of the Vault Item. Suppress an error on unsafe operations, such as overwriting a cipher key.
If the Vault Item is shared with any lost Vault Key, -U will reshare the item with the currently active key for the target Vault.
When used on a deleted Vault Item, the item will be restored and shared with the same Vaults it was shared before the deletion, unless directed otherwise by -s | -r | -S.
Stream Cipher Operations:
All Stream Cipher actions require -o to select the Vaut Item that stores the symmetric cipher key, and can be combined with other Vault Item options.
-c ALGO, --cipher ALGO
Create a new stream cipher key for ALGO.
Can be combined with -i to supply a raw binary key. Otherwise the key will be generated randomly.
-cp, -cpf FILE
Print the algorithm of the cipher key.
Results in a error if the Vault Item does not store a cipher key.
-cl
List supported stream cipher algorithms.
-z JSON, --cipher-meta=JSON
Specify secret metadata for the cipher key.
The secret metadata is stored in an encrypted form along with the cipher key.
Subject to 16K soft limit for an encrypted Vault Item size.
-zp, -zpf FILE
Print JSON secret cipher metadata.
-e, --encrypt
Encrypt a file or a stream using the stream cipher key.
The plaintext input is specified by -P, defaults to STDIN.
The ciphertext output is specified by -C, defaults to STDOUT.
If the selected Vault Item did not exist, or did not store a cipher key, a new cipher key will be generated.
-d, --decrypt
Decrypt a file or a stream using the stream cipher key.
The ciphertext input is specified by -C, defaults to STDIN.
The plaintext output is specified by -P, defaults to STDOUT.
-P[f] FILE, --plaintext=FILE
Select a plaintext file for -e | -d
-C[f] FILE, --ciphertext=FILE
Select a ciphertext file for -e | -d
Vault Key Operations:
Vault Key operations that produce output – -l and -*p – apply to:
  • The Vault Key selected with -k,
  • if -k is not supplied – to the App Vault Key selected with -a,
  • if -a is not supplied either – to the current Primary Vault Key selected with -A.
Vault Key operations that supply a value - -y, -G, -v – apply to every generated Vault Key:
  • A newly generated App Vault Key when used with -n,
  • A Vault Key generated for a Vault identified by -k, if it didn't exist or was forced by -g,
  • Every Temporary Vault Key generated when sharing with non-existing Vaults - -s | -S.
Using same private key and/or VESkey for temp keys created for different users is a potential security issue.
-k URI, --vault-key=URI
Select a Vault Key for further operations. The URI is a Vault URI, [ves:][//domain/]externalId/[userRef].
-l, --list
List all Vault Items shared with the Vault Key.
-v VESKEY, --veskey=VESKEY
Supply a VESkey for any generated Vault Keys, and/or to unlock the key specified with -k.
The latter case is useful lost Vault Keys, and for Temporary Vault Keys when the VESkey is communicated out of system instead of using key propagation.
-vp, -vpf FILE
Print the VESkey that unlocks the Vault Key.
Can be used only if the Vault Key is unlocked indirectly by a VESkey stored in a vault.
-g, --generate
Force generation of a new Vault Key to replace the selected Vault Key. API restrictions apply.
-y KEY, --private-key=KEY
Supply a PEM private key for the generated Vault Key.
-yf is more practical than plain -y.
-yf FILE
Private key from the PEM FILE.
-yp, -ypf FILE
Print the PEM private key, non-encrypted if the Vault Key is unlocked, encrypted otherwise.
-Y[p], --public-key, -Ypf FILE
Print a PEM public key.
-G ALGO, --key-algo=...
Specify an algorithm to generate the Vault Key.
-Gp, -Gpf FILE
Print the name of the selected Vault Key algorithm.
-Gl
List supported Vault Key algorithms.
--delete
Delete the Vault Key. API restrictions apply.
-R, --rekey
Rekey the Vault Key – re-encrypt all Vault Items with the active key for the matching Vault. Useful for temp keys, and for lost and found keys.
Rekeying is done automatically for temp keys, unless -M is specified.
-K, --propagate
Propagate the Vault Key – share the Vault Item that stores the VESkey with the owner of the Vault Key.
Propagation is done automatically for temp keys, unless -M is specified.
-M, --manual
Manual key management – disable automatic propagation and rekeying for Temporary Vault Keys.
Action Modifiers:
-p, --print
Print the current value of the preceding option.
Can be used with almost any option that supplies a value, as listed in the preceding sections.
-f FILE, --flie=...
Read a value from, or write to, a file.
Can be used with any option that supplies a value, or produces an output.
-F FDESC, --fd=...
Read a value from, or write to, a file descriptor.
Similarly to -f, can be used with any option that supplies a value, or produces an output.
Miscellaneous:
-x, --debug
Display debugging messages.
-xx
More detailed debugging.
-q, --quiet
Suppress error messages, except for arg errors. Return error codes only.
Can be used with -o to check if the Vault Item exists. The exit code is: No authorization is needed to check for existance of a Vault Item.
-V, --version
Print version information and exit
-h, --help
Print this help screen and exit
Exit Codes
VESvault  »  Developer Center
© 2024 VESvault Corp