Virgil CLI

Virgil Security introduces to developers a Virgil CLI – a tool to manage your Virgil account and applications. With minimal configuration, you can start using all of the functionality provided by the Virgil from your favorite terminal program.

• Linux shells – Use common shell programs such as Bash, Zsh, and tsch to run commands in Linux, macOS, or Unix.
• Windows command line – On Microsoft Windows, run commands in either PowerShell or the Windows Command Processor.

Note regarding passwords

Password protected keys are not supported since v5.2.8

Content

• Virgil CLI
  • Content
  • Installation
    • Mac OS
      • Install using Homebrew
      • Install using the package
    • Linux
    • Windows
  • Launching Virgil CLI
  • Manage Virgil Account
    • Register new account
    • Login into account
    • Logout from account
  • Manage Applications
    • Create new application
    • Delete application
    • List applications
    • Update application
    • Use application
    • Create new App Key
    • Delete App Key
    • List App Keys
    • Update App Key
    • Create App Token
    • Delete App Token
    • List App Tokens
  • PureKit Commands
    • Generate all PureKit keys
    • Generate a secret key
    • Generate an Auth key
    • Generate a Backup key pair
    • Generate a Virgil Storage key pair
    • Generate own Signing Key
    • Generate Non-Rotatable Master Secret key
  • Update keys
  • Manage Application Cards
    • Config file
    • Search cards
    • Revoke card
  • Cryptographic operations
    • Generate private key
    • Extract public key
    • Encrypt
    • Decrypt
    • Sign
    • Verify signature
  • SCMS Commands
    • Init SCMS module in application
    • Create DCM certificate
    • Get DCM certificates list
    • Get SCMS devices
  • License
  • Support

Installation

Mac OS

Install using Homebrew

You can install the Virgil CLI with Homebrew using the following command:

$ brew update
$ brew install virgil

Install using the package

Download the latest CLI package here: https://github.com/VirgilSecurity/virgil-cli/releases.

Once you've downloaded the latest .tar.gz Virgil CLI file, double click to unzip it. Rename the unzipped folder to virgil_<latest-version> (virgil_5.0.3 for example) and move it to any folder of your choice.

Launch Terminal and type the following command:

ln -s ~/<full-path-to-virgil-file> /usr/local/bin/virgil

Now you will be able to launch the Virgil CLI using Terminal.

Linux

In order to download and install the CLI using Linux, use the following commands:

# navigate to the folder which you want to download the archive to
cd <folder-name>

# download the latest version of the Virgil CLI using its link from the releases page https://github.com/VirgilSecurity/virgil-cli/releases
wget https://github.com/VirgilSecurity/virgil-cli/releases/download/v<latest-version>/virgil_<latest-version>_Linux_x86_64.tar.gz

# unzip the downloaded archive specifying its name
tar xvfz <downloaded-file>

# move cli to /usr/local/bin
mv virgil /usr/local/bin

Now you will be able to launch the Virgil CLI.

Windows

Download the latest CLI package here: https://github.com/VirgilSecurity/virgil-cli/releases.

Once you've downloaded the latest .zip Virgil CLI file, unzip it and rename the unzipped folder to virgil_<latest-version> (virgil_5.0.3 for example). Move the renamed folder to C:\ProgramFiles and copy the full path to the folder.

Edit the system environmental variables:

1. In Search, search for and then select: System (Control Panel)
2. Click the Advanced system settings link.
3. Click Environment Variables. In the section System Variables, find the PATH environment variable and select it. Click Edit. If the PATH environment variable does not exist, click New.
4. In the Edit System Variable (or New System Variable) window, specify the value of the PATH environment variable (paste the copied full path to Virgil CLI folder). Click OK. Close all remaining windows by clicking OK.

Now you will be able to launch Virgil CLI using Command prompt.

Launching Virgil CLI

Run the CLI with the following command:

virgil.exe
# or just `virgil`

To get more information, run the Virgil CLI or its command with the --help or -h option that displays full help list and available commands.

Manage Virgil Account

Register new account

This command is used to create a new account:

$ virgil register <email>

Login into account

This command is used to open session for account:

$ virgil login

Logout from account

This command is used to close the current session for account:

$ virgil logout

Manage Applications

Create new application

This command is used to create new application:

$ virgil app create <app_name>

Note! You have to verify your email in order to be able to create more than one application

Delete application

This command is used to delete application:

$ virgil app delete <app_id>

List applications

This command is used to print list of all user applications:

$ virgil app list

Update application

This command is used to update name of application:

$ virgil app update <app_id>

Use application

This command allows you to specify the application that will be used by default. In this way, you'll be able you to use CLI commands without specifying app_id where it's needed.

$ virgil use <app_name>

Create new App Key

This command is used to create new App Key for current application:

$ virgil app key create --app_id <app_id> <app-key_name>

Delete App Key

This command is used to delete App Key:

$ virgil app key delete --app_id <app_id> <app-key_id>

List App Keys

This command is used to print list of App Keys of the specified application:

$ virgil app key list --app_id <app_id> 

Update App Key

This command is used to update name of App Key:

$ virgil app key update --app_id <app_id> <app-key_id>

Create App Token

This command is used to create an App Token:

$ virgil app token create --app-id <app-id> --name <name>

Delete App Token

This command is used to delete an App Token:

$ virgil app token delete --app-id <app-id> <name>

List App Tokens

This command is used to get App Tokens list:

$ virgil app token list --app-id <app-id>

PureKit Commands

Generate all PureKit keys

This command is used to generate all Pure key pairs for an application:

$ virgil purekit keygen all

Generate a secret key

This command is used to generate a new Secret key for an application:

virgil purekit keygen secret

Generate an Auth key

This command is used to generate a new Auth key for an application:

$ virgil purekit keygen auth

Generate a Backup key pair

This command is used to generate a Backup key pair for an application:

$ virgil purekit keygen backup

Generate a Virgil Storage key pair

This command is used to generate a Virgil Storage key pair for an application:

$ virgil purekit keygen signing

Generate own Signing Key

This command is used to generate Own Signing key for an application:

$ virgil purekit keygen own

Generate Non-Rotatable Master Secret key

This command is used to generate a new Non-Rotatable Master Secret key:

$ virgil purekit keygen nonrotable-master

Update keys

This command is used to update the Secret key and Service Public key of a Pure application if your database has been compromised or you need to carry out regular rotation of keys and records:

virgil purekit update-keys <Service Public Key> <Secret Key> <Update Token>

You can get your Update Token at Virgil Dashboard by clicking "BEGIN ROTATION PROCESS" button at your application page.

Manage Application Cards

Config file

Config file is a json, with contains APP_KEY, APP_KEY_ID, APP_ID

It could be generated on dashboard or by hands

config file example :

{
  "APP_KEY": "1234567890",
  "APP_KEY_ID": "12345678901234567890",
  "APP_ID": "12345678901234567890"
}

Search cards

This command searches for any Virgil Card by its identity:

$ virgil cards search -c <file> <identity>

flags :
-c  - Config file name.

Revoke card

This command deletes Virgil Card by its id

$ virgil cards revoke -c <file> -i <identity> <card_id>

flags :
-c  - Config file name.
-i  - Card identity, mandatory.

Cryptographic operations

Generate private key

This command generates a User's Private Key:

$ virgil keygen -o <file>

flags :
-o  - Key file name. If omitted, stdout is used.

Extract public key

This command extracts a Public Key from a Private Key:

$ virgil key2pub  -i <file> -o <file>

flags :
-i  - Key's File Name. If omitted, stdin is used.
-o  - Public key's file name. If omitted, stdout is used.

Encrypt

This command encrypts any data for the specified public key(s):

$ virgil encrypt  -i <file> -o <file> -key <public_key_file_1> -key <public_key_file_2> ...,

flags :
-i  - Data to be encrypted - If omitted, stdin is used..
-o  - Encrypted data. If omitted, stdout is used..
-key  - Public key file (could be many files). 

Decrypt

This command decrypts the encrypted data with a Private Key:

$ virgil decrypt  -i <file> -o <file> -key <private_key_file>

flags :
-i  - Data to be decrypted - If omitted, stdin is used.
-o  - Decrypted data. If omitted, stdout is used.
-key  - Private key file. 

Sign

This command signs data with a provided User’s Private Key:

$ virgil sign  -i <file> -o <file> -key <private_key_file>

flags :
-i  - Data to be signed - If omitted, stdin is used.
-o  - The signed data. If omitted, stdout is used.
-key  - Private key file. 

Verify signature

This command signs data with a provided User’s Private Key:

$ virgil verify  -i <file> -s <file> -key <public_key_file> ,

flags :
-i  - File with data which necessary to verify.
-s  - Digest sign.
-key  - Public key file.  If omitted, stdin is used. 

SCMS Commands

Init SCMS module in application

This command inits SCMS services for application:

$ virgil scms init --app-id <app-id> 

Create DCM certificate

Generates DCM certificate for application:

$ virgil scms dcm create --name <dcm_name> --encrypt-pub-key <base64_key> --verify-pub-key <base64_key> --app-token <app_token> 

Get DCM certificates list

Gets DCM certificates for application:

$ virgil scms dcm list --app-token <app_token> 

Get SCMS devices

Gets list of SCMS devices:

$ virgil scms devices list --app-token <app_token> 

License

See LICENSE for details.

Support

Our developer support team is here to help you. Find out more information on our Help Center.

You can find us on [email protected].

Also, get extra help from our support team on Slack.