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