Struct: credentials.Credentials

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

Overview

A Credentials provides concurrency safe retrieval of AWS 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.

Implemented Interfaces

s3crypto.Cipher, credentials.Expirer, s3manager.ReadSeekerWriteTo, s3manager.WriterReadFrom

Constructor Functions collapse

Method Summary collapse

Function Details

func NewChainCredentials(providers []Provider) *Credentials

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



59
60
61
62
63
 
// File 'aws/credentials/chain_provider.go', line 59


func NewChainCredentials(providers []Provider) *Credentials {
	return NewCredentials(&ChainProvider{
		Providers: append([]Provider{}, providers...),
	})
}

func NewCredentials(provider Provider) *Credentials

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



231
232
233
234
235
236
 
// File 'aws/credentials/credentials.go', line 231


func NewCredentials(provider Provider) *Credentials {
	c := &Credentials{
		provider: provider,
	}
	return c
}

func NewEnvCredentials() *Credentials

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



35
36
37
 
// File 'aws/credentials/env_provider.go', line 35


func NewEnvCredentials() *Credentials {
	return NewCredentials(&EnvProvider{})
}

func NewSharedCredentials(filename, profile string) *Credentials

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



44
45
46
47
48
49
 
// File 'aws/credentials/shared_credentials_provider.go', line 44


func NewSharedCredentials(filename, profile string) *Credentials {
	return NewCredentials(&SharedCredentialsProvider{
		Filename: filename,
		Profile:  profile,
	})
}

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

NewStaticCredentials returns a pointer to a new Credentials object wrapping a static credentials value provider. Token is only required for temporary security credentials retrieved via STS, otherwise an empty string can be passed for this parameter.



24
25
26
27
28
29
30
 
// File 'aws/credentials/static_provider.go', line 24


func NewStaticCredentials(id, secret, token string) *Credentials {
	return NewCredentials(&StaticProvider{Value: Value{
		AccessKeyID:     id,
		SecretAccessKey: secret,
		SessionToken:    token,
	}})
}

func NewStaticCredentialsFromCreds(creds Value) *Credentials

NewStaticCredentialsFromCreds returns a pointer to a new Credentials object wrapping the static credentials value provide. Same as NewStaticCredentials but takes the creds Value instead of individual fields



35
36
37
 
// File 'aws/credentials/static_provider.go', line 35


func NewStaticCredentialsFromCreds(creds Value) *Credentials {
	return NewCredentials(&StaticProvider{Value: creds})
}

Method Details

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().



319
320
321
322
323
324
 
// File 'aws/credentials/credentials.go', line 319


func (c *Credentials) Expire() {
	c.m.Lock()
	defer c.m.Unlock()

	c.creds = Value{}
}

func (c *Credentials) ExpiresAt() (time.Time, error)

ExpiresAt provides access to the functionality of the Expirer interface of the underlying Provider, if it supports that interface. Otherwise, it returns an error.



364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
// File 'aws/credentials/credentials.go', line 364


func (c *Credentials) ExpiresAt() (time.Time, error) {
	c.m.RLock()
	defer c.m.RUnlock()

	expirer, ok := c.provider.(Expirer)
	if !ok {
		return time.Time{}, awserr.New("ProviderNotExpirer",
			fmt.Sprintf("provider %s does not support ExpiresAt()",
				c.creds.ProviderName),
			nil)
	}
	if c.creds == (Value{}) {
		// set expiration time to the distant past
		return time.Time{}, nil
	}
	return expirer.ExpiresAt(), nil
}

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.



310
311
312
 
// File 'aws/credentials/credentials.go', line 310


func (c *Credentials) Get() (Value, error) {
	return c.GetWithContext(backgroundContext())
}

func (c *Credentials) GetWithContext(ctx Context) (Value, error)

GetWithContext returns the credentials value, or error if the credentials Value failed to be retrieved. Will return early if the passed in context is canceled.

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.

Passed in Context is equivalent to aws.Context, and context.Context.



250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
// File 'aws/credentials/credentials.go', line 250


func (c *Credentials) GetWithContext(ctx Context) (Value, error) {
	// Check if credentials are cached, and not expired.
	select {
	case curCreds, ok := <-c.asyncIsExpired():
		// ok will only be true, of the credentials were not expired. ok will
		// be false and have no value if the credentials are expired.
		if ok {
			return curCreds, nil
		}
	case <-ctx.Done():
		return Value{}, awserr.New("RequestCanceled",
			"request context canceled", ctx.Err())
	}

	// Cannot pass context down to the actual retrieve, because the first
	// context would cancel the whole group when there is not direct
	// association of items in the group.
	resCh := c.sf.DoChan("", func() (interface{}, error) {
		return c.singleRetrieve(&suppressedContext{ctx})
	})
	select {
	case res := <-resCh:
		return res.Val.(Value), res.Err
	case <-ctx.Done():
		return Value{}, awserr.New("RequestCanceled",
			"request context canceled", ctx.Err())
	}
}

func (c *Credentials) IsExpired() bool

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

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



331
332
333
334
335
336
 
// File 'aws/credentials/credentials.go', line 331


func (c *Credentials) IsExpired() bool {
	c.m.RLock()
	defer c.m.RUnlock()

	return c.isExpiredLocked(c.creds)
}