secret

README

secret v2

What secret is?

• It provides simple Go types like secret.Text to encapsulate your secret. Example:

type Login struct {
    User string
    Password secret.Text
}

• The encapsulated secret remains inaccessible to operations like printing, logging, JSON serializtion etc. A (customizable) redact hint like ***** is returned instead.
• The only way to access the actual secret value is by asking explicitly via the .Value() method.
• See godev reference for usage examples.

What secret is not?

• It is not a secret management service or your local password manager.
• It is not a Go client to facilitate communication with secret managers like Hashicorp Vault, AWS secret Manager etc. Checkout teller if that is what you are looking for.

Installation

go get github.com/rsjethani/secret/v2

NOTE: v1 is deprecated now.

Documentation

Overview

Package secret provides types to guard your secret values from leaking into logs, std* etc.

The objective is to disallow writing/serializing of secret values to std*, logs, JSON string etc. but provide access to the secret when requested explicitly.

Index

• Constants
• func CustomRedact(r string) func(*Text)
• func FiveXs(s *Text)
• func Redacted(s *Text)
• type Text
  • func NewText(s string, options ...func(*Text)) Text
  • func (s *Text) Equals(s2 Text) bool
  • func (s Text) MarshalJSON() ([]byte, error)
  • func (s Text) MarshalText() ([]byte, error)
  • func (s Text) String() string
  • func (s *Text) UnmarshalJSON(b []byte) error
  • func (s *Text) UnmarshalText(b []byte) error
  • func (s Text) Value() string

Examples

• CustomRedact
• FiveXs
• NewText
• Redacted
• Text
• Text.Equals
• Text.MarshalJSON
• Text.MarshalText
• Text.UnmarshalJSON
• Text.UnmarshalText

Constants

const DefaultRedact string = "*****"

DefaultRedact is used by default if no other redact hint is given.

Functions

func CustomRedact

func CustomRedact(r string) func(*Text)

CustomRedact option sets the value of r as the redact hint.

Example

s := secret.NewText("$ecre!", secret.CustomRedact("HIDDEN"))
fmt.Println(s, s.Value())

Output:

HIDDEN $ecre!

func FiveXs

func FiveXs(s *Text)

FiveXs option sets "XXXXX" as the redact hint.

Example

s := secret.NewText("$ecre!", secret.FiveXs)
fmt.Println(s, s.Value())

Output:

XXXXX $ecre!

func Redacted

func Redacted(s *Text)

Redacted option sets "[REDACTED]" as the redact hint.

Example

s := secret.NewText("$ecre!", secret.Redacted)
fmt.Println(s, s.Value())

Output:

[REDACTED] $ecre!

Types

type Text

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

Text provides a way to safely store your secret value and a corresponding redact hint. This redact hint what is used in operations like printing and serializing. The default value of Text is usable.

Example

s := secret.Text{}
fmt.Println(s, s.Value())

Output:

*****

func NewText

func NewText(s string, options ...func(*Text)) Text

NewText creates a new Text instance with s as the secret value. Multiple option functions can be passed to alter default behavior.

Example

s := secret.NewText("$ecre!")
fmt.Println(s, s.Value())

Output:

***** $ecre!

func (*Text) Equals

func (s *Text) Equals(s2 Text) bool

Equals checks whether s2 has same secret string or not.

Example

s1 := secret.NewText("hello")
s2 := secret.NewText("hello")
s3 := secret.NewText("hi")
fmt.Println(s1.Equals(s2))
fmt.Println(s1.Equals(s3))

Output:

true
false

func (Text) MarshalJSON

func (s Text) MarshalJSON() ([]byte, error)

MarshalJSON allows Text to be serialized into a JSON string. Only the redact hint is part of the the JSON string.

Example

login := struct {
	User     string
	Password secret.Text
}{
	User:     "John",
	Password: secret.NewText("shh!"),
}

bytes, err := json.Marshal(&login)
if err != nil {
	panic(err)
}

fmt.Println(string(bytes))

Output:

{"User":"John","Password":"*****"}

func (Text) MarshalText

func (s Text) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It marshals redact string into bytes rather than the actual secret value.

Example

sec := secret.NewText("secret!")
bytes, err := sec.MarshalText()
if err != nil {
	panic(err)
}

fmt.Println(string(bytes))

Output:

*****

func (Text) String

func (s Text) String() string

String implements the fmt.Stringer interface and returns only the redact hint. This prevents the secret value from being printed to std*, logs etc.

func (*Text) UnmarshalJSON

func (s *Text) UnmarshalJSON(b []byte) error

UnmarshalJSON allows a JSON string to be deserialized into a Text value. DefaultRedact is set as the redact hint.

Example

login := struct {
	User     string
	Password secret.Text
}{}

err := json.Unmarshal([]byte(`{"User":"John","Password":"$ecre!"}`), &login)
if err != nil {
	panic(err)
}

fmt.Printf("%+v\n", login)
fmt.Println(login.Password.Value())

Output:

{User:John Password:*****}
$ecre!

func (*Text) UnmarshalText

func (s *Text) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It unmarshals b into receiver's new secret value. If redact string is present then it is reused otherwise DefaultRedact is used.

Example

sec := secret.Text{}

err := sec.UnmarshalText([]byte(`$ecre!`))
if err != nil {
	panic(err)
}

fmt.Println(sec, sec.Value())

Output:

***** $ecre!

func (Text) Value

func (s Text) Value() string

Value gives you access to the actual secret value stored inside Text.