Virgil Pythia Go SDK
Introduction | SDK Features | Install and configure SDK | Usage Examples | Docs | Support
Introduction
Virgil Security provides an SDK which lets you implement Pythia protocol.
Pythia is a technology that gives you a new, more secure mechanism that "breach-proofs" user passwords and lessens the security risks associated with weak passwords by providing cryptographic leverage for the defender (by eliminating offline password cracking attacks), detection for online attacks, and key rotation to recover from stolen password databases.
SDK Features
- communicate with Virgil Pythia Service
- manage your Pythia application credentials
- create, verify and update user's breach-proof password
- use Virgil Crypto Pythia library
The Virgil Pythia Go SDK is provided as a package named pythia-go. The package is distributed via GitHub.
The package is available for Go 1.10 or newer.
Install SDK Package
Virgil Pythia SDK uses the Virgil Crypto library to perform cryptographic operations. The Virgil Pythia Go SDK is provided as a package named pythia-go. The package is distributed via GitHub.
The package is available for Go 1.10 or newer.
Step #1. Install a Crypto Library (C++)
There two ways to install the Crypto Library:
The first, if you are building from sources, install prerequisites as described here and then install the library:
go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
cd $(go env GOPATH)/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5
make
The second, if you use Linux x64 or Darwin x64 architecture, you can use the pre-built crypto binaries
for Linux:
CRYPTO_LIB=virgil-crypto-2.4.4-go-linux-x86_64.tgz
or for MacOS:
CRYPTO_LIB=virgil-crypto-2.4.4-go-darwin-17.5-x86_64.tgz
and then install the library:
go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
wget https://cdn.virgilsecurity.com/virgil-crypto/go/$CRYPTO_LIB
tar -xvf $CRYPTO_LIB --strip-components=1 -C $(go env GOPATH)/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5/
Step #2. Installing Virgil Pythia Go package
Install Pythia SDK library with the following code:
go get -u github.com/VirgilSecurity/pythia-go
When you create a Pythia Application on the Virgil Dashboard you will receive Application credentials including: Proof Key and App ID. Specify your Pythia Application and Virgil account credentials in a Pythia SDK class instance.
These credentials are used for the following purposes:
- generating a JWT token that is used for authorization on the Virgil Services
- creating a user's breach-proof password
Here is an example of how to specify your credentials SDK class instance:
package main
import (
"github.com/VirgilSecurity/pythia-go"
)
func main() {
// here set your Virgil account and Pythia Application credentials
ctx, err := pythia.CreateContext("API_KEY", "API_KEY_ID", "APP_ID", "PK.1.PROOF_KEY")
if err != nil{
panic(err)
}
pythia := pythia.New(ctx)
}
Usage Examples
Virgil Pythia SDK lets you easily perform all the necessary operations to create, verify and update user's breach-proof password without requiring any additional actions and use Virgil Crypto library.
First of all, you need to set up your database to store users' breach-proof passwords. Create additional columns in your database for storing the following parameters:
Parameters |
Type |
Size (bytes) |
Description |
salt |
blob |
32 |
Unique random string that is generated by Pythia SDK for each user |
deblindedPassword |
blob |
384 |
user's breach-proof password |
version |
int |
4 |
Version of your Pythia Application credentials. This parameter has the same value for all users unless you generate new Pythia credentials on Virgil Dashboard |
Now we can start creating breach-proof passwords for users. Depending on the situation, you will use one of the following Pythia SDK functions:
CreateBreachProofPassword
is used to create a user's breach-proof password on your Application Server.
VerifyBreachProofPassword
is used to verify a user's breach-proof password.
Create Breach-Proof Password
Use this flow to create a new breach-proof password for a user.
Remember, if you already have a database with user passwords, you don't have to wait until a user logs in into your system to implement Pythia. You can go through your database and create breach-proof user passwords at any time.
So, in order to create a user's breach-proof password for a new database or available one, go through the following operations:
- Take a user's password (or its hash or whatever you use) and pass it into a
CreateBreachProofPassword
function in SDK.
- Pythia SDK will blind a password, send a request to Pythia Service to get a transformed blinded password and de-blind the transformed blinded password into a user's deblinded password (breach-proof password).
// create a new Breach-proof password using user's password or its hash
pwd, err := pythia.CreateBreachProofPassword("USER_PASSWORD")
if err != nil{
panic(err)
}
// save Breach-proof password parameters into your users DB
fmt.Println(pwd.Salt, pwd.DeblindedPassword, pwd.Version)
After performing CreateBreachProofPassword
function you get previously mentioned parameters (Salt
, deblindedPassword
, version
), save these parameters into corresponding columns in your database.
Check that you updated all database records and delete the now unnecessary column where user passwords were previously stored.
Verify Breach-Proof Password
Use this flow when a user already has his or her own breach-proof password in your database. You will have to pass his or her password into an VerifyBreachProofPassword
function:
//get user's Breach-proof password parameters from your users DB
...
// calculate user's Breach-proof password parameters
// compare these parameters with parameters from your DB
err = pythia.VerifyBreachProofPassword("USER_PASSWORD", pwd, false)
if err != nil{
//authentication failed ot throttle reached
}
The difference between the VerifyBreachProofPassword
and CreateBreachProofPassword
functions is that the verification of Pythia Service is optional in VerifyBreachProofPassword
function, which allows you to achieve maximum performance when processing data. You can turn on a proof step in VerifyBreachProofPassword
function if you have any suspicions that a user or Pythia Service were compromised.
Update breach-proof passwords
This step will allow you to use an updateToken
in order to update users' breach-proof passwords in your database.
Use this flow only if your database was COMPROMISED.
How it works:
- Access your Virgil Dashboard and press the "My Database Was Compromised" button.
- Pythia Service generates a special updateToken and new Proof Key.
- You then specify new Pythia Application credentials in the Pythia SDK on your Server side.
- Then you use
UpdateBreachProofPassword
function to create new breach-proof passwords for your users.
- Finally, you save the new breach-proof passwords into your database.
Here is an example of using the UpdateBreachProofPassword
function:
//get previous user's VerifyBreachProofPassword parameters from a compromised DB
...
// set up an updateToken that you got on the Virgil Dashboard
// update previous user's deblindedPassword and version, and save new one into your DB
updatedPwd, err := pythia.UpdateBreachProofPassword("UT.1.2.UPDATE_TOKEN", pwd)
fmt.Println(updatedPwd.DeblindedPassword, updatedPwd.Version)
Docs
Virgil Security has a powerful set of APIs, and the documentation below can get you started today.
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.