Home

Virgil Security CLI

• Quickstart
• Motivation
  • Using Virgil CLI with committing to services
    • Generate Keys
    • Create a Global Virgil Card
    • Encrypt and decrypt data
    • Sign and verify data
  • Using virgil-cli without committing to services
    • Encrypt and decrypt data
    • Sign and verify data
• Build: Unix
  • Unix toolchain
  • Unix build steps
• Build: Windows MSVC
  • Windows MSVC toolchain
  • Windows MSVC build steps
• License
• Contacts

Quickstart

Motivation

The Virgil program is a command line tool for using Virgil Security stack functionality:

• encrypt, decrypt, sign and verify data;
• interact with Virgil Keys Service;
• interact with Virgil Private Keys Service.

Using Virgil CLI with committing to services

Let's create two users Alice and Bob and demonstrate the communication between them.

mkdir alice
mkdir bob

Scenario for Alice is shown below, particularly Generate Keys and Create a Global Virgil Card. The same actions are performed for Bob.

Generate Keys

1. A private key is generated in the Private Keys Service with a default Elliptic 384-bits NIST Curve scheme. You will be asked to enter the Private key password:

   virgil keygen -o alice/private.key
   

2. A public key is generated in the Keys Service using the private key.

   virgil key2pub -i alice/private.key -o alice/public.key
   

Create a Global Virgil Card

A Virgil Card is the main entity of the Keys Service, it includes the information about the user and his public key. The Virgil Card identifies the user by one of his available types, such as an email, a phone number, etc. Global Card is created with the validation token received after verification in Virgil Identity Service.

virgil card-create-global -d alice@domain.com --public-key alice/public.key -k alice/private.key -o alice/alice.vcard

Encrypt and decrypt data

Encrypt:

• Bob encrypts plain.txt for Alice.

• Bob needs Alice's Global Card to encrypt some data for her.

• He can get it from the Keys Service by indicating Alice's email.

    virgil encrypt -i plain.txt -o plain.txt.enc email:alice@domain.com
  

Decrypt:

• Alice decrypts plain.txt.enc.

• Alice uses her private key and her Card.

    virgil decrypt -i plain.txt.enc -k alice/private.key -r vcard:alice/alice.vcard
  

Sign and verify data

Sign:

• Alice signs plain.txt before passing it to Bob.

• Alice's private key is used to create a signature.

    virgil sign -i plain.txt -o plain.txt.sign -k alice/private.key
  

Verify:

• Bob verifies plain.txt.sign.

• He must have Alice's Virgil Card to verify the signature.

    mkdir alice-domain
    virgil card-search-global -e alice@domain.com -o alice-domain/
    virgil verify -i plain.txt -s plain.txt.sign -r vcard:alice-domain/alice.vcard
  

Using virgil-cli without committing to services

Encrypt and decrypt data

Encrypt:

• Alice encrypts plain.txt for Bob.

• Alice needs Bob's public key and his identifier to encrypt some data for him.

• pubkey is an argument, which contains sender's public key and recipient's identifier.

• Recipient's identifier is a plain text, which is needed for the Public key association.

    virgil encrypt -i plain.txt -o plain.txt.enc pubkey:bob/public.key:ForBob
  

Decrypt:

• Bob decrypts plain.txt.enc.

• Bob uses his private key and the identifier, which has been provided by Alice.

    virgil decrypt -i plain.txt.enc -k bob/private.key -r id:ForBob
  

Sign and verify data

Sign:

• Alice signs plain.txt before passing it to Bob.

• Alice's private key is used to create a signature.

    virgil sign -i plain.txt -o plain.txt.sign -k alice/private.key
  

Verify:

• Bob verifies plain.txt.sign.

• He need's Alice's public key to verify the signature.

    virgil verify -i plain.txt -s plain.txt.sign -r pubkey:alice/public.key
  

Build Unix

• Compiler:

  • g++ (version >= 4.8.5), or
  • clang++ (version >= 3.5)

• CMake (accessible in command prompt). Minimum version: 3.2.

• Git (accessible in command prompt).

• libcurl-devel + SSL

• For Ubuntu (package libcurl4-openssl-dev):

       apt-get -y install git libcurl4-openssl-dev
  

• For Mac OS X:

      brew install curl --with-openssl
  

Unix build steps

1. Open terminal.

2. Clone project.

      git clone https://github.com/VirgilSecurity/virgil-cli.git
   

3. Go to the project's folder.

      cd virgil-cli
   

4. Checkout specific branch.

      git checkout release
   

5. Create folder for the build purposes and go to it.

      mkdir build && cd build
   

6. Configure, build and install.

      cmake .. && make -j4 && sudo make install
   

7. Check installation.

      virgil --version
   

Build Windows MSVC

Windows MSVC toolchain

• Visual Studio 2015
• CMake (accessible in command prompt). Minimum version: 3.2.
• Git (accessible in command prompt).
• NSIS.

Windows MSVC build steps

1. Open Visual Studio Command Prompt.

2. Clone project.

      git clone https://github.com/VirgilSecurity/virgil-cli.git
   

3. Go to the project's folder.

      cd virgil-cli
   

4. Checkout specific branch.

      git checkout release
   

5. Create folder for the build purposes and go to it.

      mkdir build
      cd build
   

6. Configure, build and make installer.

      cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ..
      nmake
      nmake package
   

7. Check installer under build directory.

      dir /B | findstr /R /C:"virgil-cli-*"
   

License

BSD 3-Clause. See LICENSE for details.

Contacts

Email: support@virgilsecurity.com