Virgil Security Ruby SDK

Introduction

<a href=“developer.virgilsecurity.com/docs”> width=“230px” src=“” align=“left” hspace=“10” vspace=“6”></a> Virgil Security provides a set of APIs for adding security to any application. In a few simple steps you can encrypt communication, securely store data, provide passwordless login, and ensure data integrity.

The Virgil SDK allows developers to get up and running with Virgil API quickly and add full end-to-end security to their existing digital solutions to become HIPAA and GDPR compliant and more.

SDK Features

communicate with Virgil Cards Service
manage users' Public Keys
store private keys in secure local storage
use Virgil Crypto library

Installation

The Virgil SDK is provided as a gem named virgil-sdk and available for Ruby 2.1 and newer. The package is distributed via bundler package manager.

To install the package use the command below:

gem install virgil-sdk

or add the following line to your Gemfile:

gem 'virgil-sdk', '~> 4.4'

Initialization

Be sure that you have already registered at the Dev Portal and created your application.

To initialize the SDK at the Client Side you need only the Access Token created for a client at Dev Portal. The Access Token helps to authenticate client's requests.

virgil = VirgilApi.new(access_token: "[YOUR_ACCESS_TOKEN_HERE]")

To initialize the SDK at the Server Side you need the application credentials (Access Token, App ID, App Key and App Key Password) you got during Application registration at the Dev Portal.

# initialize Virgil SDK high-level instance.
context = VirgilContext.new(
    access_token: "[YOUR_ACCESS_TOKEN_HERE]",
    # Credentials are required only to publish and revoke Virgil Cards.
    credentials: VirgilAppCredentials.new(
        app_id: "[YOUR_APP_ID_HERE]",
        app_key_data: VirgilBuffer.from_file("[YOUR_APP_KEY_PATH_HERE]"),
        app_key_password: "[YOUR_APP_KEY_PASSWORD_HERE]"))

virgil = VirgilApi.new(context: context)

Usage Examples

Before start practicing with the usage examples be sure that the SDK is configured. Check out our SDK configuration guides for more information.

Generate and publish user's Cards with Public Keys inside on Cards Service

Use the following code to create and publish user's Card with Public Key inside on Virgil Cards Service:

# generate a new Virgil Key
alice_key = virgil.keys.generate()

# save the Virgil Key into a storage
alice_key.save("[KEY_NAME]", "[KEY_PASSWORD]")

# create a Virgil Card
alice_card = virgil.cards.create("alice", alice_key)

# export the Virgil Card to a string
exported_alice_card = alice_card.export

# transmit the Card to your App Server
# import the Virgil Card from the string
alice_card = virgil.cards.import(exported_alice_card)

# publish the Virgil Card on the Virgil Cards Service
virgil.cards.publish(alice_card)

Sign then encrypt data

Virgil SDK allows you to use a user's Private key and his or her Cards to sign, then encrypt any kind of data.

In the following example, we load a Private Key from a customized Key Storage and get recipient's Card from the Virgil Cards Services. Recipient's Card contains a Public Key which we will encrypt the data and verify a signature with.

# load a Virgil Key from a device storage
alice_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# search for Virgil Cards
bob_cards = await virgil.cards.find("bob")

# prepare a message
message = "Hey Bob, how's it going?"

# sign then encrypt the message
ciphertext = alice_key.sign_then_encrypt(message, bob_cards).to_base64

Decrypt then verify data

Once the Users have received the signed and encrypted message, they can decrypt it with their own Private Key and verify the signature with Sender's Card:

# load a Virgil Key from a device storage
bob_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# get a sender's Virgil Card
alice_card = virgil.cards.get("[ALICE_CARD_ID]")

# decrypt the message
original_message = bob_key.decrypt_then_verify(ciphertext, alice_card).to_s

Docs

Virgil Security has a powerful set of APIs, and the documentation below can get you started today.

In order to use the Virgil SDK with your application, you will need to configure your application first. By default, the SDK will attempt to look for Virgil-specific settings in your application but you can change it during SDK configuration.

Configure the SDK documentation
Setup authentication to make API calls to Virgil Services
Setup Card Manager to manage user's Public Keys
Setup Card Verifier to verify signatures inside of user's Card
Setup Key storage to store Private Keys
More usage examples
Create & publish a Card that has a Public Key on Virgil Cards Service
Search user’s Card by user’s identity
Get user’s Card by its ID
Use Card for crypto operations
Reference API

License

This library is released under the 3-clause BSD License.

Support

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

You can find us on Twitter or send us email support@VirgilSecurity.com.

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