cryptohelper

README

cryptohelper

The go cryptohelper package contains a collection of helper functions designed to document and streamline some common cryptographic patterns in golang web applications using only the standard go crypto library.

The functions can be used directly in your own projects or studied and copied as a starting point for your own library. They are designed with secure best-practice considerations and are production ready.

The package is intended to be self-documenting and complete for the patterns it includes, and as such it may contain several functions such as CompareHMAC(), EncodeHex(), and EncodeB64() which are very simple wrappers for equally simple underlying core library functions, but have been included for semantic consistency and completeness.

Documentation

• Go Package API Docs

Supported Patterns

The library currently supports the following patterns:

• Psuedo-random security code / pin number generation
• Cryptographically secure random security code / pin number generation
• Cryptographically secure key generation
  • AES 128-bit/192-bit/256-bit
  • HMAC SHA-256/SHA-512
  • Custom / any length
• AES encryption/decryption
• HMAC hashing
• String encoding/decoding of keys, ciphers, etc
  • Hexadecimal
  • Base64

Documentation

Index

• Constants
• Variables
• func CompareHMAC(hashA []byte, hashB []byte) bool
• func CreateHMACSHA256(key []byte, plaintext []byte) []byte
• func CreateHMACSHA512(key []byte, plaintext []byte) []byte
• func DecodeB64(str string) ([]byte, error)
• func DecodeHex(str string) ([]byte, error)
• func DecryptTextAESGCM(key []byte, ciphertext []byte) ([]byte, error)
• func EncodeB64(seq []byte) string
• func EncodeHex(seq []byte) string
• func EncryptTextAESGCM(key []byte, plaintext []byte) ([]byte, error)
• func GenerateAES128Key() ([]byte, error)
• func GenerateAES192Key() ([]byte, error)
• func GenerateAES256Key() ([]byte, error)
• func GenerateCryptoPIN(length int) (string, error)
• func GenerateCryptoSequence(length int) ([]byte, error)
• func GenerateHMACSHA256Key() ([]byte, error)
• func GenerateHMACSHA512Key() ([]byte, error)
• func GeneratePIN(length int) string

Constants

const (
	AES128KeyLength     = 16
	AES192KeyLength     = 24
	AES256KeyLength     = 32
	HMACSHA256KeyLength = 32
	HMACSHA512KeyLength = 64
)

Variables

var (
	ErrCipherTextMissingNonce = errors.New("The nonce cannot be parsed from the cipher text because the length of the cipher text is too short")
)

Functions

func CompareHMAC

func CompareHMAC(hashA []byte, hashB []byte) bool

CompareHMAC is a secure way to compare two HMAC hash outputs for equality without leaking timing side-channel information.

func CreateHMACSHA256

func CreateHMACSHA256(key []byte, plaintext []byte) []byte

CreateHMACSHA256 creates a cryptographic hash of a plaintext message using the Keyed-Hash Message Authentication Code (HMAC) method and the SHA-256 hashing algorithm. While the key can be any length it should be 32 random bytes for optimal security. The output can be converted to a string for storage using EncodeHex or EncodeB64. For a secure way to compare the output with another hmac hash use CompareHMAC.

func CreateHMACSHA512

func CreateHMACSHA512(key []byte, plaintext []byte) []byte

CreateHMACSHA512 creates a cryptographic hash of a plaintext message using the Keyed-Hash Message Authentication Code (HMAC) method and the SHA-512 hashing algorithm. While the key can be any length it should be 64 random bytes for optimal security. The output can be converted to a string for storage using EncodeHex or EncodeB64. For a secure way to compare the output with another hmac hash use CompareHMAC.

func DecodeB64

func DecodeB64(str string) ([]byte, error)

DecodeB64 converts a base64-encoded string such as a stored key, hash, or ciphertext back into a byte slice.

func DecodeHex

func DecodeHex(str string) ([]byte, error)

DecodeHex converts a hexadecimal string such as a stored key, hash, or ciphertext back into a byte slice.

func DecryptTextAESGCM

func DecryptTextAESGCM(key []byte, ciphertext []byte) ([]byte, error)

DecryptTextAESGCM decrypts a chunk of ciphertext which was encrypted using AES 128/192/256 symmetrical encryption with the mode of operation used for the block cipher being GCM. This function requires the same key used to encrypt the plaintext and also expects the 12-byte random nonce used to encrypt the plaintext to be prepended to the ciphertext. If the EncryptTextAESGCM function was used to generate the ciphertext then the nonce will be handled transparently.

func EncodeB64

func EncodeB64(seq []byte) string

EncodeB64 converts a byte slice such as a key, hash, or ciphertext to a base64-encoded string for storage.

func EncodeHex

func EncodeHex(seq []byte) string

EncodeHex converts a byte slice such as a key, hash, or ciphertext to a hexadecimal string for storage.

func EncryptTextAESGCM

func EncryptTextAESGCM(key []byte, plaintext []byte) ([]byte, error)

EncryptTextAESGCM encrypts a chunk of plaintext using AES 128/192/256 symmetrical encryption with the strength based on the key length. 128-bit requires a key length of 16, 192-bit requires a key length of 24, and 256-bit requires a key length of 32. An error will be returned if the key is not of an acceptable length. The mode of operation used for the block cipher is GCM (Galois/Counter Mode). A 12-byte random nonce will be prepended to the final ciphertext and must be parsed back out and used during the decryption process. If the DecryptTextAESGCM function is used to decrypt the ciphertext then the nonce will be handled transparently.

func GenerateAES128Key

func GenerateAES128Key() ([]byte, error)

GenerateAES128Key is an alias for GenerateCryptoSequence(16). An AES 128-bit key is expressed here as a byte slice. To obtain the plain text equivalent of this key for storage use the EncodeB64 or EncodeHex function.

func GenerateAES192Key

func GenerateAES192Key() ([]byte, error)

GenerateAES192Key is an alias for GenerateCryptoSequence(24). An AES 192-bit key is expressed here as a byte slice. To obtain the plain text equivalent of this key for storage use the EncodeB64 or EncodeHex function.

func GenerateAES256Key

func GenerateAES256Key() ([]byte, error)

GenerateAES256Key is an alias for GenerateCryptoSequence(32). An AES 256-bit key is expressed here as a byte slice. To obtain the plain text equivalent of this key for storage use the EncodeB64 or EncodeHex function.

func GenerateCryptoPIN

func GenerateCryptoPIN(length int) (string, error)

GenerateCryptoPIN creates a cryptographically secure random pin number style security code of the designated character length. The output of this function is suitable for generating pin numbers for use in a two-factor auth system which uses security code verification over a medium like SMS or email.

func GenerateCryptoSequence

func GenerateCryptoSequence(length int) ([]byte, error)

GenerateCryptoSequence returns a cryptographically secure psuedo-random sequence of bytes of the indicated length. The output of this function is suitable for generating a secret key for use in a symmetrical encryption algorithm such as AES, a random nonce, etc. This method relies on specifics of the underlying operating system and if a byte slice of the full indicated length cannot be generated an error will be returned.

func GenerateHMACSHA256Key

func GenerateHMACSHA256Key() ([]byte, error)

GenerateHMACSHA256Key is an alias for GenerateCryptoSequence(32). An HMAC SHA-256 key is expressed here as a byte slice. To obtain the plain text equivalent of this key for storage use the EncodeB64 or EncodeHex function.

func GenerateHMACSHA512Key

func GenerateHMACSHA512Key() ([]byte, error)

GenerateHMACSHA512Key is an alias for GenerateCryptoSequence(64). An HMAC SHA-512 key is expressed here as a byte slice. To obtain the plain text equivalent of this key for storage use the EncodeB64 or EncodeHex function.

func GeneratePIN

func GeneratePIN(length int) string

GeneratePIN creates a psuedo-random pin number style security code of the designated character length. The output of this function is suitable for generating pin numbers for use in a two-factor auth system which uses security code verification over a medium like SMS or email.