Package: credentials

import "../ibm-cos-sdk-go/aws/credentials"

Overview

Package credentials provides credential retrieval and management

The Credentials is the primary method of getting access to and managing credentials Values. Using dependency injection retrieval of the credential values is handled by a object which satisfies the Provider interface.

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 Value 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 := credentials.NewEnvCredentials()

// 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 := credentials.NewCredentials(&ec2rolecreds.EC2RoleProvider{})
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 := credentials.NewCredentials(&MyProvider{})
credValue, err := creds.Get()

Sub-Packages

endpointcreds, ibmiam, plugincreds, processcreds

Constants

const EnvProviderName = readonly

EnvProviderName provides a name of Env provider

Value:

"EnvProvider"

const StaticProviderName = readonly

StaticProviderName provides a name of Static provider

Value:

"StaticProvider"

const SharedCredsProviderName = readonly

SharedCredsProviderName provides a name of SharedCreds provider

Value:

"SharedCredentialsProvider"

Variables

var AnonymousCredentials = writable

AnonymousCredentials is an empty Credential object that can be used as dummy placeholder credentials for requests that do not need signed.

This Credentials can be used to configure a service to not sign requests when making service API calls. For example, when accessing public s3 buckets.

svc := s3.New(session.Must(session.NewSession(&aws.Config{
  Credentials: credentials.AnonymousCredentials,
})))
// Access public S3 buckets.

Value:

NewStaticCredentials("", "", "")

var ErrAccessKeyIDNotFound = writable

ErrAccessKeyIDNotFound is returned when the AWS Access Key ID can't be found in the process's environment.

Value:

awserr.New("EnvAccessKeyNotFound", "AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY not found in environment", nil)

var ErrSecretAccessKeyNotFound = writable

ErrSecretAccessKeyNotFound is returned when the AWS Secret Access Key can't be found in the process's environment.

Value:

awserr.New("EnvSecretNotFound", "AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY not found in environment", nil)

var ErrNoValidProvidersFoundInChain = writable

ErrNoValidProvidersFoundInChain Is returned when there are no valid providers in the ChainProvider.

This has been deprecated. For verbose error messaging set aws.Config.CredentialsChainVerboseErrors to true.

Value:

awserr.New("NoCredentialProviders",
`no valid providers in chain. Deprecated.

var ErrStaticCredentialsEmpty = writable

ErrStaticCredentialsEmpty is emitted when static credentials are empty.

Value:

awserr.New("EmptyStaticCreds", "static credentials are empty", nil)

var ErrSharedCredentialsHomeNotFound = writable

ErrSharedCredentialsHomeNotFound is emitted when the user directory cannot be found.

Value:

awserr.New("UserHomeNotFound", "user home directory not found.", nil)

Type Summary

• ChainProvider struct

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

• Credentials struct

  A Credentials provides concurrency safe retrieval of AWS credentials Value.

• EnvProvider struct

  A EnvProvider retrieves credentials from the environment variables of the running process.

• ErrorProvider struct

  An ErrorProvider is a stub credentials provider that always returns an error this is used by the SDK when construction a known provider is not possible due to an error.

• Expiry struct

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

• SharedCredentialsProvider struct

  A SharedCredentialsProvider retrieves access key pair (access key ID, secret access key, and session token if present) credentials from the current user's home directory, and keeps track if those credentials are expired.

• StaticProvider struct

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

• Value struct

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

Interface Summary

• Expirer interface

  An Expirer is an interface that Providers can implement to expose the expiration time, if known.

• Provider interface

  A Provider is the interface for any component which will provide credentials Value.

• ProviderWithContext interface

  ProviderWithContext is a Provider that can retrieve credentials with a Context.