gormcrypto

README

gormcrypto

Another library for encrypting/signing data with GORM

Installation

As with any other Go lib, you'll want to go get the module:

go get github.com/danhunsaker/gorm-crypto

Usage

Code-Based Config

Then, in your code, you would do something like this:

package main

import (
    "time"

    gc "github.com/danhunsaker/gorm-crypto"
    "github.com/danhunsaker/gorm-crypto/encoding"
    "github.com/danhunsaker/gorm-crypto/encryption"
    "github.com/danhunsaker/gorm-crypto/serializing"
    "github.com/danhunsaker/gorm-crypto/signing"
)

var eKey = "EncryptionKeyThatShouldBe32Bytes"
var sKey = "SigningKeyThatShouldBe32BytesToo"

func main() {
    aes, err := encryption.NewAES256GCM(eKey)
    if err != nil {
        panic(err)
    }

    gc.Init(gc.Config{
        Setups: map[time.Time]gc.Setup{
            time.Date(2022, 1, 1, 15, 17, 35, 0, time.UTC): {
				Encoder:          encoding.Base64{},
				Serializer:       serializing.JSON{},
				Encrypter: aes,
				Signer:    signing.NewED25519FromSeed(sKey),
            },
        },
    })
}

YAML-Based Config

Alternately, you can do something like this:

package main

import (
    gc "github.com/danhunsaker/gorm-crypto"
)

func main() {
    rawConfig, _ := os.ReadFile("crypto.yaml")
    gc.Init(gc.ConfigFromBytes(rawConfig))
}

And in crypto.yaml:

"2022-01-01T15:17:35Z":
  encoding:
    algorithm: base64
  serializing:
    algorithm: json
  encryption:
    algorithm: aes256gcm
    config:
      key: 456E6372797074696F6E4B65795468617453686F756C64427933324279746573 # EncryptionKeyThatShouldBe32Bytes in hex
  signing:
    algorithm: ed25519
    config:
      key: 5369676E696E674B65795468617453686F756C64426533324279746573546F6F # SigningKeyThatShouldBe32BytesToo in hex

Types

With that setup in place, it's as simple as using one or more of the types this library offers to encrypt and/or sign any field you like.

import "github.com/danhunsaker/gorm-crypto/cryptypes"

type ContrivedPersonExample struct {
    Name    cryptypes.SignedString
    Email   cryptypes.EncryptedString
    Address cryptypes.NullEncryptedString
    Phone   cryptypes.NullSignedEncryptedString
    Age     cryptypes.SignedEncryptedUint
}

All types have a Raw property, which contains the unencrypted raw value - hence the name. Signed types also have a Valid property, which tells you whether the value is untampered-with (but only when it's fresh from the DB). Null variants additionally include an Empty property, which indicates whether the value is actually nil instead of whatever concrete type it would otherwise be.

Acknowledgements

As a library with similar goals and implementation, some code is very similar to github.com/pkasila/gorm-crypto, which is an older library with more maintainers. If you don't need the advanced features offered here, please use that fine library instead!

Documentation

Overview

Package gormcrypto is another library for encrypting/signing data with GORM

Index

• func Init(c Config) error
• type Config
  • func ConfigFromBytes(contents []byte) (c Config)
  • func GlobalConfig() Config
  • func (c Config) ConfigToBytes() ([]byte, error)
  • func (c Config) CurrentSetup() Setup
  • func (c Config) UsedSetup(at time.Time) Setup
• type Setup
  • func (s Setup) String() string

Functions

func Init

func Init(c Config) error

Init sets up gormcrypto for use by telling it which Config to use. NOTE: This function may be deprecated at some point if I can work out how to properly make gormcrypto into a GORM plugin.

Types

type Config

type Config struct {
	Setups map[time.Time]Setup
}

Config provides the global configuration data for gormcrypto. At the moment, that's just a list of different Setups your application supports. We support multiple Setups because application requirements change over time, and you'll want to be able to use values encrypted/signed by older keys/algorithms. The Time value used in the map indicates when the Setup was - or should be - made active in your code.

func ConfigFromBytes

func ConfigFromBytes(contents []byte) (c Config)

ConfigFromBytes converts a YAML document into a valid Config object

func GlobalConfig

func GlobalConfig() Config

GlobalConfig gets the global config value. NOTE: This function will be deprecated at some point if I can work out how to properly make gormcrypto into a GORM plugin.

func (Config) ConfigToBytes

func (c Config) ConfigToBytes() ([]byte, error)

ConfigToBytes converts a Config value into a YAML-encoded byte slice for export to a file or other storage

func (Config) CurrentSetup

func (c Config) CurrentSetup() Setup

CurrentSetup returns the most recent Setup value based on the Time it was set up under

func (Config) UsedSetup

func (c Config) UsedSetup(at time.Time) Setup

UsedSetup returns the most recent Setup value based on the passed Time, falling back to CurrentSetup

type Setup

type Setup struct {
	Encoder    encoding.Algorithm
	Serializer serializing.Algorithm
	Encrypter  encryption.Algorithm
	Signer     signing.Algorithm
}

Setup describes the way your data should be handled by gormcrypto. That includes the encryption algorithm/keys, the signing algorithm/keys, the mechanism for serializing values, and the encoding to use to coerce binary data into values that can safely be serialized/stored.

func (Setup) String

func (s Setup) String() string

String converts the Setup to a string that indicates its components in a useful fashion