Sign a Card with an additional key

This guide shows how to sign a Card with an additional private key for providing your digital solution with the highest level of security.

When you care about your security, you shouldn't trust anyone. Thus, to be sure that a user's Card wasn't replaced with another one, you have to add an additional signature into a Card.

Before publishing a user's Card on Virgil Cards Service, we recommend that you sign a Card with an additional private key, for example, the private key of your Application Server.

Remember, you cannot change a Card's content after it's published.

Generate a Private Key

You can generate a private key for your server and save it in a secure key storage with the following code:

#include 

using virgil::sdk::crypto::Crypto;
using virgil::sdk::VirgilByteArrayUtils;

// generate a key pair
Crypto crypto;
auto keyPair = crypto.generateKeyPair();

// export private and public key
auto privateKeyData = crypto.exportPrivateKey(keyPair.privateKey(), "");
auto publicKeyData = crypto.exportPublicKey(keyPair.publicKey());

// Save it securely
auto privateKeyStr = VirgilBase64::encode(privateKeyData);

// Embed it in client-side apps
auto publicKeyStr = VirgilBase64::encode(publicKeyData);

using VirgilCryptoApiImpl;

// generate a key pair
var crypto = VirgilCrypto();
var keyPair = crypto.GenerateKeys();

// export private and public key
var privateKeyData = crypto.ExportPrivateKey(keyPair.PrivateKey, password: "");
var publicKeyData = crypto.ExportPublicKey(keyPair.PublicKey);

// Save it securely
var privateKeyStr = Convert.ToBase64String(privateKeyData);

// Embed it in client-side apps
var publicKeyStr = Convert.ToBase64String(publicKeyData);

    // generate a key pair
    keypair, err := crypto.GenerateKeypair()
    if err != nil {
        //handle error
    }

    // export private and public key
    privateKeyData, err := crypto.ExportPrivateKey(keypair.PrivateKey(), "")
    if err != nil {
        //handle error
    }
    publicKeyData, err := crypto.ExportPublicKey(keypair.PublicKey())
    if err != nil {
        //handle error
    }

    // Save it securely
    privateKeyStr := base64.StdEncoding.EncodeToString(privateKeyData)

    // Embed it in client-side apps
    publicKeyStr := base64.StdEncoding.EncodeToString(publicKeyData)

// generate a key pair
VirgilCrypto crypto = new VirgilCrypto();
VirgilKeyPair keyPair = crypto.generateKeys();

// export private and public key
byte[] privateKeyData = crypto.exportPrivateKey(keyPair.getPrivateKey(), "");
byte[] publicKeyData = crypto.exportPublicKey(keyPair.getPublicKey());

// Save it securely
String privateKeyStr = ConvertionUtils.toBase64String(privateKeyData);

// Embed it in client-side apps
String publicKeyStr = ConvertionUtils.toBase64String(publicKeyData);

// bootstrap.js

import { VirgilCrypto } from 'virgil-crypto';

const virgilCrypto = new VirgilCrypto();
const keyPair = virgilCrypto.generateKeys();

// Get raw private and public keys bytes from the key pair object
const privateKeyData = virgilCrypto.exportPrivateKey(keyPair.privateKey, 'OPTIONAL_PASSWORD');
const publicKeyData = virgilCrypto.exportPublicKey(keyPair.publicKey);

// Store it securely
const privateKeyBase64 = privateKeyData.toString('base64');

// Embed it in client-side app
const publicKeyBase64 = publicKeyData.toString('base64');

use Virgil\CryptoImpl\VirgilCrypto;

// generate a key pair
$crypto = new VirgilCrypto();
$keyPair = $crypto->generateKeys();

// export private and public key
$privateKeyData = $crypto->exportPrivateKey($keyPair->getPrivateKey(), "");
$publicKeyData = $crypto->exportPublicKey($keyPair->getPublicKey());

// Save it securely
$privateKeyStr = base64_encode($privateKeyData);

// Embed it in client-side apps
$publicKeyStr = base64_encode($publicKeyData);

from virgil_crypto import VirgilCrypto
from virgil_sdk.utils import Utils

# generate a key pair
crypto = VirgilCrypto()
key_pair = crypto.generate_keys()

# export private and public key
private_key_data = crypto.export_private_key(key_pair.private_key, "YOUR_PASSWORD")
public_key_data = crypto.export_public_key(key_pair.public_key)

# Save it securely
private_key_str = Utils.b64encode(private_key_data)

# Embed it in client-side apps
public_key_str = Utils.b64encode(public_key_data)

import VirgilCrypto

// generate a key pair
let crypto = VirgilCrypto()
let keyPair = try! crypto.generateKeyPair()

// export private and public key
let privateKeyData = try! crypto.exportPrivateKey(keyPair.privateKey, password: "")
let publicKeyData = try! crypto.exportPublicKey(keyPair.publicKey)

// Save it securely
let privateKeyStr = privateKeyData.base64EncodedString()

// Embed it in client-side apps
let publicKeyStr = publicKeyData.base64EncodedString()

Also, you can generate a private key using the Virgil CLI.

Sign a user's Card

In order to add the signature of your app server to a user's Card you need to:

transmit an existing user's Card to your server (you must do this before publishing). You can use any suitable way to transmit the Card.

If you need to export a user's Card to a string representation on a client side or import a Card from the string representation on a server side, use the following lines of code:

#include 

using virgil::sdk::client::models::RawSignedModel;

auto signCallBackFunc = [&](const RawSignedModel& rawCard) {
    auto rawCardStr = rawCard.exportAsBase64EncodedString();

    // Send this string to server-side, where it will be signed
    auto futureSignedRawCard = AuthenticatedQueryToServerSide(rawCardStr);

    retutn futureSignedRawCard;
};

using Virgil.SDK;

 Func> signCallBackFunc = async (rawCard) =>
{
    var rawCardStr = rawCard.ExportAsString();
    // Send this string to server-side, where it will be signed
     var response = await AuthenticatedQueryToServerSide(model.ExportAsString());
     var signedRawCard = RawSignedModelUtils.GenerateFromString(response);
    return signedRawCard;
};
cardManagerParams.signCallback = signCallBackFunc;


    params := &sdk.CardManagerParams{}

    params.SignCallback = func(model *sdk.RawSignedModel) (signedCard *sdk.RawSignedModel, err error) {
        rawCardStr, err := model.ExportAsBase64EncodedString()
        if err != nil {
            return nil, err
        }

        // Send this string to server-side, where it will be signed

        //import server's answer
        return sdk.GenerateRawSignedModelFromString(rawCardStr)
    }

SignCallback signCallback = new SignCallback() {

        @Override
        public RawSignedModel onSign(RawSignedModel rawCard) {
            String rawCardStr = rawCard.exportAsBase64String();

            // Send this string to server-side, where it will be signed
            RawSignedModel signedRawCard = new RawSignedModel(rawCardStr);
            return signedRawCard;
        }
};
cardManagerBuilder.setSignCallback(signCallback);

// client.js

import { VirgilCrypto, VirgilCardCrypto } from 'virgil-crypto';
import { CardManager, RawSignedModel, VirgilCardVerifier } from 'virgil-sdk';

const postJson = (url, data) => fetch(url, {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'content-type': 'application/json'
  }
}).then(response => response.json());

const virgilCrypto = new VirgilCrypto();
const cardCrypto = new VirgilCardCrypto(virgilCrypto);
const cardVerifier = new VirgilCardVerifier(cardCrypto, {
  whitelists: [[ {
    // This can be any value except 'virgil' and 'self' and is used to identify
    // your server's signature among other card signatures. Use the same value
    // when signing cards on the server.
    signer: 'YOUR_SERVER_NAME',
    publicKeyBase64: 'SERVER_PUBLIC_KEY_BASE64'
  } ]]
});

const cardManager = new CardManager({
  signCallback: model =>
    // serialize the model to string and send it to your server, where it will be signed
    postJson('/sign-virgil-card', { rawCardStr: model.toString() }).then(res =>
      RawSignedModel.fromString(res.signedRawCardStr)
    ),
  cardCrypto: cardCrypto,
  verifier: cardVerifier,
  // setup accessTokenProvider as usual
});

use Virgil\Sdk\Web\RawSignedModel;

$signCallback = function (RawSignedModel $model) {
    $rawCardStr = $model->exportAsBase64String();

    // Send this string to server-side, where it will be signed

    //import server's answer
    return RawSignedModel::RawSignedModelFromBase64String($rawCardStr);
};

from virgil_sdk.client import RawSignedModel


def sign_callback(model):
    raw_card_str = model.to_string()
    # Send this string to server-side, where it will be signed
    response = authenticated_query_to_server(raw_card_str)
    signed_raw_card = RawSignedModel.from_string(response)
    return signed_raw_card


# Now can use it as argument for CardManager

import VirgilSDK

cardManagerParams.signCallback = { rawCard, completion in
    let rawCardStr = try! rawCard.exportAsBase64EncodedString()
    // Send this string to server-side, where it will be signed
    authenticatedQueryToServerSide(rawCardStr) { response in
        let signedRawCard = try! RawSignedModel.import(fromBase64Encoded: response)

        completion(signedRawCard, nil)
    }
}

sign a transmitted user's Card with a private key of your server:

#include 
#include 

using virgil::sdk::crypto::Crypto;
using virgil::sdk::cards::ModelSigner;

// Receive rawCardStr from a client
auto rawCard = RawSignedModel.importFromBase64EncodedString(rawCardStr);

auto crypto = std::make_shared();
auto signer = ModelSigner(crypto);

// sign a user's card with a server's private key
signer.sign(rawCard, "YOUR_BACKEND", privateKey);

// Send it back to the client
auto newRawCardStr = rawCard.exportAsBase64EncodedString();

using Virgil.Crypto;
using Virgil.SDK;

// Receive rawCardStr from a client
var rawCard = RawSignedModelUtils.GenerateFromString(rawCardStr);

var cardCrypto = new VirgilCardCrypto();
var signer = new ModelSigner(cardCrypto);

// sign a user's card with a server's private key
 var signParams = new SignParams()
{
    Signer = "YOUR_BACKEND",
    SignerPrivateKey = privateKey
};

signer.Sign(rawCard, signParams);

// Send it back to the client
var newRawCardStr = rawCard.ExportAsString();

    // Receive rawCardStr from a client
    rawCard, err := sdk.ImportRawSignedModel(rawCardStr)
    if err != nil {
        //handle
    }

    modelSigner := sdk.NewModelSigner(cardCrypto)

    // sign a user's card with a server's private key
    err = modelSigner.Sign(rawCard, "YOUR_BACKEND", privateKey, nil)
    if err != nil {
        //handle
    }

    // Send it back to the client
    newRawCardStr, err := rawCard.ExportAsBase64EncodedString()

    if err != nil {
        //handle
    }

// Receive rawCardStr from a client
RawSignedModel rawCard = new RawSignedModel(rawCardStr);

CardCrypto cardCrypto = new VirgilCardCrypto();
ModelSigner modelSigner = new ModelSigner(cardCrypto);

// sign a user's card with a server's private key
modelSigner.sign(rawCard, "YOUR_BACKEND", PRIVATE_KEY);

// Send it back to the client
String newRawCardStr = rawCard.exportAsBase64String();

// server.js
import express from 'express';
import bodyParser from 'body-parser';
import { VirgilCrypto, VirgilCardCrypto } from 'virgil-crypto';
import { ModelSigner, RawSignedModel } from 'virgil-sdk';

const virgilCrypto = new VirgilCrypto();
const cardCrypto = new VirgilCardCrypto(virgilCrypto);
const modelSigner = new ModelSigner(cardCrypto);

const serverPrivateKey = virgilCrypto.importPrivateKey(process.env.SERVER_PRIVATE_KEY_BASE64);

const app = express();
app.use(bodyParser.json());

app.post('/sign-virgil-card', (req, res) => {
  const rawCard = RawSignedModel.fromString(req.body.rawCardStr);
  // sign the user's card with your server's private key
  modelSigner.sign({
    model: rawCard,
    // This can be any value except 'virgil' and 'self' and is used to identify
    // your server's signature among other card's signatures. Use the same value
    // when setting up VirgilCardVerifier on the client.
    signer: 'YOUR_SERVER_NAME',
    signerPrivateKey: serverPrivateKey,
    extraFields: {
      // optional custom attributes to store with the signature
    }
  });

  // send it back to the client
  res.json({ signedRawCardStr: rawCard.exportAsString() });
});

use Virgil\CryptoImpl\VirgilCardCrypto;

use Virgil\Sdk\Signer\ModelSigner;
use Virgil\Sdk\Web\RawSignedModel;

// Receive rawCardStr from a client
$rawCard = RawSignedModel::RawSignedModelFromBase64String($rawCardStr);

$cardCrypto = new VirgilCardCrypto();
$signer = new ModelSigner($cardCrypto);

// sign a user's card with a server's private key
$signer->sign($rawCard, "YOUR_BACKEND", $privateKey);

// Send it back to the client
$newRawCardStr = $rawCard->exportAsBase64String();

from virgil_crypto.card_crypto import CardCrypto
from virgil_sdk.client import RawSignedModel
from virgil_sdk.signers import ModelSigner

# Receive raw_card_str from a client
raw_card = RawSignedModel.from_string(raw_card_str)

card_crypto = CardCrypto()
signer = ModelSigner(card_crypto)

# sign a user's card with a server's private key
signer.sign(
    raw_card,
    signer="YOUR_BACKEND",
    signer_private_key=private_key
)

# Send it back to the client
new_raw_card_str = raw_card.to_string()

import VirgilSDK
import VirgilCrypto

// Receive rawCardStr from a client
let rawCard = try! RawSignedModel.import(fromBase64Encoded: rawCardStr)

let cardCrypto = VirgilCardCrypto()
let modelSigner = ModelSigner(cardCrypto: cardCrypto)

// sign a user's card with a server's private key
try! modelSigner.sign(model: rawCard, signer: "YOUR_BACKEND", privateKey: privateKey)

// Send it back to the client
let newRawCardStr = try! rawCard.exportAsBase64EncodedString()

Then Virgil SDK sends back a signed Card to the client side.

setup Virgil Card Verifier. By default, CardVerifier only verifies the signatures of a Card owner and Virgil Cards Service. So when you add an additional signature to users' Cards, you also have to set up CardVerifier.