README

Virgil PureKit Go

Build Status Release version GitHub license API Reference

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

Introduction

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.

Features

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

Benefits

  • 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

Installation

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

Resources

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 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.

Expand ▾ Collapse ▴

Documentation

Index

Constants

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"

Variables

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

    Functions

    This section is empty.

    Types

    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,
	pheServiceAddress,
	pureServiceAddress,
	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
}

          Source Files

          View all

          Directories

          Path Synopsis