processcreds

Documentation

Overview

Package processcreds is a credential Provider to retrieve `credential_process` credentials.

WARNING: The following describes a method of sourcing credentials from an external process. This can potentially be dangerous, so proceed with caution. Other credential providers should be preferred if at all possible. If using this option, you should make sure that the config file is as locked down as possible using security best practices for your operating system.

You can use credentials from a `credential_process` in a variety of ways.

One way is to setup your shared config file, located in the default location, with the `credential_process` key and the command you want to be called. You also need to set the AWS_SDK_LOAD_CONFIG environment variable (e.g., `export AWS_SDK_LOAD_CONFIG=1`) to use the shared config file.

[default]
credential_process = /command/to/call

Creating a new session will use the credential process to retrieve credentials. NOTE: If there are credentials in the profile you are using, the credential process will not be used.

// Initialize a session to load credentials.
sess, _ := session.NewSession(&aws.Config{
    Region: aws.String("us-east-1")},
)

// Create S3 service client to use the credentials.
svc := s3.New(sess)

Another way to use the `credential_process` method is by using `credentials.NewCredentials()` and providing a command to be executed to retrieve credentials:

// Create credentials using the ProcessProvider.
creds := processcreds.NewCredentials("/path/to/command")

// Create service client value configured for credentials.
svc := s3.New(sess, &aws.Config{Credentials: creds})

You can set a non-default timeout for the `credential_process` with another constructor, `credentials.NewCredentialsTimeout()`, providing the timeout. To set a one minute timeout:

// Create credentials using the ProcessProvider.
creds := processcreds.NewCredentialsTimeout(
    "/path/to/command",
    time.Duration(500) * time.Millisecond)

If you need more control, you can set any configurable options in the credentials using one or more option functions. For example, you can set a two minute timeout, a credential duration of 60 minutes, and a maximum stdout buffer size of 2k.

creds := processcreds.NewCredentials(
    "/path/to/command",
    func(opt *ProcessProvider) {
        opt.Timeout = time.Duration(2) * time.Minute
        opt.Duration = time.Duration(60) * time.Minute
        opt.MaxBufSize = 2048
    })

You can also use your own `exec.Cmd`:

// Create an exec.Cmd
myCommand := exec.Command("/path/to/command")

// Create credentials using your exec.Cmd and custom timeout
creds := processcreds.NewCredentialsCommand(
	myCommand,
	func(opt *processcreds.ProcessProvider) {
		opt.Timeout = time.Duration(1) * time.Second
	})

Index

• Constants
• func NewCredentials(command string, options ...func(*ProcessProvider)) *credentials.Credentials
• func NewCredentialsCommand(command *exec.Cmd, options ...func(*ProcessProvider)) *credentials.Credentials
• func NewCredentialsTimeout(command string, timeout time.Duration) *credentials.Credentials
• type CredentialProcessResponse
• type ProcessProvider
  • func (p *ProcessProvider) IsExpired() bool
  • func (p *ProcessProvider) Retrieve() (credentials.Value, error)

Constants

const (
	// ProviderName is the name this credentials provider will label any
	// returned credentials Value with.
	ProviderName = `ProcessProvider`

	// ErrCodeProcessProviderParse error parsing process output
	ErrCodeProcessProviderParse = "ProcessProviderParseError"

	// ErrCodeProcessProviderVersion version error in output
	ErrCodeProcessProviderVersion = "ProcessProviderVersionError"

	// ErrCodeProcessProviderRequired required attribute missing in output
	ErrCodeProcessProviderRequired = "ProcessProviderRequiredError"

	// ErrCodeProcessProviderExecution execution of command failed
	ErrCodeProcessProviderExecution = "ProcessProviderExecutionError"

	// DefaultDuration is the default amount of time in minutes that the
	// credentials will be valid for.
	DefaultDuration = time.Duration(15) * time.Minute

	// DefaultBufSize limits buffer size from growing to an enormous
	// amount due to a faulty process.
	DefaultBufSize = int(8 * sdkio.KibiByte)

	// DefaultTimeout default limit on time a process can run.
	DefaultTimeout = time.Duration(1) * time.Minute
)

Functions

func NewCredentials

func NewCredentials(command string, options ...func(*ProcessProvider)) *credentials.Credentials

NewCredentials returns a pointer to a new Credentials object wrapping the ProcessProvider. The credentials will expire every 15 minutes by default.

func NewCredentialsCommand

func NewCredentialsCommand(command *exec.Cmd, options ...func(*ProcessProvider)) *credentials.Credentials

NewCredentialsCommand returns a pointer to a new Credentials object with the specified command, and default timeout, duration and max buffer size.

func NewCredentialsTimeout

func NewCredentialsTimeout(command string, timeout time.Duration) *credentials.Credentials

NewCredentialsTimeout returns a pointer to a new Credentials object with the specified command and timeout, and default duration and max buffer size.

Types

type CredentialProcessResponse

type CredentialProcessResponse struct {
	// As of this writing, the Version key must be set to 1. This might
	// increment over time as the structure evolves.
	Version int

	// The access key ID that identifies the temporary security credentials.
	AccessKeyID string `json:"AccessKeyId"`

	// The secret access key that can be used to sign requests.
	SecretAccessKey string

	// The token that users must pass to the service API to use the temporary credentials.
	SessionToken string

	// The date on which the current credentials expire.
	Expiration *time.Time
}

A CredentialProcessResponse is the AWS credentials format that must be returned when executing an external credential_process.

type ProcessProvider

type ProcessProvider struct {
	credentials.Expiry

	// Expiry duration of the credentials. Defaults to 15 minutes if not set.
	Duration time.Duration

	// 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.
	//
	// So a ExpiryWindow of 10s would cause calls to IsExpired() to return true
	// 10 seconds before the credentials are actually expired.
	//
	// If ExpiryWindow is 0 or less it will be ignored.
	ExpiryWindow time.Duration

	// MaxBufSize limits memory usage from growing to an enormous
	// amount due to a faulty process.
	MaxBufSize int

	// Timeout limits the time a process can run.
	Timeout time.Duration
	// contains filtered or unexported fields
}

ProcessProvider satisfies the credentials.Provider interface, and is a client to retrieve credentials from a process.

func (*ProcessProvider) IsExpired

func (p *ProcessProvider) IsExpired() bool

IsExpired returns true if the credentials retrieved are expired, or not yet retrieved.

func (*ProcessProvider) Retrieve

func (p *ProcessProvider) Retrieve() (credentials.Value, error)

Retrieve executes the 'credential_process' and returns the credentials.