hierogolyph

README

hieroGOlyph

hierogolyph is library for encryption/decryption plain text. The implementation and cryptographic process is based on 18F/identity-idp.

Usage

import (
	"github.com/evalphobia/hierogolyph"
	"github.com/evalphobia/hierogolyph/cipher/aesgcm"
	"github.com/evalphobia/hierogolyph/hasher/argon2"
	hsmgcm "github.com/evalphobia/hierogolyph/hsm/aesgcm"
)

const (
	hmacKey   = `abcdefg`
	gcmKey256 = "12345678901234567890123456789012" // 32byte
)

// You can choose your prefered Cipher, HSM, Hasher and set HMACKey in config.
var defaultConfig = hierogolyph.Config{
	Cipher:  aesgcm.CipherGCM{},
	HSM:     hsmgcm.NewAesGcm([]byte(gcmKey256)),
	Hasher:  argon2.Argon2{},
	HMACKey: hmacKey,
}

func main() {
	user1 := User{
		ID:  "1",
		Key: "random strings",
		PII: "gopher",
	}

	// if raw key is saved in any data store, don't use it.
	// convert raw key in safe way... (not like below)
	const secretSalt = "this salt is used for converting user's Key and result is used for encryption/decryption"

	secretSaltForUser1 := secretSalt + user1.ID

	// [encryption phase here]
	{
		key := argon2.Argon2{}.Hash(user1.Key, secretSaltForUser1)
		h, err := hierogolyph.CreateHierogolyph(key, defaultConfig)
		if err != nil {
			panic(err)
		}

		cipherText, err := h.Encrypt(user1.PII)
		if err != nil {
			panic(err)
		}

		// you should save these values
		user1.EncryptedPII = cipherText
		user1.Salt = h.Salt
		// clear PII
		user1.PII = ""
	}

	// some process...

	// [decryption phase here]
	{
		key := argon2.Argon2{}.Hash(user1.Key, secretSaltForUser1)
		h := hierogolyph.Hierogolyph{
			Config:        defaultConfig,
			Password:      key,
			Salt:          user1.Salt,
		}

		plainText, err := h.Decrypt(user1.EncryptedPII)
		if err != nil {
			panic(err)
		}

		user1.PII = plainText
	}
}

type User struct {
	ID           string
	Key          string
	PII          string
	EncryptedPII string

	// these are generated by hierogolyph
	Salt          string
	EncryptionKey string
}

Supported cryptography

• Hash
  • Argon2id
  • Baloon (by https://github.com/nogoegst/balloon)
  • PBKDF2
  • SCrypt
• HSM
  • Amazon KMS
  • AES GCM (mock)
  • ChaCha20-Poly1305 (mock)
• Main Encryption
  • AES GCM
  • ChaCha20-Poly1305

Documentation

Index

• func HashHMAC(plainText, key string) string
• func HashSHA256(data string) string
• type Config
• type Hierogolyph
  • func CreateHierogolyph(password string, conf Config) (Hierogolyph, error)
  • func (h Hierogolyph) Decrypt(cipherText string) (plainText string, err error)
  • func (h Hierogolyph) Encrypt(plainText string) (cipherText string, err error)
  • func (h *Hierogolyph) SetEncryptionKey() error
  • func (h Hierogolyph) Unlock() (cek string, err error)

Functions

func HashHMAC

func HashHMAC(plainText, key string) string

HashHMAC returns a HMAC signed message using the given key.

func HashSHA256

func HashSHA256(data string) string

HashSHA256 returns the SHA256 checksum of the data.

Types

type Config

type Config struct {
	// Cipher is the main algorithm to encrypt/decrypt text.
	// (e,g, AES GCM)
	Cipher cipher.Cipher

	// HSM is Hardware Security Module
	// (e.g. AWS KMS)
	HSM hsm.HSM

	// Hasher is hashing algorithm.
	// (e.g. Argon2, Scrypt)
	Hasher hasher.Hasher

	// HMACKey is the key used for signing message with HMAC.
	HMACKey string
}

type Hierogolyph

type Hierogolyph struct {
	Config

	Password      string
	Salt          string
	EncryptionKey string // generated by password and salt, used for encryption/decryption and verifying password.
}

Hierogolyph treats encryption and decryption.

func CreateHierogolyph

func CreateHierogolyph(password string, conf Config) (Hierogolyph, error)

CreateHierogolyph creates new Hierogolyph from given password, which is used for encryption. (after the first encryption, don't use this constructor.)

func (Hierogolyph) Decrypt

func (h Hierogolyph) Decrypt(cipherText string) (plainText string, err error)

Decrypt decrypts given cipherText.

func (Hierogolyph) Encrypt

func (h Hierogolyph) Encrypt(plainText string) (cipherText string, err error)

Encrypt encrypts given plainText.

func (*Hierogolyph) SetEncryptionKey

func (h *Hierogolyph) SetEncryptionKey() error

SetEncryptionKey sets an encryption key generated from password and salt.

func (Hierogolyph) Unlock

func (h Hierogolyph) Unlock() (cek string, err error)

Unlock creates Content Encryption Key.