tcsecrets

Documentation

Overview

The secrets service provides a simple key/value store for small bits of secret data. Access is limited by scopes, so values can be considered secret from those who do not have the relevant scopes.

Secrets also have an expiration date, and once a secret has expired it can no longer be read. This is useful for short-term secrets such as a temporary service credential or a one-time signing key.

See:

How to use this package

First create a Secrets object:

secrets := tcsecrets.New(nil)

and then call one or more of secrets's methods, e.g.:

err := secrets.Ping(.....)

handling any errors...

if err != nil {
	// handle error...
}

Taskcluster Schema

The source code of this go package was auto-generated from the API definition at <rootUrl>/references/secrets/v1/api.json together with the input and output schemas it references,

Index

• type Secret
• type Secrets
  • func New(credentials *tcclient.Credentials, rootURL string) *Secrets
  • func NewFromEnv() *Secrets
  • func (secrets *Secrets) Get(name string) (*Secret, error)
  • func (secrets *Secrets) Get_SignedURL(name string, duration time.Duration) (*url.URL, error)
  • func (secrets *Secrets) List(continuationToken, limit string) (*SecretsList, error)
  • func (secrets *Secrets) Ping() error
  • func (secrets *Secrets) Remove(name string) error
  • func (secrets *Secrets) Set(name string, payload *Secret) error
• type SecretsList

Types

type Secret

type Secret struct {

	// An expiration date for this secret.
	Expires tcclient.Time `json:"expires"`

	// The secret value to be encrypted.
	//
	// Additional properties allowed
	Secret json.RawMessage `json:"secret"`
}

Message containing a Taskcluster Secret

type Secrets

type Secrets tcclient.Client

func New

func New(credentials *tcclient.Credentials, rootURL string) *Secrets

New returns a Secrets client, configured to run against production. Pass in nil credentials to create a client without authentication. The returned client is mutable, so returned settings can be altered.

secrets := tcsecrets.New(
    nil,                                      // client without authentication
    "http://localhost:1234/my/taskcluster",   // taskcluster hosted at this root URL on local machine
)
err := secrets.Ping(.....)                    // for example, call the Ping(.....) API endpoint (described further down)...
if err != nil {
	// handle errors...
}

func NewFromEnv

func NewFromEnv() *Secrets

NewFromEnv returns a *Secrets configured from environment variables.

The root URL is taken from TASKCLUSTER_PROXY_URL if set to a non-empty string, otherwise from TASKCLUSTER_ROOT_URL if set, otherwise the empty string.

The credentials are taken from environment variables:

TASKCLUSTER_CLIENT_ID
TASKCLUSTER_ACCESS_TOKEN
TASKCLUSTER_CERTIFICATE

If TASKCLUSTER_CLIENT_ID is empty/unset, authentication will be disabled.

func (*Secrets) Get

func (secrets *Secrets) Get(name string) (*Secret, error)

Read the secret associated with some key. If the secret has recently expired, the response code 410 is returned. If the caller lacks the scope necessary to get the secret, the call will fail with a 403 code regardless of whether the secret exists.

Required scopes:

secrets:get:<name>

See #get

func (*Secrets) Get_SignedURL

func (secrets *Secrets) Get_SignedURL(name string, duration time.Duration) (*url.URL, error)

Returns a signed URL for Get, valid for the specified duration.

Required scopes:

secrets:get:<name>

See Get for more details.

func (*Secrets) List

func (secrets *Secrets) List(continuationToken, limit string) (*SecretsList, error)

List the names of all secrets.

By default this end-point will try to return up to 1000 secret names in one request. But it **may return less**, even if more tasks are available. It may also return a `continuationToken` even though there are no more results. However, you can only be sure to have seen all results if you keep calling `listTaskGroup` with the last `continuationToken` until you get a result without a `continuationToken`.

If you are not interested in listing all the members at once, you may use the query-string option `limit` to return fewer.

See #list

func (*Secrets) Ping

func (secrets *Secrets) Ping() error

Respond without doing anything. This endpoint is used to check that the service is up.

See #ping

func (*Secrets) Remove

func (secrets *Secrets) Remove(name string) error

Delete the secret associated with some key.

Required scopes:

secrets:set:<name>

See #remove

func (*Secrets) Set

func (secrets *Secrets) Set(name string, payload *Secret) error

Set the secret associated with some key. If the secret already exists, it is updated instead.

Required scopes:

secrets:set:<name>

See #set

type SecretsList

type SecretsList struct {

	// Opaque `continuationToken` to be given as query-string option to get the
	// next set of provisioners.
	// This property is only present if another request is necessary to fetch all
	// results. In practice the next request with a `continuationToken` may not
	// return additional results, but it can. Thus, you can only be sure to have
	// all the results if you've called with `continuationToken` until you get a
	// result without a `continuationToken`.
	ContinuationToken string `json:"continuationToken,omitempty"`

	// Secret names
	//
	// Array items:
	// Secret name
	Secrets []string `json:"secrets"`
}

Message containing a list of secret names