awsutil

package module
v2.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 26, 2024 License: MPL-2.0 Imports: 19 Imported by: 2

README

AWSUTIL - Go library for generating aws credentials

NOTE: This is version 2 of the library. The v0 branch contains version 0, which may be needed for legacy applications or while transitioning to version 2.

Usage

Following is an example usage of generating AWS credentials with static user credentials


// AWS access keys for an IAM user can be used as your AWS credentials.
// This is an example of an access key and secret key
var accessKey = "AKIAIOSFODNN7EXAMPLE"
var secretKey = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

// Access key IDs beginning with AKIA are long-term access keys. A long-term
// access key should be supplied when generating static credentials.
config, err := awsutil.NewCredentialsConfig(
    awsutil.WithAccessKey(accessKey),
    awsutil.WithSecretKey(secretKey),
)
if err != nil {
    return err
}

s3Client := s3.NewFromConfig(config)

Contributing to v0

To push a bug fix or feature for awsutil v0, branch out from the awsutil/v0 branch. Commit the code changes you want to this new branch and open a PR. Make sure the PR is configured so that the base branch is set to awsutil/v0 and not main. Once the PR is reviewed, feel free to merge it into the awsutil/v0 branch. When creating a new release, validate that the Target branch is awsutil/v0 and the tag is awsutil/v0.x.x.

Documentation

Index

Constants

View Source 
const DefaultRegion = "us-east-1"

"us-east-1 is used because it's where AWS first provides support for new features, is a widely used region, and is the most common one for some services like STS.

Variables

View Source 
var ErrUpstreamRateLimited = errors.New("upstream rate limited")

Functions

func AppendAWSError 

func AppendAWSError(err error) error

AppendAWSError checks if the given error is a known AWS error we modify, and if so then returns a go-multierror, appending the original and the AWS error. If the error is not an AWS error, or not an error we wish to modify, then return the original error.

func CheckAWSError 

func CheckAWSError(err error) error

CheckAWSError will examine an error and convert to a logical error if appropriate. If no appropriate error is found, return nil

func GetRegion 

func GetRegion(ctx context.Context, configuredRegion string) (string, error)

It's impossible to mimic "normal" AWS behavior here because it's not consistent or well-defined. For example, boto3, the Python SDK (which the aws cli uses), loads `~/.aws/config` by default and only reads the `AWS_DEFAULT_REGION` environment variable (and not `AWS_REGION`, while the golang SDK does _mostly_ the opposite -- it reads the region **only** from `AWS_REGION` and not at all `~/.aws/config`, **unless** the `AWS_SDK_LOAD_CONFIG` environment variable is set. So, we must define our own approach to walking AWS config and deciding what to use.

Our chosen approach is: 

"More specific takes precedence over less specific."

1. User-provided configuration is the most explicit. 2. Environment variables are potentially shared across many invocations and so they have less precedence. 3. Configuration in `~/.aws/config` is shared across all invocations of a given user and so this has even less precedence. 4. Configuration retrieved from the EC2 instance metadata service is shared by all invocations on a given machine, and so it has the lowest precedence.

This approach should be used in future updates to this logic.

func MockAWSThrottleErr 

func MockAWSThrottleErr() error

MockAWSThrottleErr returns a mocked aws error that mimics a throttling exception.

func NewMockCredentialsProvider 

func NewMockCredentialsProvider(opts ...MockCredentialsProviderOption) aws.CredentialsProvider

NewMockCredentialsProvider provides a factory function to use with the WithCredentialsProvider option.

func RetrieveCreds 

func RetrieveCreds(ctx context.Context, accessKey, secretKey, sessionToken string, logger hclog.Logger, opt ...Option) (*aws.Config, error)

Types

type CredentialsConfig 

type CredentialsConfig struct {
	// The access key if static credentials are being used
	AccessKey string

	// The secret key if static credentials are being used
	SecretKey string

	// The session token if it is being used
	SessionToken string

	// The IAM endpoint resolver to use; if not set will use the default
	IAMEndpointResolver iam.EndpointResolverV2

	// The STS endpoint resolver to use; if not set will use the default
	STSEndpointResolver sts.EndpointResolverV2

	// If specified, the region will be provided to the config of the
	// EC2RoleProvider's client. This may be useful if you want to e.g. reuse
	// the client elsewhere. If not specified, the region will be determined
	// by the environment variables "AWS_REGION" or "AWS_DEFAULT_REGION".
	// Otherwise the default value is us-east-1.
	Region string

	// The filename for the shared credentials provider, if being used
	Filename string

	// The profile for the shared credentials provider, if being used
	Profile string

	// The role arn to use when creating either a web identity role provider
	// or a ec2-instance role provider.
	RoleARN string

	// The role session name to use when creating either a web identity role provider
	// or a ec2-instance role provider.
	RoleSessionName string

	// The role external ID to use when creating a ec2-instance role provider.
	RoleExternalId string

	// The role tags to use when creating a ec2-instance role provider.
	RoleTags map[string]string

	// The web identity token file to use if using the web identity token provider
	WebIdentityTokenFile string

	// The web identity token (contents, not the file path) to use with the web
	// identity token provider
	WebIdentityToken string

	// The http.Client to use, or nil for the client to use its default
	HTTPClient *http.Client

	// The max retries to set on the client. This is a pointer because the zero
	// value has meaning. A nil pointer will use the default value.
	MaxRetries *int

	// The logger to use for credential acquisition debugging
	Logger hclog.Logger
}

func NewCredentialsConfig 

func NewCredentialsConfig(opt ...Option) (*CredentialsConfig, error)

GenerateCredentialChain uses the config to generate a credential chain suitable for creating AWS sessions and clients.

Supported options: WithAccessKey, WithSecretKey, WithLogger, WithStsEndpointResolver, WithIamEndpointResolver, WithMaxRetries, WithRegion, WithHttpClient, WithRoleArn, WithRoleSessionName, WithRoleExternalId, WithRoleTags, WithWebIdentityTokenFile, WithWebIdentityToken.

func (*CredentialsConfig) CreateAccessKey 

func (c *CredentialsConfig) CreateAccessKey(ctx context.Context, opt ...Option) (*iam.CreateAccessKeyOutput, error)

CreateAccessKey creates a new access/secret key pair.

Supported options: WithSharedCredentials, WithAwsConfig, WithUsername, WithValidityCheckTimeout, WithIAMAPIFunc, WithSTSAPIFunc

When WithValidityCheckTimeout is non-zero, it specifies a timeout to wait on the created credentials to be valid and ready for use.

func (*CredentialsConfig) DeleteAccessKey 

func (c *CredentialsConfig) DeleteAccessKey(ctx context.Context, accessKeyId string, opt ...Option) error

DeleteAccessKey deletes an access key.

Supported options: WithSharedCredentials, WithAwsConfig, WithUserName, WithIAMAPIFunc

func (*CredentialsConfig) GenerateCredentialChain 

func (c *CredentialsConfig) GenerateCredentialChain(ctx context.Context, opt ...Option) (*aws.Config, error)

GenerateCredentialChain uses the config to generate a credential chain suitable for creating AWS clients. This will by default load configuration values from environment variables and append additional configuration options provided to the CredentialsConfig.

Supported options: WithSharedCredentials, WithCredentialsProvider

func (*CredentialsConfig) GetCallerIdentity 

func (c *CredentialsConfig) GetCallerIdentity(ctx context.Context, opt ...Option) (*sts.GetCallerIdentityOutput, error)

GetCallerIdentity runs sts.GetCallerIdentity for the current set credentials. This can be used to check that credentials are valid, in addition to checking details about the effective logged in account and user ID.

Supported options: WithSharedCredentials, WithAwsConfig, WithValidityCheckTimeout

func (*CredentialsConfig) IAMClient 

func (c *CredentialsConfig) IAMClient(ctx context.Context, opt ...Option) (IAMClient, error)

IAMClient returns an IAM client.

Supported options: WithAwsConfig, WithIAMAPIFunc, WithIamEndpointResolver.

If WithIAMAPIFunc is supplied, the included function is used as the IAM client constructor instead. This can be used for Mocking the IAM API.

func (*CredentialsConfig) RotateKeys 

func (c *CredentialsConfig) RotateKeys(ctx context.Context, opt ...Option) error

RotateKeys takes the access key and secret key from this credentials config and first creates a new access/secret key, then deletes the old access key. If deletion of the old access key is successful, the new access key/secret key are written into the credentials config and nil is returned. On any error, the old credentials are not overwritten. This ensures that any generated new secret key never leaves this function in case of an error, even though it will still result in an extraneous access key existing; we do also try to delete the new one to clean up, although it's unlikely that will work if the old one could not be deleted.

Supported options: WithSharedCredentials, WithAwsConfig WithUsername, WithValidityCheckTimeout, WithIAMAPIFunc, WithSTSAPIFunc

Note that WithValidityCheckTimeout here, when non-zero, controls the WithValidityCheckTimeout option on access key creation. See CreateAccessKey for more details.

func (*CredentialsConfig) STSClient 

func (c *CredentialsConfig) STSClient(ctx context.Context, opt ...Option) (STSClient, error)

STSClient returns a STS client.

Supported options: WithAwsConfig, WithSTSAPIFunc, WithStsEndpointResolver.

If WithSTSAPIFunc is supplied, the included function is used as the STS client constructor instead. This can be used for Mocking the STS API.

type FetchTokenContents 

type FetchTokenContents []byte

FetchTokenContents allows the use of the content of a token in the WebIdentityProvider, instead of the path to a token. Useful with a serviceaccount token requested directly from the EKS/K8s API, for example.

func (FetchTokenContents) GetIdentityToken 

func (f FetchTokenContents) GetIdentityToken() ([]byte, error)

type IAMAPIFunc 

type IAMAPIFunc func(awsConfig *aws.Config) (IAMClient, error)

IAMAPIFunc is a factory function for returning an IAM interface, useful for supplying mock interfaces for testing IAM.

func NewMockIAM 

func NewMockIAM(opts ...MockIAMOption) IAMAPIFunc

NewMockIAM provides a factory function to use with the WithIAMAPIFunc option.

type IAMClient 

type IAMClient interface {
	CreateAccessKey(context.Context, *iam.CreateAccessKeyInput, ...func(*iam.Options)) (*iam.CreateAccessKeyOutput, error)
	DeleteAccessKey(context.Context, *iam.DeleteAccessKeyInput, ...func(*iam.Options)) (*iam.DeleteAccessKeyOutput, error)
	ListAccessKeys(context.Context, *iam.ListAccessKeysInput, ...func(*iam.Options)) (*iam.ListAccessKeysOutput, error)
	GetUser(context.Context, *iam.GetUserInput, ...func(*iam.Options)) (*iam.GetUserOutput, error)
}

IAMClient represents an iam.Client

type MockAWSErr 

type MockAWSErr struct {
	Code    string
	Message string
	Fault   awserr.ErrorFault
}

MockAWSErr is used to mock API error types for tests

func (*MockAWSErr) Error 

func (e *MockAWSErr) Error() string

Error returns the error message

func (*MockAWSErr) ErrorCode 

func (e *MockAWSErr) ErrorCode() string

ErrorCode returns the error code

func (*MockAWSErr) ErrorFault 

func (e *MockAWSErr) ErrorFault() awserr.ErrorFault

ErrorFault returns one of the following values: FaultClient, FaultServer, FaultUnknown

func (*MockAWSErr) ErrorMessage 

func (e *MockAWSErr) ErrorMessage() string

ErrorMessage returns the error message

type MockCredentialsProvider 

type MockCredentialsProvider struct {
	aws.CredentialsProvider

	aws.Credentials
	// contains filtered or unexported fields
}

MockCredentialsProvider provides a way to mock the aws.CredentialsProvider

func (*MockCredentialsProvider) Retrieve 

func (m *MockCredentialsProvider) Retrieve(ctx context.Context) (aws.Credentials, error)

type MockCredentialsProviderOption 

type MockCredentialsProviderOption func(m *MockCredentialsProvider)

MockCredentialsProviderOption is a function for setting the various fields on a MockCredentialsProvider object.

func WithCredentials 

func WithCredentials(o aws.Credentials) MockCredentialsProviderOption

WithCredentials sets the output for the Retrieve method.

func WithError 

func WithError(o error) MockCredentialsProviderOption

WithCredentials sets the output for the Retrieve method.

type MockIAM 

type MockIAM struct {
	IAMClient

	CreateAccessKeyOutput *iam.CreateAccessKeyOutput
	CreateAccessKeyError  error
	DeleteAccessKeyError  error
	ListAccessKeysOutput  *iam.ListAccessKeysOutput
	ListAccessKeysError   error
	GetUserOutput         *iam.GetUserOutput
	GetUserError          error
}

MockIAM provides a way to mock the AWS IAM API.

func (*MockIAM) CreateAccessKey 

func (m *MockIAM) CreateAccessKey(context.Context, *iam.CreateAccessKeyInput, ...func(*iam.Options)) (*iam.CreateAccessKeyOutput, error)

func (*MockIAM) DeleteAccessKey 

func (m *MockIAM) DeleteAccessKey(context.Context, *iam.DeleteAccessKeyInput, ...func(*iam.Options)) (*iam.DeleteAccessKeyOutput, error)

func (*MockIAM) GetUser 

func (m *MockIAM) GetUser(context.Context, *iam.GetUserInput, ...func(*iam.Options)) (*iam.GetUserOutput, error)

func (*MockIAM) ListAccessKeys 

func (m *MockIAM) ListAccessKeys(context.Context, *iam.ListAccessKeysInput, ...func(*iam.Options)) (*iam.ListAccessKeysOutput, error)

type MockIAMOption 

type MockIAMOption func(m *MockIAM) error

MockIAMOption is a function for setting the various fields on a MockIAM object.

func WithCreateAccessKeyError 

func WithCreateAccessKeyError(e error) MockIAMOption

WithCreateAccessKeyError sets the error output for the CreateAccessKey method.

func WithCreateAccessKeyOutput 

func WithCreateAccessKeyOutput(o *iam.CreateAccessKeyOutput) MockIAMOption

WithCreateAccessKeyOutput sets the output for the CreateAccessKey method.

func WithDeleteAccessKeyError 

func WithDeleteAccessKeyError(e error) MockIAMOption

WithDeleteAccessKeyError sets the error output for the DeleteAccessKey method.

func WithGetUserError 

func WithGetUserError(e error) MockIAMOption

WithGetUserError sets the error output for the GetUser method.

func WithGetUserOutput 

func WithGetUserOutput(o *iam.GetUserOutput) MockIAMOption

WithGetUserOutput sets the output for the GetUser method.

func WithListAccessKeysError 

func WithListAccessKeysError(e error) MockIAMOption

WithListAccessKeysError sets the error output for the ListAccessKeys method.

func WithListAccessKeysOutput 

func WithListAccessKeysOutput(o *iam.ListAccessKeysOutput) MockIAMOption

WithListAccessKeysOutput sets the output for the ListAccessKeys method.

type MockSTS 

type MockSTS struct {
	STSClient

	GetCallerIdentityOutput *sts.GetCallerIdentityOutput
	GetCallerIdentityError  error

	AssumeRoleOutput *sts.AssumeRoleOutput
	AssumeRoleError  error
}

MockSTS provides a way to mock the AWS STS API.

func (*MockSTS) AssumeRole 

func (m *MockSTS) AssumeRole(context.Context, *sts.AssumeRoleInput, ...func(*sts.Options)) (*sts.AssumeRoleOutput, error)

func (*MockSTS) GetCallerIdentity 

func (m *MockSTS) GetCallerIdentity(context.Context, *sts.GetCallerIdentityInput, ...func(*sts.Options)) (*sts.GetCallerIdentityOutput, error)

type MockSTSOption 

type MockSTSOption func(m *MockSTS) error

MockSTSOption is a function for setting the various fields on a MockSTS object.

func WithAssumeRoleError 

func WithAssumeRoleError(e error) MockSTSOption

WithAssumeRoleError sets the error output for the AssumeRole method.

func WithAssumeRoleOutput 

func WithAssumeRoleOutput(o *sts.AssumeRoleOutput) MockSTSOption

WithAssumeRoleOutput sets the output for the AssumeRole method.

func WithGetCallerIdentityError 

func WithGetCallerIdentityError(e error) MockSTSOption

WithGetCallerIdentityError sets the error output for the GetCallerIdentity method.

func WithGetCallerIdentityOutput 

func WithGetCallerIdentityOutput(o *sts.GetCallerIdentityOutput) MockSTSOption

WithGetCallerIdentityOutput sets the output for the GetCallerIdentity method.

type Option 

type Option func(*options) error

Option - how Options are passed as arguments

func MockOptionErr 

func MockOptionErr(withErr error) Option

MockOptionErr provides a mock option error for use with testing.

func WithAccessKey 

func WithAccessKey(with string) Option

WithAccessKey allows passing an access key to use for operations

func WithAwsConfig 

func WithAwsConfig(with *aws.Config) Option

WithAwsConfig allows controlling the configuration passed into the client

func WithCredentialsProvider 

func WithCredentialsProvider(with aws.CredentialsProvider) Option

WithCredentialsProvider allows passing in a CredentialsProvider interface constructor for mocking the AWS Credential Provider.

func WithHttpClient 

func WithHttpClient(with *http.Client) Option

WithHttpClient allows passing a custom client to use

func WithIAMAPIFunc 

func WithIAMAPIFunc(with IAMAPIFunc) Option

WithIAMAPIFunc allows passing in an IAM interface constructor for mocking the AWS IAM API.

func WithIamEndpointResolver 

func WithIamEndpointResolver(with iam.EndpointResolverV2) Option

WithIamEndppointResolver allows passing a custom IAM endpoint resolver

func WithLogger 

func WithLogger(with hclog.Logger) Option

WithLogger allows passing a logger to use

func WithMaxRetries 

func WithMaxRetries(with *int) Option

WithMaxRetries allows passing custom max retries to set

func WithRegion 

func WithRegion(with string) Option

WithRegion allows passing a custom region

func WithRoleArn 

func WithRoleArn(with string) Option

WithRoleArn allows passing a role arn to use when creating either a web identity role provider or a ec2-instance role provider.

func WithRoleExternalId 

func WithRoleExternalId(with string) Option

WithRoleExternalId allows passing a external id to use when creating a ec2-instance role provider. If not set, the role will be assumed in the same account. If set, the RoleARN must be set.

func WithRoleSessionName 

func WithRoleSessionName(with string) Option

WithRoleSessionName allows passing a session name to use when creating either a web identity role provider or a ec2-instance role provider. If set, the RoleARN must be set.

func WithRoleTags 

func WithRoleTags(with map[string]string) Option

WithRoleTags allows passing tags to use when creating a ec2-instance role provider. If set, the RoleARN must be set.

func WithSTSAPIFunc 

func WithSTSAPIFunc(with STSAPIFunc) Option

WithSTSAPIFunc allows passing in a STS interface constructor for mocking the AWS STS API.

func WithSecretKey 

func WithSecretKey(with string) Option

WithSecretKey allows passing a secret key to use for operations

func WithSharedCredentials 

func WithSharedCredentials(with bool) Option

WithSharedCredentials allows controlling whether shared credentials are used

func WithStsEndpointResolver 

func WithStsEndpointResolver(with sts.EndpointResolverV2) Option

WithStsEndpointResolver allows passing a custom STS endpoint resolver

func WithUsername 

func WithUsername(with string) Option

WithUsername allows passing the user name to use for an operation

func WithValidityCheckTimeout 

func WithValidityCheckTimeout(with time.Duration) Option

WithValidityCheckTimeout allows passing a timeout for operations that can wait on success.

func WithWebIdentityToken 

func WithWebIdentityToken(with string) Option

WithWebIdentityToken allows passing a web identity token to use for the assumed role. If set, the RoleARN must be set.

func WithWebIdentityTokenFile 

func WithWebIdentityTokenFile(with string) Option

WithWebIdentityTokenFile allows passing a web identity token file to use for the assumed role. If set, the RoleARN must be set.

type STSAPIFunc 

type STSAPIFunc func(awsConfig *aws.Config) (STSClient, error)

STSAPIFunc is a factory function for returning a STS interface, useful for supplying mock interfaces for testing STS.

func NewMockSTS 

func NewMockSTS(opts ...MockSTSOption) STSAPIFunc

NewMockSTS provides a factory function to use with the WithSTSAPIFunc option.

If withGetCallerIdentityError is supplied, calls to GetCallerIdentity will return the supplied error. Otherwise, a basic mock API output is returned.

type STSClient 

type STSClient interface {
	AssumeRole(context.Context, *sts.AssumeRoleInput, ...func(*sts.Options)) (*sts.AssumeRoleOutput, error)
	GetCallerIdentity(context.Context, *sts.GetCallerIdentityInput, ...func(*sts.Options)) (*sts.GetCallerIdentityOutput, error)
}

STSClient represents an sts.Client

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.