cryptutil

Documentation

Overview

Package cryptutil provides encoding and decoding routines for various cryptographic structures.

Index

• Constants
• func CheckPasswordHash(hash, password []byte) error
• func DecodePrivateKey(encodedKey []byte) (*ecdsa.PrivateKey, error)
• func DecodePublicKey(encodedKey []byte) (*ecdsa.PublicKey, error)
• func DecodeSignatureJWT(b64sig string) ([]byte, error)
• func EncodePrivateKey(key *ecdsa.PrivateKey) ([]byte, error)
• func EncodePublicKey(key *ecdsa.PublicKey) ([]byte, error)
• func EncodeSignatureJWT(sig []byte) string
• func GenerateKey() []byte
• func GenerateRandomString(c int) string
• func Hash(tag string, data []byte) []byte
• func HashPassword(password []byte) ([]byte, error)
• type Cipher
• type ES256Signer
  • func NewES256Signer(privKey []byte, audience string) (*ES256Signer, error)
  • func (s *ES256Signer) SignJWT(user, email, groups string) (string, error)
• type JWTSigner
• type MockCipher
  • func (mc MockCipher) Decrypt(b []byte) ([]byte, error)
  • func (mc MockCipher) Encrypt(b []byte) ([]byte, error)
  • func (mc MockCipher) Marshal(i interface{}) (string, error)
  • func (mc MockCipher) Unmarshal(s string, i interface{}) error
• type XChaCha20Cipher
  • func NewCipher(secret []byte) (*XChaCha20Cipher, error)
  • func (c *XChaCha20Cipher) Decrypt(joined []byte) ([]byte, error)
  • func (c *XChaCha20Cipher) Encrypt(plaintext []byte) (joined []byte, err error)
  • func (c *XChaCha20Cipher) GenerateNonce() []byte
  • func (c *XChaCha20Cipher) Marshal(s interface{}) (string, error)
  • func (c *XChaCha20Cipher) Unmarshal(value string, s interface{}) error

Examples

• Hash

Constants

const DefaultKeySize = 32

Functions

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 DecodeSignatureJWT

func DecodeSignatureJWT(b64sig string) ([]byte, error)

DecodeSignatureJWT decodes an ECDSA signature according to https://tools.ietf.org/html/rfc7515#appendix-A.3.1

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 EncodeSignatureJWT

func EncodeSignatureJWT(sig []byte) string

EncodeSignatureJWT encodes an ECDSA signature according to https://tools.ietf.org/html/rfc7515#appendix-A.3.1

func GenerateKey

func GenerateKey() []byte

GenerateKey generates a random 32-byte key.

Panics if source of randomness fails.

func GenerateRandomString

func GenerateRandomString(c int) string

GenerateRandomString returns base64 encoded securely generated random string of a given set of bytes.

Panics if source of randomness fails.

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.

Types

type Cipher

type Cipher interface {
	Encrypt([]byte) ([]byte, error)
	Decrypt([]byte) ([]byte, error)
	Marshal(interface{}) (string, error)
	Unmarshal(string, interface{}) error
}

Cipher provides methods to encrypt and decrypt values.

type ES256Signer

type ES256Signer struct {

	// User (sub) is unique, stable identifier for the user.
	// Use in place of the x-pomerium-authenticated-user-id header.
	User string `json:"sub,omitempty"`

	// Email (email) is a **custom** claim name identifier for the user email address.
	// Use in place of the x-pomerium-authenticated-user-email header.
	Email string `json:"email,omitempty"`

	// Groups (groups) is a **custom** claim name identifier for the user's groups.
	// Use in place of the x-pomerium-authenticated-user-groups header.
	Groups string `json:"groups,omitempty"`

	// Audience (aud) must be the destination of the upstream proxy locations.
	// e.g. `helloworld.corp.example.com`
	Audience jwt.Audience `json:"aud,omitempty"`
	// Issuer (iss) is the URL of the proxy.
	// e.g. `proxy.corp.example.com`
	Issuer string `json:"iss,omitempty"`
	// Expiry (exp) is the expiration time in seconds since the UNIX epoch.
	// Allow 1 minute for skew. The maximum lifetime of a token is 10 minutes + 2 * skew.
	Expiry jwt.NumericDate `json:"exp,omitempty"`
	// IssuedAt (iat) is the time is measured in seconds since the UNIX epoch.
	// Allow 1 minute for skew.
	IssuedAt jwt.NumericDate `json:"iat,omitempty"`
	// IssuedAt (nbf) is the time is measured in seconds since the UNIX epoch.
	// Allow 1 minute for skew.
	NotBefore jwt.NumericDate `json:"nbf,omitempty"`
	// contains filtered or unexported fields
}

ES256Signer is struct containing the required fields to create a ES256 signed JSON Web Tokens

func NewES256Signer

func NewES256Signer(privKey []byte, audience string) (*ES256Signer, error)

NewES256Signer creates an Elliptic Curve, NIST P-256 (aka secp256r1 aka prime256v1) JWT signer.

RSA is not supported due to performance considerations of needing to sign each request. Go's P-256 is constant-time and SHA-256 is faster on 64-bit machines and immune to length extension attacks. See also: - https://cloud.google.com/iot/docs/how-tos/credentials/keys

func (*ES256Signer) SignJWT

func (s *ES256Signer) SignJWT(user, email, groups string) (string, error)

SignJWT creates a signed JWT containing claims for the logged in user id (`sub`), email (`email`) and groups (`groups`).

type JWTSigner

type JWTSigner interface {
	SignJWT(string, string, string) (string, error)
}

JWTSigner implements JWT signing according to JSON Web Token (JWT) RFC7519 https://tools.ietf.org/html/rfc7519

type MockCipher

type MockCipher struct {
	EncryptResponse []byte
	EncryptError    error
	DecryptResponse []byte
	DecryptError    error
	MarshalResponse string
	MarshalError    error
	UnmarshalError  error
}

MockCipher MockCSRFStore is a mock implementation of Cipher.

func (MockCipher) Decrypt

func (mc MockCipher) Decrypt(b []byte) ([]byte, error)

Decrypt is a mock implementation of MockCipher.

func (MockCipher) Encrypt

func (mc MockCipher) Encrypt(b []byte) ([]byte, error)

Encrypt is a mock implementation of MockCipher.

func (MockCipher) Marshal

func (mc MockCipher) Marshal(i interface{}) (string, error)

Marshal is a mock implementation of MockCipher.

func (MockCipher) Unmarshal

func (mc MockCipher) Unmarshal(s string, i interface{}) error

Unmarshal is a mock implementation of MockCipher.

type XChaCha20Cipher

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

XChaCha20Cipher provides methods to encrypt and decrypt values. Using an AEAD is a cipher providing authenticated encryption with associated data. For a description of the methodology, see https://en.wikipedia.org/wiki/Authenticated_encryption

func NewCipher

func NewCipher(secret []byte) (*XChaCha20Cipher, error)

NewCipher takes secret key and returns a new XChacha20poly1305 cipher.

func (*XChaCha20Cipher) Decrypt

func (c *XChaCha20Cipher) Decrypt(joined []byte) ([]byte, error)

Decrypt a value using XChaCha20-Poly1305

func (*XChaCha20Cipher) Encrypt

func (c *XChaCha20Cipher) Encrypt(plaintext []byte) (joined []byte, err error)

Encrypt a value using XChaCha20-Poly1305

func (*XChaCha20Cipher) GenerateNonce

func (c *XChaCha20Cipher) GenerateNonce() []byte

GenerateNonce generates a random nonce. Panics if source of randomness fails.

func (*XChaCha20Cipher) Marshal

func (c *XChaCha20Cipher) Marshal(s interface{}) (string, error)

Marshal marshals the interface state as JSON, encrypts the JSON using the cipher and base64 encodes the binary value as a string and returns the result

func (*XChaCha20Cipher) Unmarshal

func (c *XChaCha20Cipher) Unmarshal(value string, s interface{}) error

Unmarshal takes the marshaled string, base64-decodes into a byte slice, decrypts the byte slice the passed cipher, and unmarshals the resulting JSON into the struct pointer passed