Skip to content
Vlad Evka edited this page Jun 22, 2016 · 48 revisions

Virgil Security CLI

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. Create folder for the build purposes and go to it.

       mkdir build && cd build
    
  5. Configure, build and install.

       cmake .. && make -j4 && make install
    
  6. Check installation.

       virgil --version
    

Build Windows MSVC

Windows MSVC toolchain

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. Create folder for the build purposes and go to it.

       mkdir build
       cd build
    
  5. Configure, build and make installer.

       cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ..
       nmake
       nmake package
    
  6. 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

Clone this wiki locally