evalphobia/hierogolyph

hieroGOlyph
----

[![GoDoc][1]][2] [![License: MIT][3]][4] [![Release][5]][6] [![Build Status][7]][8] [![Codecov Coverage][11]][12] [![Go Report Card][13]][14] [![Code Climate][19]][20] [![BCH compliance][21]][22]

[1]: https://godoc.org/github.com/evalphobia/hierogolyph?status.svg
[2]: https://godoc.org/github.com/evalphobia/hierogolyph
[3]: https://img.shields.io/badge/License-MIT-blue.svg
[4]: LICENSE.md
[5]: https://img.shields.io/github/release/evalphobia/hierogolyph.svg
[6]: https://github.com/evalphobia/hierogolyph/releases/latest
[7]: https://github.com/evalphobia/hierogolyph/workflows/test/badge.svg
[8]: https://github.com/evalphobia/hierogolyph/actions?query=workflow%3Atest
[9]: https://coveralls.io/repos/evalphobia/hierogolyph/badge.svg?branch=master&service=github
[10]: https://coveralls.io/github/evalphobia/hierogolyph?branch=master
[11]: https://codecov.io/github/evalphobia/hierogolyph/coverage.svg?branch=master
[12]: https://codecov.io/github/evalphobia/hierogolyph?branch=master
[13]: https://goreportcard.com/badge/github.com/evalphobia/hierogolyph
[14]: https://goreportcard.com/report/github.com/evalphobia/hierogolyph
[15]: https://img.shields.io/github/downloads/evalphobia/hierogolyph/total.svg?maxAge=1800
[16]: https://github.com/evalphobia/hierogolyph/releases
[17]: https://img.shields.io/github/stars/evalphobia/hierogolyph.svg
[18]: https://github.com/evalphobia/hierogolyph/stargazers
[19]: https://codeclimate.com/github/evalphobia/hierogolyph/badges/gpa.svg
[20]: https://codeclimate.com/github/evalphobia/hierogolyph
[21]: https://bettercodehub.com/edge/badge/evalphobia/hierogolyph?branch=master
[22]: https://bettercodehub.com/

`hierogolyph` is library for encryption/decryption plain text.
The implementation and cryptographic process is based on [18F/identity-idp](https://github.com/18F/identity-idp/blob/master/docs/encryption-and-key-rotation.md#implementation).

# Usage



```go
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