package module
v3.0.1 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Apr 1, 2020 License: BSD-3-Clause Imports: 16 Imported by: 0


Virgil PureKit Go

Build Status Release version GitHub license API Reference

Introduction | Features | Benefits | Installation | Resources | License | Support


Virgil Security introduces Virgil PureKit - an open-source security framework for enabling post-compromise protection for stored data. PureKit allows developers to protect users' passwords and personal data from hacking and securely share data.

The framework can be used within any database or login system that uses a password, so it’s applicable for a company of any industry or size.

Password-Based Security

Virgil PureKit is based on the Password-Hardened Encryption (PHE) protocol – a powerful and revolutionary cryptographic technology that provides stronger and more modern security, that protects users' data and reduces the security risks associated with weak passwords.

PureKit brings data security to a new level in three ways:

  1. Replaces password hashing in a way making it impossible to run offline and online attacks. By interacting with PHE Service, a standalone cryptographic service in Virgil Cloud dedicated to implement PHE protocol, PureKit creates a unique user’s record that is associated with the user password. It is important to note that a user password is never transmitted to the PHE service in any form.
  2. Encrypts data with user’s personal encryption keys. PureKit gives users a possibility to encrypt their data with personal encryption keys, and all keys can be revealed only after providing a correct password.
  3. Immediately invalidate stolen database. Even if your database has been compromised it impossible to run offline attacks, to retrieve user password or decrypt data. At the same time, PureKit provides convenient and secure key rotation procedure, that allows you quickly update all your server keys without losing access to your data.


  • Per-user data and files encryption
  • Password protection against hacking
  • Management of data encryption keys
  • Secure data and files sharing
  • Role-based data encryption


  • Users control data access
  • Post-compromise security
  • Password & data protection from online and offline attacks
  • Replaces salting and hashing of passwords
  • Zero knowledge of user passwords and secret keys
  • Virgil Security has no access to your data
  • Encryption occurs independently of database security
  • Works with any database
  • Stronger than encryption at-rest and TDE
  • More secure than AWS and Google Key Management Systems (KMS)
  • Instant invalidation of stolen databases
  • Compliance with GDPR, HIPAA, PCI DSS and more


Navigate to our Developer Documentation to install and start working with Virgil PureKit.



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


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

You can find us on Twitter or send an email to our support team support@VirgilSecurity.com.

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




View Source
const (
	NmsPrefix       = "NM"
	BuppkPrefix     = "BU"
	SecretKeyPrefix = "SK"
	PublicKeyPrefix = "PK"
View Source
const (
	DefaultGrantTTL = time.Hour
View Source
const DerivedSecretLength = 44
View Source
const NonrotatableMasterSecretLength = 32
View Source
const RecoverPwdAlias = "RECOVERY_PASSWORD"


View Source
var (
	ErrInvalidPassword = errors.New("invalid password")
	ErrNoAccess        = errors.New("no access")
	ErrGrantKeyExpired = errors.New("grant key expired")

ErrInvalidPassword is returned when protocol determines validation failure


This section is empty.


type AuthResult

type AuthResult struct {
	Grant          *models.PureGrant
	EncryptedGrant string

type Context

type Context struct {
	Crypto              *crypto.Crypto
	Version             uint32
	UpdateToken         *Credentials
	PublicKey           *Credentials
	SecretKey           *Credentials
	Buppk               crypto.PublicKey
	Storage             storage.PureStorage
	PheClient           *clients.PheClient
	KmsClient           *clients.KmsClient
	NonRotatableSecrets *NonRotatableSecrets
	ExternalPublicKeys  map[string][]crypto.PublicKey
	AppToken            string

Context holds & validates protocol input parameters

func CreateCloudContext

func CreateCloudContext(at, nm, bu, sk, pk string,
	externalPublicKeys map[string][]string,
	kmsServiceAddress string) (*Context, error)

func CreateContext

func CreateContext(c *crypto.Crypto,
	at, nm, bu, sk, pk string,
	pureStorage storage.PureStorage,
	externalPublicKeys map[string][]string,
	pheServerAddress, kmsServerAddress string) (*Context, error)

CreateContext validates input parameters and prepares them for being used in Protocol

func CreateDefaultCloudContext

func CreateDefaultCloudContext(at, nm, bu, sk, pk string,
	externalPublicKeys map[string][]string) (*Context, error)

func (*Context) SetUpdateToken

func (c *Context) SetUpdateToken(updateToken string) error

type Credentials

type Credentials struct {
	Payload1, Payload2, Payload3 []byte
	Version                      uint32

func ParseCredentials

func ParseCredentials(prefix, creds string, versioned bool, numPayloads int) (*Credentials, error)

type DeserializedEncryptedGrant

type DeserializedEncryptedGrant struct {
	EncryptedGrant       *protos.EncryptedGrant
	EncryptedGrantHeader *protos.EncryptedGrantHeader

type KmsEncryptedData

type KmsEncryptedData struct {
	Wrap, Blob []byte

type KmsManager

type KmsManager struct {
	CurrentVersion     uint32
	PureCrypto         *PureCrypto
	PwdCurrentClient   *phe.UokmsClient
	PwdPreviousClient  *phe.UokmsClient
	GrantCurrentClient *phe.UokmsClient

	HTTPKmsClient    *clients.KmsClient
	PwdKmsRotation   *phe.UokmsWrapRotation
	GrantKmsRotation *phe.UokmsWrapRotation
	// contains filtered or unexported fields

func NewKmsManager

func NewKmsManager(context *Context) (*KmsManager, error)

func (*KmsManager) GenerateGrantKeyEncryptionData

func (k *KmsManager) GenerateGrantKeyEncryptionData(grantKey, header []byte) (*KmsEncryptedData, error)

func (*KmsManager) GeneratePwdRecoveryData

func (k *KmsManager) GeneratePwdRecoveryData(passwordHash []byte) (*KmsEncryptedData, error)

func (*KmsManager) GetGrantClient

func (k *KmsManager) GetGrantClient(kmsVersion uint32) (*phe.UokmsClient, error)

func (*KmsManager) GetPwdClient

func (k *KmsManager) GetPwdClient(kmsVersion uint32) (*phe.UokmsClient, error)

func (*KmsManager) PerformGrantRotation

func (k *KmsManager) PerformGrantRotation(wrap []byte) ([]byte, error)

func (*KmsManager) PerformPwdRotation

func (k *KmsManager) PerformPwdRotation(wrap []byte) ([]byte, error)

func (*KmsManager) RecoverGrant

func (k *KmsManager) RecoverGrant(grant *models.GrantKey, header []byte) ([]byte, error)

func (*KmsManager) RecoverGrantKey

func (k *KmsManager) RecoverGrantKey(grantKey *models.GrantKey, header []byte) ([]byte, error)

func (*KmsManager) RecoverGrantKeySecret

func (k *KmsManager) RecoverGrantKeySecret(grantKey *models.GrantKey) ([]byte, error)

func (*KmsManager) RecoverPwd

func (k *KmsManager) RecoverPwd(record *models.UserRecord) ([]byte, error)

func (*KmsManager) RecoverPwdSecret

func (k *KmsManager) RecoverPwdSecret(record *models.UserRecord) ([]byte, error)

type NonRotatableSecrets

type NonRotatableSecrets struct {
	Vksp, Oksp crypto.PrivateKey

func GenerateNonRotatableSecrets

func GenerateNonRotatableSecrets(c *crypto.Crypto, masterSecret []byte) (*NonRotatableSecrets, error)

type PheManager

type PheManager struct {
	Crypto         *crypto.Crypto
	CurrentVersion uint32
	UpdateToken    []byte
	CurrentClient  *phe.PheClient
	PreviousClient *phe.PheClient
	HttpClient     *clients.PheClient

func NewPheManager

func NewPheManager(context *Context) (*PheManager, error)

func (*PheManager) ComputePheKey

func (p *PheManager) ComputePheKey(record *models.UserRecord, passwordHash []byte) (key []byte, err error)

func (*PheManager) GetEnrollment

func (p *PheManager) GetEnrollment(passwordHash []byte) (record, key []byte, err error)

func (*PheManager) GetPheClient

func (p *PheManager) GetPheClient(pheVersion uint32) (*phe.PheClient, error)

func (*PheManager) PerformRotation

func (p *PheManager) PerformRotation(record []byte) ([]byte, error)

type Pure

type Pure struct {
	CurrentVersion     uint32
	PureCrypto         *PureCrypto
	Storage            storage.PureStorage
	Buppk              crypto.PublicKey
	Oskp               crypto.PrivateKey
	ExternalPublicKeys map[string][]crypto.PublicKey
	PheManager         *PheManager
	KmsManager         *KmsManager

func NewPure

func NewPure(context *Context) (*Pure, error)

func (*Pure) AssignRole

func (p *Pure) AssignRole(roleName string, publicKeyID []byte, rskData []byte, userIds ...string) error

func (*Pure) AssignRoleWithGrant

func (p *Pure) AssignRoleWithGrant(roleName string, grant *models.PureGrant, userIds ...string) error

func (*Pure) AuthenticateUser

func (p *Pure) AuthenticateUser(userID, password string, sessionParams *SessionParameters) (*AuthResult, error)

func (*Pure) ChangeUserPassword

func (p *Pure) ChangeUserPassword(userID, oldPassword, newPassword string) error

func (*Pure) ChangeUserPasswordWithGrant

func (p *Pure) ChangeUserPasswordWithGrant(grant *models.PureGrant, newPassword string) error

func (*Pure) CreateRole

func (p *Pure) CreateRole(roleName string, userIds ...string) error

func (*Pure) CreateUserGrantAsAdmin

func (p *Pure) CreateUserGrantAsAdmin(userID string, bupsk crypto.PrivateKey, ttl time.Duration) (*models.PureGrant, error)

func (*Pure) Decrypt

func (p *Pure) Decrypt(grant *models.PureGrant, ownerUserID, dataID string, ciphertext []byte) ([]byte, error)

func (*Pure) DecryptGrantFromUser

func (p *Pure) DecryptGrantFromUser(encryptedGrant string) (*models.PureGrant, error)

func (*Pure) DecryptWithKey

func (p *Pure) DecryptWithKey(privateKey crypto.PrivateKey, ownerUserID, dataID string, ciphertext []byte) ([]byte, error)

func (*Pure) DeleteKey

func (p *Pure) DeleteKey(userID, dataID string) error

func (*Pure) DeleteUser

func (p *Pure) DeleteUser(userID string, cascade bool) error

func (*Pure) Encrypt

func (p *Pure) Encrypt(userID, dataID string, plaintext []byte) ([]byte, error)

func (*Pure) EncryptGeneral

func (p *Pure) EncryptGeneral(
	userID, dataID string,
	otherUserIDs []string,
	roleNames []string,
	publicKeys []crypto.PublicKey,
	plainText []byte) ([]byte, error)

nolint: golint,gocyclo,gocritic

func (*Pure) InvalidateEncryptedUserGrant

func (p *Pure) InvalidateEncryptedUserGrant(encryptedGrant string) error

func (*Pure) PerformRotation

func (p *Pure) PerformRotation() (*RotationResults, error)

func (*Pure) RecoverUser

func (p *Pure) RecoverUser(userID, newPassword string) error

func (*Pure) RegisterUser

func (p *Pure) RegisterUser(userID, password string) error

func (*Pure) ResetUser

func (p *Pure) ResetUser(userID, newPassword string, cascade bool) error

func (*Pure) Share

func (p *Pure) Share(grant *models.PureGrant, dataID string, otherUserIds []string, publicKeys []crypto.PublicKey) error

func (*Pure) ShareToRole

func (p *Pure) ShareToRole(grant *models.PureGrant, dataID string, roleName string) error

func (*Pure) ShareToRoles

func (p *Pure) ShareToRoles(grant *models.PureGrant, dataID string, roleNames []string) error

func (*Pure) UnassignRole

func (p *Pure) UnassignRole(roleName string, userIds ...string) error

func (*Pure) Unshare

func (p *Pure) Unshare(ownerUserID, dataID string, otherUserIDs []string, publicKeys []crypto.PublicKey) error

type PureCrypto

type PureCrypto struct {
	Crypto *crypto.Crypto
	// contains filtered or unexported fields

func NewPureCrypto

func NewPureCrypto(crypto *crypto.Crypto) *PureCrypto

func (*PureCrypto) AddRecipientsToCellKey

func (p *PureCrypto) AddRecipientsToCellKey(cms []byte, privateKey crypto.PrivateKey, publicKeys []crypto.PublicKey) ([]byte, error)

func (*PureCrypto) ComputePasswordHash

func (p *PureCrypto) ComputePasswordHash(password string) ([]byte, error)

func (*PureCrypto) ComputeSymmetricKeyId

func (p *PureCrypto) ComputeSymmetricKeyId(key []byte) ([]byte, error)

func (*PureCrypto) DecryptBackup

func (p *PureCrypto) DecryptBackup(data []byte, decryptKey crypto.PrivateKey, verifyKey crypto.PublicKey) ([]byte, error)

func (*PureCrypto) DecryptCellKey

func (p *PureCrypto) DecryptCellKey(data *PureCryptoData, privateKey crypto.PrivateKey, verifyingKey crypto.PublicKey) ([]byte, error)

func (*PureCrypto) DecryptData

func (p *PureCrypto) DecryptData(data []byte, decryptionKey crypto.PrivateKey, verificationKey crypto.PublicKey) ([]byte, error)

func (*PureCrypto) DecryptRolePrivateKey

func (p *PureCrypto) DecryptRolePrivateKey(data []byte, decryptKey crypto.PrivateKey, verifyKey crypto.PublicKey) ([]byte, error)

func (*PureCrypto) DecryptSymmetricWithNewNonce

func (p *PureCrypto) DecryptSymmetricWithNewNonce(ciphertext, ad, key []byte) ([]byte, error)

func (*PureCrypto) DecryptSymmetricWithOneTimeKey

func (p *PureCrypto) DecryptSymmetricWithOneTimeKey(ciphertext, ad, key []byte) ([]byte, error)

func (*PureCrypto) DeleteRecipientsFromCellKey

func (p *PureCrypto) DeleteRecipientsFromCellKey(cms []byte, publicKeys []crypto.PublicKey) ([]byte, error)

func (*PureCrypto) EncryptCellKey

func (p *PureCrypto) EncryptCellKey(
	plaintext []byte,
	recipients []crypto.PublicKey,
	signingKey crypto.PrivateKey) (*PureCryptoData, error)

func (*PureCrypto) EncryptData

func (p *PureCrypto) EncryptData(data []byte, signingKey crypto.PrivateKey, recipients ...crypto.PublicKey) ([]byte, error)

func (*PureCrypto) EncryptForBackup

func (p *PureCrypto) EncryptForBackup(data []byte, encryptKey crypto.PublicKey, signingKey crypto.PrivateKey) ([]byte, error)

func (*PureCrypto) EncryptRolePrivateKey

func (p *PureCrypto) EncryptRolePrivateKey(data []byte, encryptKey crypto.PublicKey, signingKey crypto.PrivateKey) ([]byte, error)

func (*PureCrypto) EncryptSymmetricWithNewNonce

func (p *PureCrypto) EncryptSymmetricWithNewNonce(plaintext, ad, key []byte) ([]byte, error)

func (*PureCrypto) EncryptSymmetricWithOneTimeKey

func (p *PureCrypto) EncryptSymmetricWithOneTimeKey(plaintext, ad, key []byte) ([]byte, error)

func (*PureCrypto) ExportPrivateKey

func (p *PureCrypto) ExportPrivateKey(key crypto.PrivateKey) ([]byte, error)

func (*PureCrypto) ExportPublicKey

func (p *PureCrypto) ExportPublicKey(key crypto.PublicKey) ([]byte, error)

func (*PureCrypto) ExtractPublicKeysIdsFromCellKey

func (p *PureCrypto) ExtractPublicKeysIdsFromCellKey(cms []byte) ([][]byte, error)

func (*PureCrypto) GenerateCellKey

func (p *PureCrypto) GenerateCellKey() (crypto.PrivateKey, error)

func (*PureCrypto) GenerateRoleKey

func (p *PureCrypto) GenerateRoleKey() (crypto.PrivateKey, error)

func (*PureCrypto) GenerateSymmetricOneTimeKey

func (p *PureCrypto) GenerateSymmetricOneTimeKey() ([]byte, error)

func (*PureCrypto) GenerateUserKey

func (p *PureCrypto) GenerateUserKey() (crypto.PrivateKey, error)

func (*PureCrypto) ImportPrivateKey

func (p *PureCrypto) ImportPrivateKey(data []byte) (crypto.PrivateKey, error)

func (*PureCrypto) ImportPublicKey

func (p *PureCrypto) ImportPublicKey(data []byte) (crypto.PublicKey, error)

type PureCryptoData

type PureCryptoData struct {
	Cms, Body []byte

type RotationResults

type RotationResults struct {
	UsersRotated  uint64
	GrantsRotated uint64

type SessionParameters

type SessionParameters struct {
	SessionID string
	TTL       time.Duration


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL