cryptutil

Documentation

Overview

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

Index

• Constants
• func CertificateFromBase64(cert, key string) (*tls.Certificate, error)
• func CertificateFromFile(certFile, keyFile string) (*tls.Certificate, error)
• func CheckHMAC(data, suppliedMAC []byte, key string) bool
• func CheckPasswordHash(hash, password []byte) error
• func DecodePrivateKey(encodedKey []byte) (*ecdsa.PrivateKey, error)
• func DecodePublicKey(encodedKey []byte) (*ecdsa.PublicKey, error)
• func Decrypt(a cipher.AEAD, data, ad []byte) ([]byte, error)
• func EncodePrivateKey(key *ecdsa.PrivateKey) ([]byte, error)
• func EncodePublicKey(key *ecdsa.PublicKey) ([]byte, error)
• func Encrypt(a cipher.AEAD, data, ad []byte) []byte
• func GenerateHMAC(data []byte, key string) []byte
• func GenerateSelfSignedCertificate(domain string) (*tls.Certificate, error)
• func GetCertificateForDomain(certificates []tls.Certificate, domain string) (*tls.Certificate, error)
• func Hash(tag string, data []byte) []byte
• func HashPassword(password []byte) ([]byte, error)
• func NewAEADCipher(secret []byte) (cipher.AEAD, error)
• func NewAEADCipherFromBase64(s string) (cipher.AEAD, error)
• func NewBase64Key() string
• func NewKey() []byte
• func NewRandomStringN(c int) string
• func NewSigningKey() (*ecdsa.PrivateKey, error)
• func PrivateJWKFromBytes(data []byte, alg jose.SignatureAlgorithm) (*jose.JSONWebKey, error)
• func PublicJWKFromBytes(data []byte, alg jose.SignatureAlgorithm) (*jose.JSONWebKey, error)
• func Sign(data []byte, privkey *ecdsa.PrivateKey) ([]byte, error)
• func ValidTimestamp(ts string) error
• func Verify(data, signature []byte, pubkey *ecdsa.PublicKey) bool
• type SecretToken
  • func SecretTokenFromString(rawstr string) (tok SecretToken, ok bool)
  • func (tok SecretToken) String() string
• type Token
  • func NewRandomToken() (tok Token)
  • func TokenFromString(rawstr string) (tok Token, ok bool)
  • func (tok Token) String() string
  • func (tok Token) UUID() uuid.UUID

Examples

• Hash

Constants

const DefaultKeySize = 32

DefaultKeySize is the default key size in bytes.

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

const TokenLength = 16

TokenLength is the length of a token.

Functions

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 []byte, key string) 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 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 []byte, key string) []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 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 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 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 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 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 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.