configopaque

Documentation

Overview

Package configopaque implements a String type alias to mask sensitive information. Use configopaque.String on the type of sensitive fields, to mask the opaque string as `[REDACTED]`.

This ensures that no sensitive information is leaked in logs or when printing the full Collector configurations.

The only way to view the value stored in a configopaque.String is to first convert it to a string by casting with the builtin `string` function.

To achieve this, configopaque.String implements standard library interfaces like fmt.Stringer, encoding.TextMarshaler and others to ensure that the underlying value is masked when printed or serialized.

If new interfaces that would leak opaque values are added to the standard library or become widely used in the Go ecosystem, these will eventually be implemented by configopaque.String as well. This is not considered a breaking change.

Example (OpaqueMap)

cfg := &ExampleConfigMap{
	Censored: map[string]configopaque.String{
		"token": "sensitivetoken",
	},
	Uncensored: map[string]string{
		"key":   "cloud.zone",
		"value": "zone-1",
	},
}

// yaml marshaling
bytes, err := yaml.Marshal(cfg)
if err != nil {
	panic(err)
}
fmt.Printf("encoded cfg (YAML) is:\n%s\n\n", string(bytes))

Output:
encoded cfg (YAML) is:
censored:
    token: '[REDACTED]'
uncensored:
    key: cloud.zone
    value: zone-1

Example (OpaqueSlice)

package main

import (
	"encoding/json"
	"fmt"

	"go.opentelemetry.io/collector/config/configopaque"
)

func main() {
	cfg := &ExampleConfigSlice{
		Censored:   []configopaque.String{"data", "is", "sensitive"},
		Uncensored: []string{"data", "is", "not", "sensitive"},
	}

	// JSON marshaling
	bytes, err := json.MarshalIndent(cfg, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Printf("encoded cfg (JSON) is\n%s\n\n", string(bytes))
}

type ExampleConfigSlice struct {
	Censored   []configopaque.String
	Uncensored []string
}

Output:
encoded cfg (JSON) is
{
  "Censored": [
    "[REDACTED]",
    "[REDACTED]",
    "[REDACTED]"
  ],
  "Uncensored": [
    "data",
    "is",
    "not",
    "sensitive"
  ]
}

Example (OpaqueString)

rawBytes := []byte(`{
		"Censored":   "sensitive",
		"Uncensored": "not sensitive"
	}`)

// JSON unmarshaling
var cfg ExampleConfigString
err := json.Unmarshal(rawBytes, &cfg)
if err != nil {
	panic(err)
}

// YAML marshaling
bytes, err := yaml.Marshal(cfg)
if err != nil {
	panic(err)
}
fmt.Printf("encoded cfg (YAML) is:\n%s\n\n", string(bytes))

Output:
encoded cfg (YAML) is:
censored: '[REDACTED]'
uncensored: not sensitive

Index

• type MapList
  • func (ml MapList) Get(name string) (val String, ok bool)
  • func (ml MapList) Iter(yield func(name string, value String) bool)
  • func (ml *MapList) Set(name string, val String)
  • func (ml *MapList) Unmarshal(conf *confmap.Conf) error
  • func (ml MapList) Validate() error
• type Pair
• type String
  • func (s String) GoString() string
  • func (s String) MarshalBinary() (text []byte, err error)
  • func (s String) MarshalText() ([]byte, error)
  • func (s String) String() string

Examples

• Package (OpaqueMap)
• Package (OpaqueSlice)
• Package (OpaqueString)

Types

type MapList

type MapList []Pair

MapList is a replacement for map[string]configopaque.String with a similar API, which can also be unmarshalled from (and is stored as) a list of name/value pairs.

Pairs are assumed to have distinct names. This is checked during config validation.

func (MapList) Get

func (ml MapList) Get(name string) (val String, ok bool)

Get looks up a pair's value based on its name. It is the MapList equivalent of `val, ok := m[key]`. However, it has linear time complexity.

func (MapList) Iter

func (ml MapList) Iter(yield func(name string, value String) bool)

Iter is an iterator over key/value pairs for use in for-range loops. It is the MapList equivalent of directly ranging over a map.

func (*MapList) Set

func (ml *MapList) Set(name string, val String)

Set sets the value corresponding to a given name. It is the MapList equivalent of `m[key] = val`. However, it has linear time complexity, and does not affect shallow copies.

func (*MapList) Unmarshal

func (ml *MapList) Unmarshal(conf *confmap.Conf) error

Unmarshal is called by the Collector when unmarshalling from a map. When the input config is a slice, this will be skipped, and mapstructure's default unmarshalling logic will be used.

func (MapList) Validate

func (ml MapList) Validate() error

type Pair

type Pair struct {
	Name  string `mapstructure:"name"`
	Value String `mapstructure:"value"`
	// contains filtered or unexported fields
}

Pair is an element of a MapList, and consists of a name and an opaque value.

type String

type String string

String alias that is marshaled and printed in an opaque way. To recover the original value, cast it to a string.

func (String) GoString

func (s String) GoString() string

GoString formats the string as `[REDACTED]`. This is used for the %#v verb.

func (String) MarshalBinary

func (s String) MarshalBinary() (text []byte, err error)

MarshalBinary marshals the string `[REDACTED]` as []byte.

func (String) MarshalText

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

MarshalText marshals the string as `[REDACTED]`.

func (String) String

func (s String) String() string

String formats the string as `[REDACTED]`. This is used for the %s and %q verbs.