virgil

README

Virgil Security Go SDK

Introduction | SDK Features | Installation | Usage Examples | Docs | Support

Introduction

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
• use your own Crypto

Installation

The Virgil Go SDK is provided as a package named virgil. The package is distributed via github. Also in this guide, you find one more package called Virgil Crypto (Virgil Crypto Library) that is used by the SDK to perform cryptographic operations.

The package is available for Go 1.10 or newer.

Installing the package:

• go get -u gopkg.in/virgil.v5/sdk

Crypto library notice

The built in crypto library supports only following primitives:

• ED25519 keys
• SHA512 hashes
• AES256_GCM encrypting

and is not recommended for production use.

On linux and macOS consider using external crypto library written in c++

Using external crypto library (c++)

go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
cd $GOPATH/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5
make

in your source code use crypto objects from this library as follows:

var (
	crypto      = virgil_crypto_go.NewVirgilCrypto()
	cardCrypto  = virgil_crypto_go.NewCardCrypto()
	tokenSigner = virgil_crypto_go.NewVirgilAccessTokenSigner()
)

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 lines of code to create and publish a user's Card with Public Key inside on Virgil Cards Service:

import (
	"gopkg.in/virgil.v5/sdk"
	"gopkg.in/virgilsecurity/virgil-crypto-go.v5"
)

var (
	crypto      = virgil_crypto_go.NewVirgilCrypto()
	cardCrypto  = virgil_crypto_go.NewVirgilCardCrypto()
	tokenSigner = virgil_crypto_go.NewVirgilAccessTokenSigner()
)

func main() {

	// generate a key pair
	keypair, err := crypto.GenerateKeypair()

	// save a private key into key storage
	err = privateKeyStorage.Store(keypair.PrivateKey(), "Alice", nil)
	if err != nil{
		//handle error
	}
	// publish user's on the Cards Service
	card, err := cardManager.PublishCard(&sdk.CardParams{
		PublicKey:  keypair.PublicKey(),
		PrivateKey: keypair.PrivateKey(),
		Identity:   "Alice",
	})

	if err != nil{
		//handle error
	}

}

Sign then encrypt data

Virgil SDK lets you 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 on which we will encrypt the data and verify a signature.

import "gopkg.in/virgilsecurity/virgil-crypto-go.v5"

var (
	crypto      = virgil_crypto_go.NewVirgilCrypto()
	cardCrypto  = virgil_crypto_go.NewVirgilCardCrypto()
	tokenSigner = virgil_crypto_go.NewVirgilAccessTokenSigner()
)

func main() {
	messageToEncrypt := []byte("Hello, Bob!")

	// prepare a user's private key from a device storage
	alicePrivateKey, err := privateKeyStorage.Load("Alice")
	if err != nil{
		//handle error
	}


	// using cardManager search for Bob's cards on Cards Service
	cards, err := cardManager.SearchCards("Bob")

	if err != nil{
		//handle error
	}

	// sign a message with a private key then encrypt using Bob's public keys
	encryptedMessage, err := crypto.SignThenEncrypt(messageToEncrypt, alicePrivateKey, cards.ExtractPublicKeys()...)

	if err != nil{
		//handle error
	}
}

Decrypt then verify data

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:

import "gopkg.in/virgilsecurity/virgil-crypto-go.v5"

var (
	crypto      = virgil_crypto_go.NewVirgilCrypto()
	cardCrypto  = virgil_crypto_go.NewVirgilCardCrypto()
	tokenSigner = virgil_crypto_go.NewVirgilAccessTokenSigner()
)

func main() {
	// prepare a user's private key
	bobPrivateKey, err := privateKeyStorage.Load("Bob")
	if err != nil{
		//handle error
	}

	// using cardManager search for Alice's cards on Cards Service
	aliceCards, err := cardManager.SearchCards("Alice")

	if err != nil{
		//handle error
	}

	// decrypt with a private key and verify using one of Alice's public keys
	decryptedMessage, err := crypto.DecryptThenVerify(encryptedMessage, bobPrivateKey, cards.ExtractPublicKeys()...)

	if err != nil{
		//handle error
	}
}

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 first configure your application. 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
  • Setup your own Crypto library inside of the SDK
• 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

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.

Documentation

Index

• Constants
• func GetAgentHeader() string

Constants

const (
	// Version represents passw0rd SDK version
	Version = "v5"
)

Functions

func GetAgentHeader

func GetAgentHeader() string