jcrypt

README

JCrypt

Easily encrypt and decrypt annotated fields on-the-fly during JSON marshalling.

Marshaling

Export any data type in JSON representation as done by json.Marshal and encrypt certain values:

import (
    "fmt"

    "github.com/sbreitf1/go-jcrypt"
)

type data struct {
    UserName string `json:"username"`
    Password string `json:"password" jcrypt:"aes"`
}

func main() {
    d := data{"obi wan", "deathstar"}
    raw, _ := jcrypt.Marshal(d, &jcrypt.Options{
        GetKeyHandler: jcrypt.StaticKey([]byte("secret")),
    })

    fmt.Println(string(raw))
}

The above example will output something like

{
    "username":"obi wan",
    "password": {
        "mode":"aes",
        "data":"-uHW77tqZg8ATOVIApk9Wgh3C78x8NZl4E6xFWOTM-i1YsgKwi5NuGYOYNjg6t0pmBQawjxuRT7qDPyMaoGP1A"
    }
}

The jcrypt annotation causes the password field to be encrypted using AES. The corresponding encryption key is secret and is passed as static key.

Unmarshaling

Obtaining the plaintext value from an encrypted JSON representation is also comparable to json.Unmarshal:

import "github.com/sbreitf1/go-jcrypt"

var jsonInputData = `{"username":"obi wan","password": {"mode":"aes","data":` +
	`"-uHW77tqZg8ATOVIApk9Wgh3C78x8NZl4E6xFWOTM-i1YsgKwi5NuGYOYNjg6t0pmBQawjxuRT7qDPyMaoGP1A"}`

type data struct {
    UserName string `json:"username"`
    Password string `json:"password" jcrypt:"aes"`
}

func main() {
    var d data
    jcrypt.Unmarshal(jsonInputData, &d, &jcrypt.Options{
        GetKeyHandler: jcrypt.StaticKey([]byte("secret")),
    })

    // d now contains "obi wan" and "deathstar"
}

Missing Features

• marshal / unmarshal maps
• Respect json-annotation options like omitempty and string
• Document GetKey-Callback handler for interactive password input
• Other encryption standards
• Check for encryption / disable and document fallback-mode for unencrypted values in annotated fields
• Auto-encrypt files in fallback-mode
• YAML support

Documentation

Index

• Variables
• func IsWrongPassword(err error) bool
• func Marshal(v interface{}, options *Options) ([]byte, error)
• func MarshalToFile(file string, v interface{}, options *Options) error
• func StaticKey(key []byte) func() ([]byte, error)
• func Unmarshal(data []byte, v interface{}, options *Options) error
• func UnmarshalFromFile(file string, v interface{}, options *Options) error
• type KeySource
• type Options

Variables

var (

	// ErrChecksumMismatch is returned when the checksum of a decrypted value is wrong indicating a wrong password.
	ErrChecksumMismatch = fmt.Errorf("checksum mismatch")
)

Functions

func IsWrongPassword

func IsWrongPassword(err error) bool

IsWrongPassword returns whether the given error indicates a wrong password.

func Marshal

func Marshal(v interface{}, options *Options) ([]byte, error)

Marshal returns a json representation of v and replaces all jcrypt-annotated fields with encrypted values.

func MarshalToFile

func MarshalToFile(file string, v interface{}, options *Options) error

MarshalToFile marshals an object and writes the data to a file using os.ModePerm.

func StaticKey

func StaticKey(key []byte) func() ([]byte, error)

StaticKey returns a KeySource to be used for Options.GetKeyHandler that simply returns a fixed key.

func Unmarshal

func Unmarshal(data []byte, v interface{}, options *Options) error

Unmarshal reads a json-representation and decrypts all jcrypt-annoted fields.

func UnmarshalFromFile

func UnmarshalFromFile(file string, v interface{}, options *Options) error

UnmarshalFromFile reads a file and unmarshals it.

Types

type KeySource

type KeySource func() ([]byte, error)

KeySource defines a handler function to obtain the encryption passphrase. This handler is only called if a passphrase is required.

type Options

type Options struct {
	// Salt defines a salt for pbkdf2 key derivation
	Salt []byte
	// GetKeyHandler is called when a key is required for marshalling or unmarshalling. Is called at most once for every operation.
	GetKeyHandler KeySource
	// YAML can be set to true to output or process YAML encoding instead of JSON.
	YAML bool
}

Options define further parameters for marshalling and crypto operations.