conceal

README

go-conceal

Guard against logging secrets in Go.

conceal (verb):
  1. to hide; withdraw or remove from observation
  2. to keep secret; to prevent or avoid disclosing

Project Overview

Module github.com/shoenig/go-conceal can be used to help protect against sensitive values from being exposed in places they shouldn't be, particularly in log lines.

Getting Started

The conceal package can be gotten with go get:

$ go get github.com/shoenig/go-conceal

Example Usage

// protect a string value
text := conceal.New("abc123")
fmt.Sprintf("%s", text) // prints "<redacted>"
fmt.Sprintf("%#v", text) // prints "conceal.Text{}"

// protect a byte slice
b := conceal.NewBytes([]byte{1, 2, 3})
fmt.Sprintf("%s", b) // prints "<redacted>"
fmt.Sprintf("%#v", b) // prints "conceal.Bytes{}"

// get access to the underlying secret values
doThings(text.Unveil(), b.Unveil())

Contributing

The github.com/shoenig/go-conceal module is always improving with new features and error corrections. For contributing bug fixes and new features please file an issue.

License

The github.com/shoenig/go-conceal module is open source under the BSD-3-Clause license.

Documentation

Overview

Package conceal provides types for protecting sensitive text in logs.

Index

• type Bytes
  • func NewBytes(b []byte) *Bytes
  • func (b *Bytes) Copy() *Bytes
  • func (b *Bytes) Equal(o *Bytes) bool
  • func (b *Bytes) GoString() string
  • func (b *Bytes) Hash() int
  • func (b *Bytes) String() string
  • func (b *Bytes) Unveil() []byte
• type Text
  • func New(s string) *Text
  • func UUIDv4() *Text
  • func (t *Text) Copy() *Text
  • func (t *Text) Equal(o *Text) bool
  • func (t *Text) GoString() string
  • func (t *Text) Hash() int
  • func (t *Text) MarshalText() ([]byte, error)
  • func (t *Text) String() string
  • func (t *Text) UnmarshalText(text []byte) error
  • func (t *Text) Unveil() string

Types

type Bytes

type Bytes struct {
	// contains filtered or unexported fields
}

A Bytes secret contains a byte slice which should not be exposed.

This type overrides String and GoString such that the underlying data does not get exposed (typically through log statements) accidentally.

To get at the underlying data, use the Secret method.

Unlike a Go byte slice, Bytes is not 'comparable' (it can't be a map key or support ==). Use its Equal method to compare.

func NewBytes

func NewBytes(b []byte) *Bytes

NewBytes returns a Bytes that keeps b a secret.

A copy of b is created, so that later changes to b have no effect on the protected value.

func (*Bytes) Copy

func (b *Bytes) Copy() *Bytes

Copy creates a deep copy of b.

func (*Bytes) Equal

func (b *Bytes) Equal(o *Bytes) bool

Equal returns true if the underlying bytes of t and o are the same.

func (*Bytes) GoString

func (b *Bytes) GoString() string

GoString returns "conceal.Bytes{}".

func (*Bytes) Hash

func (b *Bytes) Hash() int

Hash creates a deterministic hash from the content of t.

Implements hashicorp/go-set/HashFunc[int].

func (*Bytes) String

func (b *Bytes) String() string

String returns "<redacted>" instead of the underlying value.

func (*Bytes) Unveil

func (b *Bytes) Unveil() []byte

Unveil returns the underlying value.

This method should never be called in a context where the value should not be exposed, for example in log lines.

type Text

type Text struct {
	// contains filtered or unexported fields
}

A Text contains a string which should not be exposed (e.g. in logs).

This type overrides String and GoString such that the underling data does not get exposed (typically through log statements) accidentally.

To get at the underlying data, use the Secret method.

Unlike a Go string, Text is not 'comparable' (it can't be a map key or support ==). Use its Equal method to compare, and its Hash method for use in a hashicorp/go-set.HashMap[Text].

func New

func New(s string) *Text

New returns a Text that keeps s hidden.

func UUIDv4

func UUIDv4() *Text

UUIDv4 creates a quasi uuid v4 formatted string, useable for secrets.

Not strictly compliant with uuid v4 as these do not contain version bits.

func (*Text) Copy

func (t *Text) Copy() *Text

Copy creates a deep copy of t.

func (*Text) Equal

func (t *Text) Equal(o *Text) bool

Equal returns true if the underlying text of t and o are the same.

func (*Text) GoString

func (t *Text) GoString() string

GoString returns "conceal.Text{}".

func (*Text) Hash

func (t *Text) Hash() int

Hash creates a deterministic hash from the content of t.

Implements hashicorp/go-set/HashFunc[int].

func (*Text) MarshalText

func (t *Text) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaller interface, which is also compatible with the encoding/json marshaller.

func (*Text) String

func (t *Text) String() string

String returns "(redacted)" instead of the underlying value.

func (*Text) UnmarshalText

func (t *Text) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface, which is also compatible with the encoding/json un-marshaller.

func (*Text) Unveil

func (t *Text) Unveil() string

Unveil returns the underlying value.

This method should never be called in a context where the value should not be exposed, for example in log lines.