README
¶
Virgil PureKit Go
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:
- 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.
- 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.
- 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
- PureKit Product Page
- PureKit Documentation - start integrating PureKit into your project with our detailed guides.
- PureKit API Reference
- MariaDB Demo - a simple web application that illustrates how Virgil PureKit can be used with MariaDB to store and share data in the most secure way.
- Virgil PHE WhitePaper - foundation principles of the Password-Hardened Encryption (PHE) protocol.
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.
Documentation
¶
Index ¶
- Constants
- Variables
- type AuthResult
- type Context
- func CreateCloudContext(at, nm, bu, sk, pk string, externalPublicKeys map[string][]string, ...) (*Context, error)
- func CreateContext(c *crypto.Crypto, at, nm, bu, sk, pk string, pureStorage storage.PureStorage, ...) (*Context, error)
- func CreateDefaultCloudContext(at, nm, bu, sk, pk string, externalPublicKeys map[string][]string) (*Context, error)
- type Credentials
- type DeserializedEncryptedGrant
- type KmsEncryptedData
- type KmsManager
- func (k *KmsManager) GenerateGrantKeyEncryptionData(grantKey, header []byte) (*KmsEncryptedData, error)
- func (k *KmsManager) GeneratePwdRecoveryData(passwordHash []byte) (*KmsEncryptedData, error)
- func (k *KmsManager) GetGrantClient(kmsVersion uint32) (*phe.UokmsClient, error)
- func (k *KmsManager) GetPwdClient(kmsVersion uint32) (*phe.UokmsClient, error)
- func (k *KmsManager) PerformGrantRotation(wrap []byte) ([]byte, error)
- func (k *KmsManager) PerformPwdRotation(wrap []byte) ([]byte, error)
- func (k *KmsManager) RecoverGrant(grant *models.GrantKey, header []byte) ([]byte, error)
- func (k *KmsManager) RecoverGrantKey(grantKey *models.GrantKey, header []byte) ([]byte, error)
- func (k *KmsManager) RecoverGrantKeySecret(grantKey *models.GrantKey) ([]byte, error)
- func (k *KmsManager) RecoverPwd(record *models.UserRecord) ([]byte, error)
- func (k *KmsManager) RecoverPwdSecret(record *models.UserRecord) ([]byte, error)
- type NonRotatableSecrets
- type PheManager
- func (p *PheManager) ComputePheKey(record *models.UserRecord, passwordHash []byte) (key []byte, err error)
- func (p *PheManager) GetEnrollment(passwordHash []byte) (record, key []byte, err error)
- func (p *PheManager) GetPheClient(pheVersion uint32) (*phe.PheClient, error)
- func (p *PheManager) PerformRotation(record []byte) ([]byte, error)
- type Pure
- func (p *Pure) AssignRole(roleName string, publicKeyID []byte, rskData []byte, userIds ...string) error
- func (p *Pure) AssignRoleWithGrant(roleName string, grant *models.PureGrant, userIds ...string) error
- func (p *Pure) AuthenticateUser(userID, password string, sessionParams *SessionParameters) (*AuthResult, error)
- func (p *Pure) ChangeUserPassword(userID, oldPassword, newPassword string) error
- func (p *Pure) ChangeUserPasswordWithGrant(grant *models.PureGrant, newPassword string) error
- func (p *Pure) CreateRole(roleName string, userIds ...string) error
- func (p *Pure) CreateUserGrantAsAdmin(userID string, bupsk crypto.PrivateKey, ttl time.Duration) (*models.PureGrant, error)
- func (p *Pure) Decrypt(grant *models.PureGrant, ownerUserID, dataID string, ciphertext []byte) ([]byte, error)
- func (p *Pure) DecryptGrantFromUser(encryptedGrant string) (*models.PureGrant, error)
- func (p *Pure) DecryptWithKey(privateKey crypto.PrivateKey, ownerUserID, dataID string, ciphertext []byte) ([]byte, error)
- func (p *Pure) DeleteKey(userID, dataID string) error
- func (p *Pure) DeleteUser(userID string, cascade bool) error
- func (p *Pure) Encrypt(userID, dataID string, plaintext []byte) ([]byte, error)
- func (p *Pure) EncryptGeneral(userID, dataID string, otherUserIDs []string, roleNames []string, ...) ([]byte, error)
- func (p *Pure) InvalidateEncryptedUserGrant(encryptedGrant string) error
- func (p *Pure) PerformRotation() (*RotationResults, error)
- func (p *Pure) RecoverUser(userID, newPassword string) error
- func (p *Pure) RegisterUser(userID, password string) error
- func (p *Pure) ResetUser(userID, newPassword string, cascade bool) error
- func (p *Pure) Share(grant *models.PureGrant, dataID string, otherUserIds []string, ...) error
- func (p *Pure) ShareToRole(grant *models.PureGrant, dataID string, roleName string) error
- func (p *Pure) ShareToRoles(grant *models.PureGrant, dataID string, roleNames []string) error
- func (p *Pure) UnassignRole(roleName string, userIds ...string) error
- func (p *Pure) Unshare(ownerUserID, dataID string, otherUserIDs []string, ...) error
- type PureCrypto
- func (p *PureCrypto) AddRecipientsToCellKey(cms []byte, privateKey crypto.PrivateKey, publicKeys []crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) ComputePasswordHash(password string) ([]byte, error)
- func (p *PureCrypto) ComputeSymmetricKeyId(key []byte) ([]byte, error)
- func (p *PureCrypto) DecryptBackup(data []byte, decryptKey crypto.PrivateKey, verifyKey crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) DecryptCellKey(data *PureCryptoData, privateKey crypto.PrivateKey, ...) ([]byte, error)
- func (p *PureCrypto) DecryptData(data []byte, decryptionKey crypto.PrivateKey, verificationKey crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) DecryptRolePrivateKey(data []byte, decryptKey crypto.PrivateKey, verifyKey crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) DecryptSymmetricWithNewNonce(ciphertext, ad, key []byte) ([]byte, error)
- func (p *PureCrypto) DecryptSymmetricWithOneTimeKey(ciphertext, ad, key []byte) ([]byte, error)
- func (p *PureCrypto) DeleteRecipientsFromCellKey(cms []byte, publicKeys []crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) EncryptCellKey(plaintext []byte, recipients []crypto.PublicKey, signingKey crypto.PrivateKey) (*PureCryptoData, error)
- func (p *PureCrypto) EncryptData(data []byte, signingKey crypto.PrivateKey, recipients ...crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) EncryptForBackup(data []byte, encryptKey crypto.PublicKey, signingKey crypto.PrivateKey) ([]byte, error)
- func (p *PureCrypto) EncryptRolePrivateKey(data []byte, encryptKey crypto.PublicKey, signingKey crypto.PrivateKey) ([]byte, error)
- func (p *PureCrypto) EncryptSymmetricWithNewNonce(plaintext, ad, key []byte) ([]byte, error)
- func (p *PureCrypto) EncryptSymmetricWithOneTimeKey(plaintext, ad, key []byte) ([]byte, error)
- func (p *PureCrypto) ExportPrivateKey(key crypto.PrivateKey) ([]byte, error)
- func (p *PureCrypto) ExportPublicKey(key crypto.PublicKey) ([]byte, error)
- func (p *PureCrypto) ExtractPublicKeysIdsFromCellKey(cms []byte) ([][]byte, error)
- func (p *PureCrypto) GenerateCellKey() (crypto.PrivateKey, error)
- func (p *PureCrypto) GenerateRoleKey() (crypto.PrivateKey, error)
- func (p *PureCrypto) GenerateSymmetricOneTimeKey() ([]byte, error)
- func (p *PureCrypto) GenerateUserKey() (crypto.PrivateKey, error)
- func (p *PureCrypto) ImportPrivateKey(data []byte) (crypto.PrivateKey, error)
- func (p *PureCrypto) ImportPublicKey(data []byte) (crypto.PublicKey, error)
- type PureCryptoData
- type RotationResults
- type SessionParameters
Constants ¶
const ( NmsPrefix = "NM" BuppkPrefix = "BU" SecretKeyPrefix = "SK" PublicKeyPrefix = "PK" )
const (
DefaultGrantTTL = time.Hour
)
const DerivedSecretLength = 44
const NonrotatableMasterSecretLength = 32
const RecoverPwdAlias = "RECOVERY_PASSWORD"
Variables ¶
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 ¶
Types ¶
type AuthResult ¶
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 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 (*Context) SetUpdateToken ¶
type Credentials ¶
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 (*KmsManager) RecoverGrantKey ¶
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 (*Pure) AssignRole ¶
func (*Pure) AssignRoleWithGrant ¶
func (*Pure) AuthenticateUser ¶
func (p *Pure) AuthenticateUser(userID, password string, sessionParams *SessionParameters) (*AuthResult, error)
func (*Pure) ChangeUserPassword ¶
func (*Pure) ChangeUserPasswordWithGrant ¶
func (*Pure) CreateUserGrantAsAdmin ¶
func (*Pure) DecryptGrantFromUser ¶
func (*Pure) DecryptWithKey ¶
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 (*Pure) PerformRotation ¶
func (p *Pure) PerformRotation() (*RotationResults, error)
func (*Pure) RecoverUser ¶
func (*Pure) RegisterUser ¶
func (*Pure) ShareToRole ¶
func (*Pure) ShareToRoles ¶
type PureCrypto ¶
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 (*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
}