Documentation
¶
Overview ¶
Package awskms provides a secrets implementation backed by AWS KMS. Use OpenKeeper to construct a *secrets.Keeper.
URLs ¶
For secrets.OpenKeeper, awskms registers for the scheme "awskms". The default URL opener will use an AWS session with the default credentials and configuration.
To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.
As ¶
awskms exposes the following type for As:
- Error: any error type returned by the service, notably smithy.APIError
Example (OpenFromURL) ¶
package main
import (
"context"
"log"
"gocloud.dev/secrets"
)
func main() {
// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/secrets/awskms"
// PRAGMA: On gocloud.dev, hide lines until the next blank line.
ctx := context.Background()
// Use one of the following:
// 1. By ID.
keeperByID, err := secrets.OpenKeeper(ctx,
"awskms://1234abcd-12ab-34cd-56ef-1234567890ab?region=us-east-1")
if err != nil {
log.Fatal(err)
}
defer keeperByID.Close()
// 2. By alias.
keeperByAlias, err := secrets.OpenKeeper(ctx,
"awskms://alias/ExampleAlias?region=us-east-1")
if err != nil {
log.Fatal(err)
}
defer keeperByAlias.Close()
// 3. By ARN. Note that ARN may contain ":" characters, which cannot be escaped
// in the Host part of a URL, so the "awskms:///<ARN>" form should be used.
const arn = "arn:aws:kms:us-east-1:111122223333:key/" +
"1234abcd-12ab-34bc-56ef-1234567890ab"
keeperByARN, err := secrets.OpenKeeper(ctx,
"awskms:///"+arn+"?region=us-east-1")
if err != nil {
log.Fatal(err)
}
defer keeperByARN.Close()
}
Output:
Index ¶
Examples ¶
Constants ¶
const Scheme = "awskms"
Scheme is the URL scheme awskms registers its URLOpener under on secrets.DefaultMux.
Variables ¶
var DialV2 = Dial
var OpenKeeperV2 = OpenKeeper
var Set = wire.NewSet( Dial, )
Set holds Wire providers for this package.
Functions ¶
func OpenKeeper ¶ added in v0.13.0
OpenKeeper returns a *secrets.Keeper that uses AWS KMS, using SDK v2. The key ID can be in the form of an Amazon Resource Name (ARN), alias name, or alias ARN. See https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn for more details. See the package documentation for an example.
Example ¶
package main
import (
"context"
"log"
"github.com/aws/aws-sdk-go-v2/config"
"gocloud.dev/secrets/awskms"
)
func main() {
// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
// Establish a AWS V2 Config.
// See https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/ for more info.
ctx := context.Background()
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
log.Fatal(err)
}
// Get a client to use with the KMS API.
client, err := awskms.Dial(cfg)
if err != nil {
log.Fatal(err)
}
// Construct a *secrets.Keeper.
keeper := awskms.OpenKeeper(client, "alias/test-secrets", nil)
defer keeper.Close()
}
Output:
Types ¶
type KeeperOptions ¶
type KeeperOptions struct {
// EncryptionContext parameters.
// See https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context.
EncryptionContext map[string]string
}
KeeperOptions controls Keeper behaviors. It is provided for future extensibility.
type URLOpener ¶ added in v0.12.0
type URLOpener struct {
// Options specifies the options to pass to OpenKeeper.
// EncryptionContext parameters from the URL are merged in.
Options KeeperOptions
}
URLOpener opens AWS KMS URLs like "awskms://keyID" or "awskms:///keyID".
The URL Host + Path are used as the key ID, which can be in the form of an Amazon Resource Name (ARN), alias name, or alias ARN. See https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn for more details. Note that ARNs may contain ":" characters, which cannot be escaped in the Host part of a URL, so the "awskms:///<ARN>" form should be used.
EncryptionContext key/value pairs can be provided by providing URL parameters prefixed with "context_"; e.g., "...&context_abc=foo&context_def=bar" would result in an EncryptionContext of {abc=foo, def=bar}. See https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context.
Source Files