Documentation ¶
Overview ¶
Provides symmetric authenticated encryption using 256-bit AES-GCM with a random nonce.
Provides a recommended hashing algorithm.
The hash function is HMAC-SHA512/256 where SHA512/256 is as described in FIPS 180-4. This construction avoids length-extension attacks while maintaining a widely compatible digest size with better performance on 64-bit systems.
Password hashing uses bcrypt with a work factor of 14.
Provides encoding and decoding routines for various cryptographic structures.
Provides message authentication and asymmetric signatures.
Message authentication: HMAC SHA512/256 This is a slight twist on the highly dependable HMAC-SHA256 that gains performance on 64-bit systems and consistency with our hashing recommendation.
Asymmetric Signature: ECDSA using P256 and SHA256 ECDSA is the best compromise between cryptographic concerns and support for our internal use cases (e.g. RFC7518). The Go standard library implementation has some protection against entropy problems, but is not deterministic. See https://github.com/golang/go/commit/8d7bf2291b095d3a2ecaa2609e1101be46d80deb
Provides a recommended TLS configuration.
Index ¶
- func CheckHMAC(data, suppliedMAC []byte, key *[32]byte) bool
- 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 Decrypt(ciphertext []byte, key *[32]byte) (plaintext []byte, err error)
- func DefaultTLSConfig() *tls.Config
- func EncodePrivateKey(key *ecdsa.PrivateKey) ([]byte, error)
- func EncodePublicKey(key *ecdsa.PublicKey) ([]byte, error)
- func EncodeSignatureJWT(sig []byte) string
- func Encrypt(plaintext []byte, key *[32]byte) (ciphertext []byte, err error)
- func GenerateHMAC(data []byte, key *[32]byte) []byte
- func Hash(tag string, data []byte) []byte
- func HashPassword(password []byte) ([]byte, error)
- func NewEncryptionKey() *[32]byte
- func NewHMACKey() *[32]byte
- func NewSigningKey() (*ecdsa.PrivateKey, error)
- func Sign(data []byte, privkey *ecdsa.PrivateKey) ([]byte, error)
- func Verify(data, signature []byte, pubkey *ecdsa.PublicKey) bool
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckHMAC ¶
CheckHMAC securely checks the supplied MAC against a message using the shared secret key.
func CheckPasswordHash ¶
CheckPassword 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 ¶
DecodePublicKey decodes a PEM-encoded ECDSA public key.
func DecodeSignatureJWT ¶
Decodes an ECDSA signature according to https://tools.ietf.org/html/rfc7515#appendix-A.3.1
func Decrypt ¶
Decrypt decrypts data using 256-bit AES-GCM. This both hides the content of the data and provides a check that it hasn't been altered. Expects input form nonce|ciphertext|tag where '|' indicates concatenation.
func DefaultTLSConfig ¶
func EncodePrivateKey ¶
func EncodePrivateKey(key *ecdsa.PrivateKey) ([]byte, error)
EncodePrivateKey encodes an ECDSA private key to PEM format.
func EncodePublicKey ¶
EncodePublicKey encodes an ECDSA public key to PEM format.
func EncodeSignatureJWT ¶
Encodes an ECDSA signature according to https://tools.ietf.org/html/rfc7515#appendix-A.3.1
func Encrypt ¶
Encrypt encrypts data using 256-bit AES-GCM. This both hides the content of the data and provides a check that it hasn't been altered. Output takes the form nonce|ciphertext|tag where '|' indicates concatenation.
func GenerateHMAC ¶
GenerateHMAC produces a symmetric signature using a shared secret key.
func Hash ¶
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 ¶
HashPassword generates a bcrypt hash of the password using work factor 14.
func NewEncryptionKey ¶
func NewEncryptionKey() *[32]byte
NewEncryptionKey generates a random 256-bit key for Encrypt() and Decrypt(). It panics if the source of randomness fails.
func NewHMACKey ¶
func NewHMACKey() *[32]byte
NewHMACKey generates a random 256-bit secret key for HMAC use. Because key generation is critical, it panics if the source of randomness fails.
func NewSigningKey ¶
func NewSigningKey() (*ecdsa.PrivateKey, error)
GenerateSigningKey generates a random P-256 ECDSA private key.
Types ¶
This section is empty.