Use A User's Card for crypto operations

With a user's Card published on Virgil Cards Service, we can encrypt data and verify a signature using Virgil SDK and Crypto Library.

Prerequisites for work

Install SDK & Setup Virgil Crypto

The Virgil Ruby SDK is provided as a package named virgil-sdk. The package is distributed via bundler package manager.

The package is available for Ruby 2.1 and newer.

Installing the package:

To install the gem use the command below:

gem install virgil-sdk

or add the following line to your Gemfile:

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

Set up authentication on a server side

Collect your Virgil developer credentials

Parameter	Description
APP_ID	ID of your Application at Virgil Dashboard
APP_KEY	A Private Key that is used to sign users' Cards. For security, you will only be shown the App Private Key when the key is created. Don't forget to save it in a secure location for the next step
APP_KEY_PASSWORD	A password to your APP KEY
ACCESS_TOKEN	An unique string that is used to authorize requests on Virgil Services.

Requests to your app server must be authorized. You can use any kind of authentication, for example, Google auth.

Next, you'll set up server-side SDK to sign and approve user's Card.

Here is an example of how to setup server side with an Access Token:

virgil = VirgilApi.new(context: VirgilContext.new(
    access_token: "[YOUR_ACCESS_TOKEN_HERE]",
    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]"))
)

Set up authentication on a client side

In order to make call to Virgil Services, for example, to publish user's Card on Virgil Cards Service you need to have a Access Token. You have to generate for each Application an Access Token on Virgil Dashboard.

With the Access Token we can initialize the Virgil SDK on the client-side to start doing fun stuff like sending and receiving messages.

To initialize the Virgil SDK on a client-side you need to use the following code:

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

Set up Card Verifier

Virgil Card Verifier helps you automatically verify signatures of a User's Card, for example when you get Card from Virgil Cards Service.

By default, CardVerifiers verifies only two signatures - those of a Card owner and Virgil Cards Service.

Set up CardVerifiers with the following lines of code:

app_public_key = VirgilBuffer.from_base64("[YOUR_APP_PUBLIC_KEY_HERE]")

# initialize High Level Api with custom verifiers
virgil = VirgilApi.new(context: VirgilContext.new(
            access_token: "[YOUR_ACCESS_TOKEN_HERE]",
            card_verifiers: [VirgilCardVerifierInfo.new("[YOUR_APP_CARD_ID_HERE]", app_public_key)])
            )

alice_cards = virgil.cards.find("alice")

Encrypt data

Data encryption

Encrypt Data on a Public Key with the following code:

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

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

# encrypt the message using found Virgil Cards
ciphertext = bob_cards.encrypt(message).to_base64

Decrypt data

Once the Users receive the signed and encrypted message, they can decrypt it with their own Private Key. Data decryption

Use the following code to decrypt

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

# decrypt a ciphertext using loaded Virgil Key
original_message = bob_key.decrypt(ciphertext).to_s

Sign data

A valid digital signature gives a recipient reason to believe that the message was created by a known sender, that the sender cannot deny having sent the message, and that the message was not altered in transit.

Creating signature

Use the following code to sign data:

# prepare a message
message = "Hey Bob, hope you are doing well."

# generate signature
signature = alice_key.sign(message)

Verify signature

In order to verify the digital Signature, Bob has to have Alice's Virgil Card

Verify a signature

use the following code to verify a signature:

# search for Virgil Card
alice_card = virgil.cards.get("[ALICE_CARD_ID_HERE]")

# verify signature using Alice's Virgil Card
unless alice_card.verify(message, signature)

    raise "Aha... Alice it's not you."
end

Sign then encrypt data

In order to sign then encrypt data, you need to 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 on which we will encrypt the data and verify a signature.

Sign then encrypt data

Use the following code to sign then encrypt data:

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

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

# prepare the 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 data then verify signature

Once the Users receive the signed and encrypted message, they can decrypt it with their own Private Key and verify signature with a Sender's Card.

Decrypt then verify

Use the following code to decrypt then verify:

# load a Virgil Key from 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

Encrypt Data for multiple recipients

Encrypting for multiple recipients

Use the following code to encrypt data for multiple recipients:

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

# message for encryption
message = "Hey Bob, how's it going?"

# encrypt the message
ciphertext = bob_cards.encrypt(message).to_base64