sqlcrypter

go-sqlcrypter

go-sqlcrypter is a Go package that enables sensitive data to be encrypted at rest within a relational database. A custom type EncryptedBytes is provided which implements the sql.Scanner and driver.Valuer interfaces allowing data to be encrypted and decrypted when writing to and reading from a SQL database. Column-level encryption provides an additional layer of security.

The following encryption providers are supported:

• AES GCM
• AWS KMS
• HashiCorp Vault

Refer to each provider for documentation and examples.

Install

go get -u github.com/bincyber/go-sqlcrypter@v0.2.0

Usage

Configure the encryption provider of your choice:

[!WARNING] Never hardcode encryption keys in source code or config files committed to git.

key := []byte("abcdef01234567899876543210fedcba")
provider, err := aescrypter.New(key, nil)
if err != nil {
    log.Fatalf("failed to initialize AES crypter. Error: %s", err)
}

Initialize the sqlcrypter with the encryption provider:

sqlcrypter.Init(provider)

Use the custom type EncryptedBytes for any sensitive data:

type Employee struct {
	Name  string
	SSN   sqlcrypter.EncryptedBytes
	Email string
	Title string
}

func main() {
	e := &Employee{
		Name:  "Tony Stark",
		SSN:   sqlcrypter.NewEncryptedBytes("999-00-1234"),
		Email: "tony@starkindustries.com",
		Title: "Genius, Billionaire, Playboy, Philanthropist",
	}
}

For a full example, see example/main.go.

Nullable columns: NullEncryptedBytes

Use NullEncryptedBytes when a column may be SQL NULL, and you need to tell NULL apart from an empty string stored as ciphertext:

By contrast, EncryptedBytes maps empty plaintext to NULL on write (driver.Valuer), which cannot represent “empty but not null.”

Constructors:

present := sqlcrypter.NewNullEncryptedBytes("secret")     // Valid=true; empty string allowed
absent  := sqlcrypter.NullEncryptedBytesNull()            // Valid=false => SQL NULL

• sqlc / pgx (Postgres BYTEA): put sqlcrypter.NullEncryptedBytes on the generated struct field. The type implements pgtype.BytesScanner and pgtype.BytesValuer. The default BYTEA codec picks these up, therefore no manual pgtype.Map registration is required.
• JSON: absent values marshal as JSON null while present values marshal as base64-encoded ciphertext (including when plaintext is empty).
• GORM: GormDataType() is nullencryptedbytes and GormDBDataType follows the same dialect mapping as EncryptedBytes (bytea / binary / blob / varbinary).

Development

Docker Compose backs local services; make dev/up and related targets invoke it against testing/docker-compose.yml.

To bring up the development environment:

make dev/up
make terraform/apply

To run the test suite:

make go/testsum

Contributing

Contributions of new encryption providers (eg, Azure Key Vault, GCP KMS, etc.) are more than welcome!

License

The source code for this library is licensed under the MIT license, which you can find in the LICENSE file.