Documentation
¶
Overview ¶
Package secrets provides an easy and portable way to encrypt and decrypt messages.
Subpackages contain distinct implementations of secrets for various providers, including Cloud and on-prem solutions. For example, "localsecrets" supports encryption/decryption using a locally provided key. Your application should import one of these provider-specific subpackages and use its exported function(s) to create a *Keeper; do not use the NewKeeper function in this package. For example:
keeper := localsecrets.NewKeeper(myKey)
encrypted, err := keeper.Encrypt(ctx.Background(), []byte("text"))
...
Then, write your application code using the *Keeper type. You can easily reconfigure your initialization code to choose a different provider. You can develop your application locally using localsecrets, or deploy it to multiple Cloud providers. You may find http://github.com/google/wire useful for managing your initialization code.
Alternatively, you can construct a *Keeper via a URL and OpenKeeper. See https://godoc.org/gocloud.dev#hdr-URLs for more information.
OpenCensus Integration ¶
OpenCensus supports tracing and metric collection for multiple languages and backend providers. See https://opencensus.io.
This API collects OpenCensus traces and metrics for the following methods:
- Encrypt
- Decrypt
All trace and metric names begin with the package import path. The traces add the method name. For example, "gocloud.dev/secrets/Encrypt". The metrics are "completed_calls", a count of completed method calls by provider, method and status (error code); and "latency", a distribution of method latency by provider and method. For example, "gocloud.dev/secrets/latency".
To enable trace collection in your application, see "Configure Exporter" at https://opencensus.io/quickstart/go/tracing. To enable metric collection in your application, see "Exporting stats" at https://opencensus.io/quickstart/go/metrics.
Example ¶
package main
import (
"context"
"fmt"
"log"
_ "gocloud.dev/secrets/gcpkms"
"gocloud.dev/secrets/localsecrets"
)
func main() {
ctx := context.Background()
// Construct a *secrets.Keeper from one of the secrets subpackages.
// This example uses localsecrets.
keeper := localsecrets.NewKeeper(localsecrets.ByteKey("secret key"))
defer keeper.Close()
// Now we can use keeper to Encrypt.
plaintext := []byte("Go CDK Secrets")
ciphertext, err := keeper.Encrypt(ctx, plaintext)
if err != nil {
log.Fatal(err)
}
// And/or Decrypt.
decrypted, err := keeper.Decrypt(ctx, ciphertext)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(decrypted))
}
Output: Go CDK Secrets
Example (ErrorAs) ¶
package main
import (
"context"
"fmt"
"log"
"gocloud.dev/secrets"
_ "gocloud.dev/secrets/gcpkms"
"google.golang.org/grpc/status"
)
func main() {
// This example is specific to the gcpkms implementation; it
// demonstrates access to the underlying google.golang.org/grpc/status.Status
// type.
// The types exposed for As by gcpkms are documented in
// https://godoc.org/gocloud.dev/secrets/gcpkms#hdr-As
ctx := context.Background()
const url = "gcpkms://projects/proj/locations/global/keyRings/test/ring/wrongkey"
keeper, err := secrets.OpenKeeper(ctx, url)
if err != nil {
log.Fatal(err)
}
defer keeper.Close()
plaintext := []byte("Go CDK secrets")
_, err = keeper.Encrypt(ctx, plaintext)
if err != nil {
var s *status.Status
if keeper.ErrorAs(err, &s) {
fmt.Println(s.Code())
}
}
}
Output:
Example (OpenKeeper) ¶
package main
import (
"context"
"fmt"
"log"
"gocloud.dev/secrets"
_ "gocloud.dev/secrets/localsecrets"
)
func main() {
ctx := context.Background()
// Create a Keeper using a URL.
// This example uses "localsecrets", the in-memory implementation.
// We need to add a blank import line to register the localsecrets provider's
// URLOpener, which implements secrets.KeeperURLOpener:
// import _ "gocloud.dev/secrets/localsecrets"
// localsecrets registers for the "base64key" scheme.
// All secrets.OpenKeeper URLs also work with "secrets+" or "secrets+keeper+" prefixes,
// e.g., "secrets+base64key://..." or "secrets+variable+base64key://...".
// All secrets URLs also work with the "secrets+" prefix, e.g., "secrets+base64key://".
k, err := secrets.OpenKeeper(ctx, "base64key://bXktc2VjcmV0LWtleQ==")
if err != nil {
log.Fatal(err)
}
defer k.Close()
// Now we can use k to encrypt/decrypt.
plaintext := []byte("Go CDK Secrets")
ciphertext, err := k.Encrypt(ctx, plaintext)
if err != nil {
log.Fatal(err)
}
decrypted, err := k.Decrypt(ctx, ciphertext)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(decrypted))
}
Output: Go CDK Secrets
Index ¶
- Variables
- type Keeper
- type KeeperURLOpener
- type URLMux
- func (mux *URLMux) KeeperSchemes() []string
- func (mux *URLMux) OpenKeeper(ctx context.Context, urlstr string) (*Keeper, error)
- func (mux *URLMux) OpenKeeperURL(ctx context.Context, u *url.URL) (*Keeper, error)
- func (mux *URLMux) RegisterKeeper(scheme string, opener KeeperURLOpener)
- func (mux *URLMux) ValidKeeperScheme(scheme string) bool
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var NewKeeper = newKeeper
NewKeeper is intended for use by provider implementations.
var ( // OpenCensusViews are predefined views for OpenCensus metrics. // The views include counts and latency distributions for API method calls. // See the example at https://godoc.org/go.opencensus.io/stats/view for usage. OpenCensusViews = oc.Views(pkgName, latencyMeasure) )
Functions ¶
This section is empty.
Types ¶
type Keeper ¶
type Keeper struct {
// contains filtered or unexported fields
}
Keeper does encryption and decryption. To create a Keeper, use constructors found in provider-specific subpackages.
func OpenKeeper ¶ added in v0.12.0
OpenKeeper opens the Keeper identified by the URL given. See the URLOpener documentation in provider-specific subpackages for details on supported URL formats, and https://godoc.org/gocloud.dev#hdr-URLs for more information.
func (*Keeper) ErrorAs ¶ added in v0.10.0
ErrorAs converts i to provider-specific types. See https://godoc.org/gocloud.dev#hdr-As for background information and the provider-specific package documentation for the specific types supported for that provider.
ErrorAs panics if i is nil or not a pointer. ErrorAs returns false if err == nil.
type KeeperURLOpener ¶ added in v0.12.0
KeeperURLOpener represents types that can open Keepers based on a URL. The opener must not modify the URL argument. OpenKeeperURL must be safe to call from multiple goroutines.
This interface is generally implemented by types in driver packages.
type URLMux ¶ added in v0.12.0
type URLMux struct {
// contains filtered or unexported fields
}
URLMux is a URL opener multiplexer. It matches the scheme of the URLs against a set of registered schemes and calls the opener that matches the URL's scheme. See https://godoc.org/gocloud.dev#hdr-URLs for more information.
The zero value is a multiplexer with no registered schemes.
func DefaultURLMux ¶ added in v0.12.0
func DefaultURLMux() *URLMux
DefaultURLMux returns the URLMux used by OpenKeeper.
Driver packages can use this to register their KeeperURLOpener on the mux.
func (*URLMux) KeeperSchemes ¶ added in v0.13.0
KeeperSchemes returns a sorted slice of the registered Keeper schemes.
func (*URLMux) OpenKeeper ¶ added in v0.12.0
OpenKeeper calls OpenKeeperURL with the URL parsed from urlstr. OpenKeeper is safe to call from multiple goroutines.
func (*URLMux) OpenKeeperURL ¶ added in v0.12.0
OpenKeeperURL dispatches the URL to the opener that is registered with the URL's scheme. OpenKeeperURL is safe to call from multiple goroutines.
func (*URLMux) RegisterKeeper ¶ added in v0.12.0
func (mux *URLMux) RegisterKeeper(scheme string, opener KeeperURLOpener)
RegisterKeeper registers the opener with the given scheme. If an opener already exists for the scheme, RegisterKeeper panics.
func (*URLMux) ValidKeeperScheme ¶ added in v0.13.0
ValidKeeperScheme returns true iff scheme has been registered for Keepers.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package awskms provides a secrets implementation backed by AWS KMS.
|
Package awskms provides a secrets implementation backed by AWS KMS. |
|
Package azurekeyvault provides a secrets implementation backed by Azure KeyVault.
|
Package azurekeyvault provides a secrets implementation backed by Azure KeyVault. |
|
Package driver defines interfaces to be implemented for providers of the secrets package.
|
Package driver defines interfaces to be implemented for providers of the secrets package. |
|
Package drivertest provides a conformance test for implementations of the secrets driver.
|
Package drivertest provides a conformance test for implementations of the secrets driver. |
|
Package gcpkms provides a secrets implementation backed by Google Cloud KMS.
|
Package gcpkms provides a secrets implementation backed by Google Cloud KMS. |
|
hashivault
module
|
|
|
Package localsecrets provides a secrets implementation using a locally locally provided symmetric key.
|
Package localsecrets provides a secrets implementation using a locally locally provided symmetric key. |
|
Package vault provides a secrets implementation using the Transit Secrets Engine of Vault by Hashicorp.
|
Package vault provides a secrets implementation using the Transit Secrets Engine of Vault by Hashicorp. |