cryptutil

package
v0.15.2 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2021 License: Apache-2.0 Imports: 39 Imported by: 6

Documentation

Overview

Package cryptutil provides cryptographic utility functions, complementing the lower level abstractions found in the standard library.

Index

Examples

Constants

View Source 
const (
	// DataEncryptionKeySize is the size of a data encryption key.
	DataEncryptionKeySize = chacha20poly1305.KeySize
	// DataEncryptionKeyCacheSize is the number of DEKs to keep in the LRU cache.
	DataEncryptionKeyCacheSize = 20
)
View Source 
const DefaultKeySize = 32

DefaultKeySize is the default key size in bytes.

View Source 
const (
	// DefaultLeeway defines the default leeway for matching NotBefore/Expiry claims.
	DefaultLeeway = 5.0 * time.Minute
)
View Source 
const KeyEncryptionKeySize = curve25519.ScalarSize

KeyEncryptionKeySize is the size of a key encryption key.

View Source 
const TokenLength = 16

TokenLength is the length of a token.

Variables

This section is empty.

Functions

func CRLFromBase64 added in v0.14.0 

func CRLFromBase64(rawCRL string) (*pkix.CertificateList, error)

CRLFromBase64 parses a certificate revocation list from a base64 encoded blob.

func CRLFromFile added in v0.14.0 

func CRLFromFile(fileName string) (*pkix.CertificateList, error)

CRLFromFile parses a certificate revocation list from a file.

func CertificateFromBase64 

func CertificateFromBase64(cert, key string) (*tls.Certificate, error)

CertificateFromBase64 returns an X509 pair from a base64 encoded blob.

func CertificateFromFile 

func CertificateFromFile(certFile, keyFile string) (*tls.Certificate, error)

CertificateFromFile given a certificate, and key file path, returns a X509 keypair.

func CheckHMAC 

func CheckHMAC(data, suppliedMAC, key []byte) bool

CheckHMAC securely checks the supplied MAC against a message using the shared secret key.

func CheckPasswordHash 

func CheckPasswordHash(hash, password []byte) error

CheckPasswordHash securely compares a bcrypt hashed password with its possible plaintext equivalent. Returns nil on success, or an error on failure.

func DecodeCRL added in v0.14.0 

func DecodeCRL(encodedCRL []byte) (*pkix.CertificateList, error)

DecodeCRL decodes a PEM-encoded certificate revocation list.

func DecodePrivateKey 

func DecodePrivateKey(encodedKey []byte) (*ecdsa.PrivateKey, error)

DecodePrivateKey decodes a PEM-encoded ECDSA private key.

func DecodePublicKey 

func DecodePublicKey(encodedKey []byte) (*ecdsa.PublicKey, error)

DecodePublicKey decodes a PEM-encoded ECDSA public key.

func Decrypt 

func Decrypt(a cipher.AEAD, data, ad []byte) ([]byte, error)

Decrypt a value with optional associated data

func EncodePrivateKey 

func EncodePrivateKey(key *ecdsa.PrivateKey) ([]byte, error)

EncodePrivateKey encodes an ECDSA private key to PEM format.

func EncodePublicKey 

func EncodePublicKey(key *ecdsa.PublicKey) ([]byte, error)

EncodePublicKey encodes an ECDSA public key to PEM format.

func Encrypt 

func Encrypt(a cipher.AEAD, data, ad []byte) []byte

Encrypt encrypts a value with optional associated data

Panics if source of randomness fails.

func GenerateHMAC 

func GenerateHMAC(data, key []byte) []byte

GenerateHMAC produces a symmetric signature using a shared secret key.

func GenerateSelfSignedCertificate 

func GenerateSelfSignedCertificate(domain string) (*tls.Certificate, error)

GenerateSelfSignedCertificate generates a self-signed TLS certificate.

mostly copied from https://golang.org/src/crypto/tls/generate_cert.go

func GetCertPool added in v0.11.0 

func GetCertPool(ca, caFile string) (*x509.CertPool, error)

GetCertPool gets a cert pool for the given CA or CAFile.

func GetCertificateForDomain 

func GetCertificateForDomain(certificates []tls.Certificate, domain string) (*tls.Certificate, error)

GetCertificateForDomain returns the tls Certificate which matches the given domain name. It should handle both exact matches and wildcard matches. If none of those match, the first certificate will be used. Finally if there are no matching certificates one will be generated.

func GetKeyEncryptionKeyID added in v0.14.0 

func GetKeyEncryptionKeyID(raw []byte) string

GetKeyEncryptionKeyID derives an id from the key encryption key data itself.

func Hash 

func Hash(tag string, data []byte) []byte

Hash generates a hash of data using HMAC-SHA-512/256. The tag is intended to be a natural-language string describing the purpose of the hash, such as "hash file for lookup key" or "master secret to client secret". It serves as an HMAC "key" and ensures that different purposes will have different hash output. This function is NOT suitable for hashing passwords.

Example 
tag := "hashing file for lookup key"
contents, err := ioutil.ReadFile("testdata/random")
if err != nil {
	fmt.Printf("could not read file: %v\n", err)
	os.Exit(1)
}
digest := Hash(tag, contents)
fmt.Println(hex.EncodeToString(digest))

Output:

9f4c795d8ae5c207f19184ccebee6a606c1fdfe509c793614066d613580f03e1

func HashPassword 

func HashPassword(password []byte) ([]byte, error)

HashPassword generates a bcrypt hash of the password using work factor 14.

func HashProto added in v0.12.0 

func HashProto(msg proto.Message) []byte

HashProto hashes a protobuf message. It sets `Deterministic` to true to ensure the encoded message is always the same. (ie map order is lexographic)

func MarshalPKCS8PrivateKey added in v0.14.0 

func MarshalPKCS8PrivateKey(key interface{}) ([]byte, error)

MarshalPKCS8PrivateKey wraps x509.MarshalPKCS8PrivateKey with added support for KeyEncryptionKeys.

func MarshalPKIXPublicKey added in v0.14.0 

func MarshalPKIXPublicKey(pub interface{}) ([]byte, error)

MarshalPKIXPublicKey wraps x509.MarshalPKIXPublicKey with added support for KeyEncryptionKeys.

func NewAEADCipher 

func NewAEADCipher(secret []byte) (cipher.AEAD, error)

NewAEADCipher takes secret key and returns a new XChacha20poly1305 cipher.

func NewAEADCipherFromBase64 

func NewAEADCipherFromBase64(s string) (cipher.AEAD, error)

NewAEADCipherFromBase64 takes a base64 encoded secret key and returns a new XChacha20poly1305 cipher.

func NewBase64Key 

func NewBase64Key() string

NewBase64Key generates a random base64 encoded 32-byte key.

Panics if source of randomness fails.

func NewKey 

func NewKey() []byte

NewKey generates a random 32-byte (256 bit) key.

Panics if source of randomness fails.

func NewRandomStringN 

func NewRandomStringN(c int) string

NewRandomStringN returns base64 encoded random string of a given num of bytes.

Panics if source of randomness fails.

func NewRandomUInt64 added in v0.14.0 

func NewRandomUInt64() uint64

NewRandomUInt64 returns a random uint64.

Panics if source of randomness fails.

func NewSigningKey 

func NewSigningKey() (*ecdsa.PrivateKey, error)

NewSigningKey generates a random P-256 ECDSA private key. Go's P-256 is constant-time (which prevents certain types of attacks) while its P-384 and P-521 are not.

func ParsePEMCertificate added in v0.15.0 

func ParsePEMCertificate(raw []byte) (*x509.Certificate, error)

ParsePEMCertificate parses PEM encoded certificate block

func ParsePEMCertificateFromFile added in v0.15.0 

func ParsePEMCertificateFromFile(file string) (*x509.Certificate, error)

ParsePEMCertificateFromFile decodes PEM certificate from file

func ParsePKCS8PrivateKey added in v0.14.0 

func ParsePKCS8PrivateKey(der []byte) (interface{}, error)

ParsePKCS8PrivateKey wraps x509.ParsePKCS8PrivateKey with added support for KeyEncryptionKeys.

func ParsePKIXPublicKey added in v0.14.0 

func ParsePKIXPublicKey(derBytes []byte) (pub interface{}, err error)

ParsePKIXPublicKey wraps x509.ParsePKIXPublicKey with added support for KeyEncryptionKeys.

func PrivateJWKFromBytes 

func PrivateJWKFromBytes(data []byte, alg jose.SignatureAlgorithm) (*jose.JSONWebKey, error)

PrivateJWKFromBytes returns a jose JSON Web _Private_ Key from bytes.

func PublicJWKFromBytes 

func PublicJWKFromBytes(data []byte, alg jose.SignatureAlgorithm) (*jose.JSONWebKey, error)

PublicJWKFromBytes returns a jose JSON Web _Public_ Key from bytes.

func Sign 

func Sign(data []byte, privkey *ecdsa.PrivateKey) ([]byte, error)

Sign signs arbitrary data using ECDSA.

func ValidTimestamp 

func ValidTimestamp(ts string) error

ValidTimestamp is a helper function often used in conjunction with an HMAC function to verify that the timestamp (in unix seconds) is within leeway period.

func Verify 

func Verify(data, signature []byte, pubkey *ecdsa.PublicKey) bool

Verify checks a raw ECDSA signature. Returns true if it's valid and false if not.

Types

type DataEncryptionKey added in v0.14.0 

type DataEncryptionKey struct {
	// contains filtered or unexported fields
}

A DataEncryptionKey is an XChaCha20Poly1305 symmetric encryption key. For more details see the documentation on KeyEncryptionKeys.

func GenerateDataEncryptionKey added in v0.14.0 

func GenerateDataEncryptionKey() (*DataEncryptionKey, error)

GenerateDataEncryptionKey generates a new random data encryption key.

func NewDataEncryptionKey added in v0.14.0 

func NewDataEncryptionKey(raw []byte) (*DataEncryptionKey, error)

NewDataEncryptionKey returns a new DataEncryptionKey from existing bytes.

func (*DataEncryptionKey) Decrypt added in v0.14.0 

func (dek *DataEncryptionKey) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt decrypts encrypted data using the data encryption key.

func (*DataEncryptionKey) DecryptString added in v0.14.0 

func (dek *DataEncryptionKey) DecryptString(ciphertext string) (string, error)

DecryptString decrypts an encrypted string using the data encryption key and base64 encoding.

func (*DataEncryptionKey) Encrypt added in v0.14.0 

func (dek *DataEncryptionKey) Encrypt(plaintext []byte) []byte

Encrypt encrypts data using the data encryption key.

func (*DataEncryptionKey) EncryptString added in v0.14.0 

func (dek *DataEncryptionKey) EncryptString(plaintext string) string

EncryptString encrypts a string using the data encryption key and base64 encoding.

func (*DataEncryptionKey) KeyBytes added in v0.14.0 

func (dek *DataEncryptionKey) KeyBytes() []byte

KeyBytes returns the private key encryption key's raw bytes.

type DataEncryptionKeyCache added in v0.14.0 

type DataEncryptionKeyCache struct {
	// contains filtered or unexported fields
}

A DataEncryptionKeyCache caches recently used data encryption keys based on their encrypted representation. The cache is safe for concurrent read and write access.

Internally an LRU cache is used and the encrypted DEK bytes are converted to strings to allow usage as hash map keys.

func NewDataEncryptionKeyCache added in v0.14.0 

func NewDataEncryptionKeyCache() *DataEncryptionKeyCache

NewDataEncryptionKeyCache creates a new DataEncryptionKeyCache.

func (*DataEncryptionKeyCache) Get added in v0.14.0 

func (cache *DataEncryptionKeyCache) Get(encryptedDEK []byte) (*DataEncryptionKey, bool)

Get returns a data encryption key if available.

func (*DataEncryptionKeyCache) Put added in v0.14.0 

func (cache *DataEncryptionKeyCache) Put(encryptedDEK []byte, dek *DataEncryptionKey)

Put stores a data encryption key by its encrypted representation.

type KeyEncryptionKey added in v0.14.0 

type KeyEncryptionKey interface {
	ID() string
	KeyBytes() []byte
	// contains filtered or unexported methods
}

A KeyEncryptionKey (KEK) is used to implement *envelope encryption*, similar to how data is stored at rest with AWS or Google Cloud:

Data is encrypted with a data encryption key (DEK) and that key is stored next to the data encrypted with the KEK. Finally the KEK id is also stored with the data.

To decrypt the data you first retrieve the KEK, second decrypt the DEK, and finally decrypt the data using the DEK.

  • Our KEKs are asymmetric Curve25519 keys. We use the *public* key to encrypt the DEK so only the *private* key can decrypt it.
  • Our DEKs are symmetric XChaCha20Poly1305 keys.

type KeyEncryptionKeySource added in v0.14.0 

type KeyEncryptionKeySource interface {
	GetKeyEncryptionKey(id string) (*PrivateKeyEncryptionKey, error)
}

A KeyEncryptionKeySource gets private key encryption keys based on their id.

type KeyEncryptionKeySourceFunc added in v0.14.0 

type KeyEncryptionKeySourceFunc func(id string) (*PrivateKeyEncryptionKey, error)

A KeyEncryptionKeySourceFunc implements the KeyEncryptionKeySource interface using a function.

func (KeyEncryptionKeySourceFunc) GetKeyEncryptionKey added in v0.14.0 

func (src KeyEncryptionKeySourceFunc) GetKeyEncryptionKey(id string) (*PrivateKeyEncryptionKey, error)

GetKeyEncryptionKey gets the key encryption key by calling the underlying function.

type PrivateKeyEncryptionKey added in v0.14.0 

type PrivateKeyEncryptionKey struct {
	// contains filtered or unexported fields
}

PrivateKeyEncryptionKey is a Curve25519 asymmetric private encryption key used to decrypt data encryption keys.

func GenerateKeyEncryptionKey added in v0.14.0 

func GenerateKeyEncryptionKey() (*PrivateKeyEncryptionKey, error)

GenerateKeyEncryptionKey generates a new random key encryption key.

func NewPrivateKeyEncryptionKey added in v0.14.0 

func NewPrivateKeyEncryptionKey(raw []byte) (*PrivateKeyEncryptionKey, error)

NewPrivateKeyEncryptionKey creates a new encryption key from existing bytes.

func (*PrivateKeyEncryptionKey) Decrypt added in v0.14.0 

func (kek *PrivateKeyEncryptionKey) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt decrypts data from a NACL anonymous box.

func (*PrivateKeyEncryptionKey) DecryptDataEncryptionKey added in v0.14.0 

func (kek *PrivateKeyEncryptionKey) DecryptDataEncryptionKey(ciphertext []byte) (*DataEncryptionKey, error)

DecryptDataEncryptionKey decrypts a data encryption key.

func (*PrivateKeyEncryptionKey) ID added in v0.14.0 

func (kek *PrivateKeyEncryptionKey) ID() string

ID returns the private key's id.

func (*PrivateKeyEncryptionKey) KeyBytes added in v0.14.0 

func (kek *PrivateKeyEncryptionKey) KeyBytes() []byte

KeyBytes returns the private key encryption key's raw bytes.

func (*PrivateKeyEncryptionKey) Public added in v0.14.0 

func (kek *PrivateKeyEncryptionKey) Public() *PublicKeyEncryptionKey

Public returns the private key's public key.

type PublicKeyEncryptionKey added in v0.14.0 

type PublicKeyEncryptionKey struct {
	// contains filtered or unexported fields
}

PublicKeyEncryptionKey is a Curve25519 asymmetric public encryption key used to encrypt data encryption keys.

func NewPublicKeyEncryptionKey added in v0.14.0 

func NewPublicKeyEncryptionKey(raw []byte) (*PublicKeyEncryptionKey, error)

NewPublicKeyEncryptionKey creates a new encryption key from existing bytes.

func NewPublicKeyEncryptionKeyWithID added in v0.14.0 

func NewPublicKeyEncryptionKeyWithID(id string, raw []byte) (*PublicKeyEncryptionKey, error)

NewPublicKeyEncryptionKeyWithID creates a new encryption key from an existing id and bytes.

func (*PublicKeyEncryptionKey) Encrypt added in v0.14.0 

func (kek *PublicKeyEncryptionKey) Encrypt(plaintext []byte) ([]byte, error)

Encrypt encrypts data using a NACL anonymous box.

func (*PublicKeyEncryptionKey) EncryptDataEncryptionKey added in v0.14.0 

func (kek *PublicKeyEncryptionKey) EncryptDataEncryptionKey(dek *DataEncryptionKey) ([]byte, error)

EncryptDataEncryptionKey encrypts a DataEncryptionKey.

func (*PublicKeyEncryptionKey) ID added in v0.14.0 

func (kek *PublicKeyEncryptionKey) ID() string

ID returns the public key's id.

func (*PublicKeyEncryptionKey) KeyBytes added in v0.14.0 

func (kek *PublicKeyEncryptionKey) KeyBytes() []byte

KeyBytes returns the public key's raw bytes.

type SecretToken 

type SecretToken struct {
	ID     Token
	Secret Token
}

A SecretToken is made up of an id and a secret.

func SecretTokenFromString 

func SecretTokenFromString(rawstr string) (tok SecretToken, ok bool)

SecretTokenFromString parses a base58-encoded string into a secret token.

func (SecretToken) String 

func (tok SecretToken) String() string

String returns the SecretToken as a base58-encoded string.

type Token 

type Token [TokenLength]byte

A Token is a globally unique identifier.

func NewRandomToken 

func NewRandomToken() (tok Token)

NewRandomToken returns a new random Token (via a random UUID).

func TokenFromString 

func TokenFromString(rawstr string) (tok Token, ok bool)

TokenFromString parses a base58-encoded string into a token.

func (Token) String 

func (tok Token) String() string

String returns the Token as a base58-encoded string.

func (Token) UUID 

func (tok Token) UUID() uuid.UUID

UUID returns the token as a UUID.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.