credentials

package
v3.0.1+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 4, 2017 License: Apache-2.0 Imports: 16 Imported by: 12

Documentation

Overview

Package credentials provides credential retrieval and management for S3 compatible object storage.

By default the Credentials.Get() will cache the successful result of a Provider's Retrieve() until Provider.IsExpired() returns true. At which point Credentials will call Provider's Retrieve() to get new credential Value.

The Provider is responsible for determining when credentials have expired. It is also important to note that Credentials will always call Retrieve the first time Credentials.Get() is called.

Example of using the environment variable credentials.

creds := NewFromEnv()
// Retrieve the credentials value
credValue, err := creds.Get()
if err != nil {
    // handle error
}

Example of forcing credentials to expire and be refreshed on the next Get(). This may be helpful to proactively expire credentials and refresh them sooner than they would naturally expire on their own.

creds := NewFromIAM("")
creds.Expire()
credsValue, err := creds.Get()
// New credentials will be retrieved instead of from cache.

Custom Provider

Each Provider built into this package also provides a helper method to generate a Credentials pointer setup with the provider. To use a custom Provider just create a type which satisfies the Provider interface and pass it to the NewCredentials method.

type MyProvider struct{}
func (m *MyProvider) Retrieve() (Value, error) {...}
func (m *MyProvider) IsExpired() bool {...}

creds := NewCredentials(&MyProvider{})
credValue, err := creds.Get()

Index

Constants

View Source
const DefaultExpiryWindow = time.Second * 10 // 10 secs

DefaultExpiryWindow - Default expiry window. ExpiryWindow will allow the credentials to trigger refreshing prior to the credentials actually expiring. This is beneficial so race conditions with expiring credentials do not cause request to fail unexpectedly due to ExpiredTokenException exceptions.

Variables

This section is empty.

Functions

This section is empty.

Types

type Chain

type Chain struct {
	Providers []Provider
	// contains filtered or unexported fields
}

A Chain will search for a provider which returns credentials and cache that provider until Retrieve is called again.

The Chain provides a way of chaining multiple providers together which will pick the first available using priority order of the Providers in the list.

If none of the Providers retrieve valid credentials Value, ChainProvider's Retrieve() will return the error, collecting all errors from all providers.

If a Provider is found which returns valid credentials Value ChainProvider will cache that Provider for all calls to IsExpired(), until Retrieve is called again.

creds := credentials.NewChainCredentials(
    []credentials.Provider{
        &credentials.EnvAWSS3{},
        &credentials.EnvMinio{},
    })

// Usage of ChainCredentials.
mc, err := minio.NewWithCredentials(endpoint, creds, secure, "us-east-1")
if err != nil {
     log.Fatalln(err)
}

func (*Chain) IsExpired

func (c *Chain) IsExpired() bool

IsExpired will returned the expired state of the currently cached provider if there is one. If there is no current provider, true will be returned.

func (*Chain) Retrieve

func (c *Chain) Retrieve() (Value, error)

Retrieve returns the credentials value or error if no provider returned without error.

If a provider is found it will be cached and any calls to IsExpired() will return the expired state of the cached provider.

type Credentials

type Credentials struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Credentials - A container for synchronous safe retrieval of credentials Value. Credentials will cache the credentials value until they expire. Once the value expires the next Get will attempt to retrieve valid credentials.

Credentials is safe to use across multiple goroutines and will manage the synchronous state so the Providers do not need to implement their own synchronization.

The first Credentials.Get() will always call Provider.Retrieve() to get the first instance of the credentials Value. All calls to Get() after that will return the cached credentials Value until IsExpired() returns true.

func New

func New(provider Provider) *Credentials

New returns a pointer to a new Credentials with the provider set.

func NewChainCredentials

func NewChainCredentials(providers []Provider) *Credentials

NewChainCredentials returns a pointer to a new Credentials object wrapping a chain of providers.

func NewEnvAWS

func NewEnvAWS() *Credentials

NewEnvAWS returns a pointer to a new Credentials object wrapping the environment variable provider.

func NewEnvMinio

func NewEnvMinio() *Credentials

NewEnvMinio returns a pointer to a new Credentials object wrapping the environment variable provider.

func NewFileAWSCredentials

func NewFileAWSCredentials(filename string, profile string) *Credentials

NewFileAWSCredentials returns a pointer to a new Credentials object wrapping the Profile file provider.

func NewFileMinioClient

func NewFileMinioClient(filename string, alias string) *Credentials

NewFileMinioClient returns a pointer to a new Credentials object wrapping the Alias file provider.

func NewIAM

func NewIAM(endpoint string) *Credentials

NewIAM returns a pointer to a new Credentials object wrapping the IAM. Takes a ConfigProvider to create a EC2Metadata client. The ConfigProvider is satisfied by the session.Session type.

func NewStatic

func NewStatic(id, secret, token string, signerType SignatureType) *Credentials

NewStatic returns a pointer to a new Credentials object wrapping a static credentials value provider.

func NewStaticV2

func NewStaticV2(id, secret, token string) *Credentials

NewStaticV2 returns a pointer to a new Credentials object wrapping a static credentials value provider, signature is set to v2. If access and secret are not specified then regardless of signature type set it Value will return as anonymous.

func NewStaticV4

func NewStaticV4(id, secret, token string) *Credentials

NewStaticV4 is similar to NewStaticV2 with similar considerations.

func (*Credentials) Expire

func (c *Credentials) Expire()

Expire expires the credentials and forces them to be retrieved on the next call to Get().

This will override the Provider's expired state, and force Credentials to call the Provider's Retrieve().

func (*Credentials) Get

func (c *Credentials) Get() (Value, error)

Get returns the credentials value, or error if the credentials Value failed to be retrieved.

Will return the cached credentials Value if it has not expired. If the credentials Value has expired the Provider's Retrieve() will be called to refresh the credentials.

If Credentials.Expire() was called the credentials Value will be force expired, and the next call to Get() will cause them to be refreshed.

func (*Credentials) IsExpired

func (c *Credentials) IsExpired() bool

IsExpired returns if the credentials are no longer valid, and need to be refreshed.

If the Credentials were forced to be expired with Expire() this will reflect that override.

type EnvAWS

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

A EnvAWS retrieves credentials from the environment variables of the running process. EnvAWSironment credentials never expire.

EnvAWSironment variables used:

* Access Key ID: AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY. * Secret Access Key: AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY. * Secret Token: AWS_SESSION_TOKEN.

func (*EnvAWS) IsExpired

func (e *EnvAWS) IsExpired() bool

IsExpired returns if the credentials have been retrieved.

func (*EnvAWS) Retrieve

func (e *EnvAWS) Retrieve() (Value, error)

Retrieve retrieves the keys from the environment.

type EnvMinio

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

A EnvMinio retrieves credentials from the environment variables of the running process. EnvMinioironment credentials never expire.

EnvMinioironment variables used:

* Access Key ID: MINIO_ACCESS_KEY. * Secret Access Key: MINIO_SECRET_KEY.

func (*EnvMinio) IsExpired

func (e *EnvMinio) IsExpired() bool

IsExpired returns if the credentials have been retrieved.

func (*EnvMinio) Retrieve

func (e *EnvMinio) Retrieve() (Value, error)

Retrieve retrieves the keys from the environment.

type Expiry

type Expiry struct {

	// If set will be used by IsExpired to determine the current time.
	// Defaults to time.Now if CurrentTime is not set.
	CurrentTime func() time.Time
	// contains filtered or unexported fields
}

A Expiry provides shared expiration logic to be used by credentials providers to implement expiry functionality.

The best method to use this struct is as an anonymous field within the provider's struct.

Example:

type IAMCredentialProvider struct {
    Expiry
    ...
}

func (*Expiry) IsExpired

func (e *Expiry) IsExpired() bool

IsExpired returns if the credentials are expired.

func (*Expiry) SetExpiration

func (e *Expiry) SetExpiration(expiration time.Time, window time.Duration)

SetExpiration sets the expiration IsExpired will check when called.

If window is greater than 0 the expiration time will be reduced by the window value.

Using a window is helpful to trigger credentials to expire sooner than the expiration time given to ensure no requests are made with expired tokens.

type FileAWSCredentials

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

A FileAWSCredentials retrieves credentials from the current user's home directory, and keeps track if those credentials are expired.

Profile ini file example: $HOME/.aws/credentials

func (*FileAWSCredentials) IsExpired

func (p *FileAWSCredentials) IsExpired() bool

IsExpired returns if the shared credentials have expired.

func (*FileAWSCredentials) Retrieve

func (p *FileAWSCredentials) Retrieve() (Value, error)

Retrieve reads and extracts the shared credentials from the current users home directory.

type FileMinioClient

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

A FileMinioClient retrieves credentials from the current user's home directory, and keeps track if those credentials are expired.

Configuration file example: $HOME/.mc/config.json

func (*FileMinioClient) IsExpired

func (p *FileMinioClient) IsExpired() bool

IsExpired returns if the shared credentials have expired.

func (*FileMinioClient) Retrieve

func (p *FileMinioClient) Retrieve() (Value, error)

Retrieve reads and extracts the shared credentials from the current users home directory.

type IAM

type IAM struct {
	Expiry

	// Required http Client to use when connecting to IAM metadata service.
	Client *http.Client
	// contains filtered or unexported fields
}

A IAM retrieves credentials from the EC2 service, and keeps track if those credentials are expired.

func (*IAM) Retrieve

func (m *IAM) Retrieve() (Value, error)

Retrieve retrieves credentials from the EC2 service. Error will be returned if the request fails, or unable to extract the desired

type Provider

type Provider interface {
	// Retrieve returns nil if it successfully retrieved the value.
	// Error is returned if the value were not obtainable, or empty.
	Retrieve() (Value, error)

	// IsExpired returns if the credentials are no longer valid, and need
	// to be retrieved.
	IsExpired() bool
}

A Provider is the interface for any component which will provide credentials Value. A provider is required to manage its own Expired state, and what to be expired means.

type SignatureType

type SignatureType int

SignatureType is type of Authorization requested for a given HTTP request.

const (
	// SignatureDefault is always set to v4.
	SignatureDefault SignatureType = iota
	SignatureV4
	SignatureV2
	SignatureV4Streaming
	SignatureAnonymous // Anonymous signature signifies, no signature.
)

Different types of supported signatures - default is SignatureV4 or SignatureDefault.

func (SignatureType) IsAnonymous

func (s SignatureType) IsAnonymous() bool

IsAnonymous - is signature empty?

func (SignatureType) IsStreamingV4

func (s SignatureType) IsStreamingV4() bool

IsStreamingV4 - is signature SignatureV4Streaming?

func (SignatureType) IsV2

func (s SignatureType) IsV2() bool

IsV2 - is signature SignatureV2?

func (SignatureType) IsV4

func (s SignatureType) IsV4() bool

IsV4 - is signature SignatureV4?

func (SignatureType) String

func (s SignatureType) String() string

Stringer humanized version of signature type, strings returned here are case insensitive.

type Static

type Static struct {
	Value
}

A Static is a set of credentials which are set programmatically, and will never expire.

func (*Static) IsExpired

func (s *Static) IsExpired() bool

IsExpired returns if the credentials are expired.

For Static, the credentials never expired.

func (*Static) Retrieve

func (s *Static) Retrieve() (Value, error)

Retrieve returns the static credentials.

type Value

type Value struct {
	// AWS Access key ID
	AccessKeyID string

	// AWS Secret Access Key
	SecretAccessKey string

	// AWS Session Token
	SessionToken string

	// Signature Type.
	SignerType SignatureType
}

A Value is the AWS credentials value for individual credential fields.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL