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
          }

          Directories

          Path Synopsis