Documentation
¶
Overview ¶
Package secrets provides an easy and portable way to encrypt and decrypt messages. Subpackages contain driver implementations of secrets for supported services.
See https://gocloud.dev/howto/secrets/ for a detailed how-to guide.
Errors ¶
The errors returned from this package can be inspected in several ways:
The Code function from gocloud.dev/gcerrors will return an error code, also defined in that package, when invoked on an error. Alternatively, errors.Is can be used with the code-specific errors from the same package (e.g., ErrInternal).
The Keeper.ErrorAs method can retrieve the driver error underlying the returned error. Alternatively, errors.As can be used in the same way.
OpenTelemetry Integration ¶
OpenTelemetry supports tracing and metric collection for multiple languages and backend providers. See https://opentelemetry.io.
This API collects OpenTelemetry 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 driver, method and status (error code); and "latency", a distribution of method latency by driver and method. For example, "gocloud.dev/secrets/latency".
To enable trace collection in your application, see the OpenTelemetry documentation at https://opentelemetry.io/docs/instrumentation/go/getting-started/.
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.
sk, err := localsecrets.NewRandomKey()
if err != nil {
log.Fatal(err)
}
keeper := localsecrets.NewKeeper(sk)
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 (OpenFromURL) ¶
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 driver'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://smGbjm71Nxd1Ig5FS0wj9SlbzAIrnolCz9bQQ6uAhl4=")
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 drivers only. Do not use in application code.
var ( // OpenTelemetryViews are predefined views for OpenTelemetry metrics. // The views include counts and latency distributions for API method calls. // See the explanations at https://opentelemetry.io/docs/specs/otel/metrics/data-model/ for usage. OpenTelemetryViews = gcdkotel.Views(pkgName) )
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 driver subpackages.
func OpenKeeper ¶ added in v0.12.0
OpenKeeper opens the Keeper identified by the URL given. See the URLOpener documentation in driver subpackages for details on supported URL formats, and https://gocloud.dev/concepts/urls for more information.
func (*Keeper) Decrypt ¶
Decrypt decrypts the ciphertext and returns the plaintext.
Example ¶
package main
import (
"context"
"log"
"gocloud.dev/secrets"
_ "gocloud.dev/secrets/gcpkms"
)
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, hide lines until the next blank line.
ctx := context.Background()
var keeper *secrets.Keeper
var cipherText []byte // obtained from elsewhere and random-looking
plainText, err := keeper.Decrypt(ctx, cipherText)
if err != nil {
log.Fatal(err)
}
// PRAGMA: On gocloud.dev, hide the rest of the function.
_ = plainText
}
Output:
func (*Keeper) Encrypt ¶
Encrypt encrypts the plaintext and returns the cipher message.
Example ¶
package main
import (
"context"
"log"
"gocloud.dev/secrets"
_ "gocloud.dev/secrets/gcpkms"
)
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, hide lines until the next blank line.
ctx := context.Background()
var keeper *secrets.Keeper
plainText := []byte("Secrets secrets...")
cipherText, err := keeper.Encrypt(ctx, plainText)
if err != nil {
log.Fatal(err)
}
// PRAGMA: On gocloud.dev, hide the rest of the function.
_ = cipherText
}
Output:
func (*Keeper) ErrorAs ¶ added in v0.10.0
ErrorAs converts i to driver-specific types. See https://gocloud.dev/concepts/as/ for background information and the driver package documentation for the specific types supported for that driver.
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://gocloud.dev/concepts/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 by secrets drivers, which will be used by the secrets package to interact with the underlying services.
|
Package driver defines interfaces to be implemented by secrets drivers, which will be used by the secrets package to interact with the underlying services. |
|
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 provided symmetric key.
|
Package localsecrets provides a secrets implementation using a locally provided symmetric key. |
|
vault
module
|