secrecy

README

secrecy

secrecy is a Go module that enables wrapping sensitive values so that they are never shown when the value is printed, logged, or encoded. Any formatting interface (Stringer, json.Marshaler, etc.) will return a constant redacted string rather than the underlying value.

The project is inspired by the Rust secrecy crate and exposes a similar API in Go.

Installation

go get github.com/ryanfowler/secrecy@latest

Usage

Import the package and wrap sensitive values using secrecy.New. In order to access the underlying secret, you must use the Expose() method.

import "github.com/ryanfowler/secrecy"

type Login struct {
    Username string
    Password secrecy.Secret[string]
}

login := Login{
    Username: "ryanfowler",
    Password: secrecy.New("secretpassword"),
}

// Will output:
// Login = {Username:ryanfowler Password:[redacted]}
fmt.Printf("Login = %+v\n", login)

// Will output:
// Equal = true
fmt.Printf("Equal = %t\n", login.Password.Expose() == "secretpassword")

In order to have the underlying secret "zeroed" when the Secret gets garbage collected, create the Secret with the secrecy.NewZeroizing method.

Customising the redaction string

The string shown when a secret is formatted defaults to "[REDACTED]". It can be changed globally before any Secret values are created using secrecy.SetRedactedString.

func init() {
    secrecy.SetRedactedString("***")
}

All formatting and encoding operations will now emit the custom string.

Zeroizing secrets

A secret can have it's contents zeroed by calling the Zero() method.

s := secrecy.New([]byte("secretpassword"))
defer s.Zero()

useSecret(s.Expose())

Alternatively, the secrecy.NewZeroizing function returns a pointer to a Secret that will automatically zero its value once the object becomes unreachable and is garbage collected.

s := secrecy.NewZeroizing([]byte("secretpassword"))

useToken(s.Expose())

After Zero() has been invoked, Expose() will return the zero value for the wrapped type.

License

This project is licensed under the MIT License.

Documentation

Overview

Package secrecy provides helpers for handling sensitive values. When wrapped in a Secret, the original value will never be printed or encoded unless it is explicitly exposed with the Expose method.

Index

• func SetRedactedString(s string)
• func Zeroize(value any)
• type Secret
  • func New[T any](value T) Secret[T]
  • func NewZeroizing[T any](value T) *Secret[T]
  • func (s Secret[T]) Expose() T
  • func (s Secret[T]) GoString() string
  • func (s Secret[T]) GobEncode() ([]byte, error)
  • func (s Secret[T]) MarshalJSON() ([]byte, error)
  • func (s Secret[T]) MarshalTOML() ([]byte, error)
  • func (s Secret[T]) MarshalText() ([]byte, error)
  • func (s Secret[T]) MarshalYAML() (any, error)
  • func (s Secret[T]) String() string
  • func (s *Secret[T]) UnmarshalJSON(data []byte) error
  • func (s *Secret[T]) Zero()

Functions

func SetRedactedString

func SetRedactedString(s string)

SetRedactedString sets the global value used when a secret is formatted or encoded. It should be called during program initialization, before any Secrets are created. By default the string is "[REDACTED]".

func Zeroize

func Zeroize(value any)

Zeroize recursively zeroes the provided value in place when possible. It traverses slices, maps and structs, clearing every reachable element. Private struct fields are skipped as they cannot be modified via reflection.

Types

type Secret

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

Secret wraps a sensitive value to prevent it from being inadvertently leaked through logging, formatting, or other encoding mechanisms. To retrieve the underlying value, the Expose method must be called.

func New

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

New returns a new Secret that wraps the provided value.

password := secrecy.New("p@ssword")
fmt.Println(password) // prints [REDACTED]

func NewZeroizing

func NewZeroizing[T any](value T) *Secret[T]

NewZeroizing returns a pointer to a Secret that wraps the provided value and automatically zeroes it when the Secret is garbage collected. The value should not be accessed or modified outside of the returned Secret.

token := secrecy.NewZeroizing([]byte("key"))

func (Secret[T]) Expose

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

Expose returns the underlying secret value. This is the only way to retrieve the wrapped data.

func (Secret[T]) GoString

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

GoString implements the GoStringer interface.

func (Secret[T]) GobEncode

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

GobEncode implements the GobEncoder interface.

func (Secret[T]) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface.

func (Secret[T]) MarshalTOML

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

MarshalTOML implements the toml.Marshaler interface.

func (Secret[T]) MarshalText

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

MarshalText implements the TextMarshaler interface.

func (Secret[T]) MarshalYAML

func (s Secret[T]) MarshalYAML() (any, error)

MarshalYAML implements the yaml.Marshaler interface.

func (Secret[T]) String

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

String implements the Stinger interface.

func (*Secret[T]) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface.

func (*Secret[T]) Zero

func (s *Secret[T]) Zero()

Zero runs the Zeroize function on the underlying secret value. After calling Zero, Expose will return the zero value for type T.