secret

README

Generic Golang Secrets

This package uses Go 1.18's secrets to implement a wrapping structure that will unmarshal secret values but marshals them to the default / blank value. This is useful when dealing with values that you don't want to have accidentally exposed in a type safe manner.

Example

import (
    "encoding/json"
    "fmt"

    secret "github.com/andrewbenton/go-secrets"
)

type myConfig struct {
    Username string                `json:"username"`
    Password secret.Secret[string] `json:"password"`
}

func main() {
    input := `{"username": "andrew", "password": "super secret password"}`

    var cfg myConfig
    if err := json.Unmarshal(input, &cfg); err != nil {
        panic(err)
    }

    // secret is hidden when marshaling
    data, err := json.Marshal(cfg)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(data))

    // recursive reflection based printing won't reveal the secret
    fmt.Printf("%#v\n", cfg)

    // secret isn't shown!
    fmt.Println(cfg)

    // secret still isn't shown!
    fmt.Println(cfg.Password)

    // secret can be directly accessed
    fmt.Println(cfg.Password.Get())
}

Performance

Performance isn't the primary concern of this library, however it's important to recognize that the additional functionality required to keep secrets hidden costs more. The tests below contrast the JSON marshaling and unmarshaling performance of a string vs a Secret[string]. These results were executed against an AMD Ryzen 9 7900X running in 105W Eco mode.

Go 1.22.0:

BenchmarkJsonMarshal-24                 10483046               104.5 ns/op
BenchmarkJsonUnmarshal-24                6155026               175.8 ns/op
BenchmarkSecret_MarshalJSON-24           7724763               147.7 ns/op
BenchmarkSecret_UnmarshalJSON-24         3029302               397.4 ns/op

Documentation

Index

• type Secret
  • func Make[T any](value T) Secret[T]
  • func (s Secret[T]) Get() T
  • func (s Secret[T]) MarshalJSON() ([]byte, error)
  • func (s Secret[T]) Set(value T)
  • func (s Secret[T]) String() string
  • func (s *Secret[T]) UnmarshalJSON(input []byte) error

Types

type Secret

type Secret[T any] struct {
	// contains filtered or unexported fields
}

Secret contains a value that can be unmarshaled but should never be printed

func Make

func Make[T any](value T) Secret[T]

Make is the standard way that secrets must be created to be properly initialized and sealed.

func (Secret[T]) Get

func (s Secret[T]) Get() T

Get returns the hidden secret value

func (Secret[T]) MarshalJSON

func (s Secret[T]) MarshalJSON() ([]byte, error)

MarshalJSON returns a marshaled form of the underlying secret. For example, a string secret will return an empty string and a numeric secret will return a zero value.

func (Secret[T]) Set

func (s Secret[T]) Set(value T)

Set updates the hidden secret value

func (Secret[T]) String

func (s Secret[T]) String() string

String shows the type of the secret without showing the value.

func (*Secret[T]) UnmarshalJSON

func (s *Secret[T]) UnmarshalJSON(input []byte) error

UnmarshalJSON decodes the input into the underlying secret's value