Package: plugincreds

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

Overview

Package plugincreds implements a credentials provider sourced from a Go plugin. This package allows you to use a Go plugin to retrieve AWS credentials for the SDK to use for service API calls.

As of Go 1.8 plugins are only supported on the Linux platform.

Plugin Symbol Name

The “GetAWSSDKCredentialProvider” is the symbol name that will be used to lookup the credentials provider getter from the plugin. If you want to use a custom symbol name you should use GetPluginProviderFnsByName to lookup the symbol by a custom name.

This symbol is a function that returns two additional functions. One to retrieve the credentials, and another to determine if the credentials have expired.

Plugin Symbol Signature

The plugin credential provider requires the symbol to match the following signature.

func() (RetrieveFn func() (key, secret, token string, err error), IsExpiredFn func() bool)

Plugin Implementation Example

The following is an example implementation of a SDK credential provider using the plugin provider in this package. See the SDK's example/aws/credential/plugincreds/plugin folder for a runnable example of this.

package main

func main() {}

var myCredProvider provider

// Build: go build -o plugin.so -buildmode=plugin plugin.go
func init() {
	// Initialize a mock credential provider with stubs
	myCredProvider = provider{"a","b","c"}
}

// GetAWSSDKCredentialProvider is the symbol SDK will lookup and use to
// get the credential provider's retrieve and isExpired functions.
func GetAWSSDKCredentialProvider() (func() (key, secret, token string, err error), func() bool) {
	return myCredProvider.Retrieve,	myCredProvider.IsExpired
}

// mock implementation of a type that returns retrieves credentials and
// returns if they have expired.
type provider struct {
	key, secret, token string
}

func (p provider) Retrieve() (key, secret, token string, err error) {
	return p.key, p.secret, p.token, nil
}

func (p *provider) IsExpired() bool {
	return false;
}

Configuring SDK for Plugin Credentials

To configure the SDK to use a plugin's credential provider you'll need to first open the plugin file using the plugin standard library package. Once you have a handle to the plugin you can use the NewCredentials function of this package to create a new credentials.Credentials value that can be set as the credentials loader of a Session or Config. See the SDK's example/aws/credential/plugincreds folder for a runnable example of this.

// Open plugin, and load it into the process.
p, err := plugin.Open("somefile.so")
if err != nil {
	return nil, err
}

// Create a new Credentials value which will source the provider's Retrieve
// and IsExpired functions from the plugin.
creds, err := plugincreds.NewCredentials(p)
if err != nil {
	return nil, err
}

// Example to configure a Session with the newly created credentials that
// will be sourced using the plugin's functionality.
sess := session.Must(session.NewSession(&aws.Config{
	Credentials:  creds,
}))

Constants

const ProviderSymbolName = readonly

ProviderSymbolName the symbol name the SDK will use to lookup the plugin provider value from.

Value:

`GetAWSSDKCredentialProvider`
const ProviderName = readonly

ProviderName is the name this credentials provider will label any returned credentials Value with.

Value:

`PluginCredentialsProvider`
const ErrCodeLookupSymbolError = readonly

ErrCodeLookupSymbolError failed to lookup symbol

Value:

"LookupSymbolError"
const ErrCodeInvalidSymbolError = readonly

ErrCodeInvalidSymbolError symbol invalid

Value:

"InvalidSymbolError"
const ErrCodePluginRetrieveNil = readonly

ErrCodePluginRetrieveNil Retrieve function was nil

Value:

"PluginRetrieveNilError"
const ErrCodePluginIsExpiredNil = readonly

ErrCodePluginIsExpiredNil IsExpired Function was nil

Value:

"PluginIsExpiredNilError"
const ErrCodePluginProviderRetrieve = readonly

ErrCodePluginProviderRetrieve plugin provider's retrieve returned error

Value:

"PluginProviderRetrieveError"

Type Summary collapse

Function Summary collapse

Function Details

func GetPluginProviderFns(p *plugin.Plugin) (func() (key, secret, token string, err error), func() bool, error)

GetPluginProviderFns returns the plugin's Retrieve and IsExpired functions returned by the plugin's credential provider getter.

Uses ProviderSymbolName as the symbol name when lookup up the symbol. If you want to use a different symbol name, use GetPluginProviderFnsByName.



179
180
181
 
// File 'aws/credentials/plugincreds/provider.go', line 179


func GetPluginProviderFns(p *plugin.Plugin) (func() (key, secret, token string, err error), func() bool, error) {
	return GetPluginProviderFnsByName(p, ProviderSymbolName)
}

func GetPluginProviderFnsByName(p *plugin.Plugin, symbolName string) (func() (key, secret, token string, err error), func() bool, error)

GetPluginProviderFnsByName returns the plugin's Retrieve and IsExpired functions returned by the plugin's credential provider getter.

Same as GetPluginProviderFns, but takes a custom symbolName to lookup with.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
// File 'aws/credentials/plugincreds/provider.go', line 187


func GetPluginProviderFnsByName(p *plugin.Plugin, symbolName string) (func() (key, secret, token string, err error), func() bool, error) {
	sym, err := p.Lookup(symbolName)
	if err != nil {
		return nil, nil, awserr.New(ErrCodeLookupSymbolError,
			fmt.Sprintf("failed to lookup %s plugin provider symbol", symbolName), err)
	}

	fn, ok := sym.(func() (func() (key, secret, token string, err error), func() bool))
	if !ok {
		return nil, nil, awserr.New(ErrCodeInvalidSymbolError,
			fmt.Sprintf("symbol %T, does not match the 'func() (func() (key, secret, token string, err error), func() bool)'  type", sym), nil)
	}

	retrieveFn, isExpiredFn := fn()
	if retrieveFn == nil {
		return nil, nil, awserr.New(ErrCodePluginRetrieveNil,
			"the plugin provider retrieve function cannot be nil", nil)
	}
	if isExpiredFn == nil {
		return nil, nil, awserr.New(ErrCodePluginIsExpiredNil,
			"the plugin provider isExpired function cannot be nil", nil)
	}

	return retrieveFn, isExpiredFn, nil
}

func NewCredentials(p *plugin.Plugin) (*credentials.Credentials, error)

NewCredentials returns a new Credentials loader using the plugin provider. If the symbol isn't found or is invalid in the plugin an error will be returned.



137
138
139
140
141
142
143
144
145
146
147
 
// File 'aws/credentials/plugincreds/provider.go', line 137


func NewCredentials(p *plugin.Plugin) (*credentials.Credentials, error) {
	retrieve, isExpired, err := GetPluginProviderFns(p)
	if err != nil {
		return nil, err
	}

	return credentials.NewCredentials(Provider{
		RetrieveFn:  retrieve,
		IsExpiredFn: isExpired,
	}), nil
}