package secrets
import "gocloud.dev/secrets"
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.
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 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 "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.
Code:play
Output: Code:play
Code:play
Output: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))
}
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())
}
}
}
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))
}
Go CDK Secrets
Index ¶
- Variables
- type Keeper
- func OpenKeeper(ctx context.Context, urlstr string) (*Keeper, error)
- func (k *Keeper) Close() error
- func (k *Keeper) Decrypt(ctx context.Context, ciphertext []byte) (plaintext []byte, err error)
- func (k *Keeper) Encrypt(ctx context.Context, plaintext []byte) (ciphertext []byte, err error)
- func (k *Keeper) ErrorAs(err error, i any) bool
- type KeeperURLOpener
- type URLMux
- func DefaultURLMux() *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 ¶
Variables ¶
var NewKeeper = newKeeper
NewKeeper is intended for use by drivers only. Do not use in application code.
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) )
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 ¶
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) Close ¶
Close releases any resources used for the Keeper.
func (*Keeper) Decrypt ¶
Decrypt decrypts the ciphertext and returns the plaintext.
Code:play
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
}
func (*Keeper) Encrypt ¶
Encrypt encrypts the plaintext and returns the cipher message.
Code:play
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
}
func (*Keeper) ErrorAs ¶
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 ¶
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 ¶
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 ¶
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 ¶
KeeperSchemes returns a sorted slice of the registered Keeper schemes.
func (*URLMux) OpenKeeper ¶
OpenKeeper calls OpenKeeperURL with the URL parsed from urlstr. OpenKeeper is safe to call from multiple goroutines.
func (*URLMux) OpenKeeperURL ¶
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 ¶
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 ¶
ValidKeeperScheme returns true iff scheme has been registered for Keepers.
Source Files ¶
secrets.go
Directories ¶
Path | Synopsis |
---|---|
secrets/awskms | Package awskms provides a secrets implementation backed by AWS KMS. |
secrets/azurekeyvault | Package azurekeyvault provides a secrets implementation backed by Azure KeyVault. |
secrets/driver | Package driver defines interfaces to be implemented by secrets drivers, which will be used by the secrets package to interact with the underlying services. |
secrets/drivertest | Package drivertest provides a conformance test for implementations of the secrets driver. |
secrets/gcpkms | Package gcpkms provides a secrets implementation backed by Google Cloud KMS. |
secrets/localsecrets | Package localsecrets provides a secrets implementation using a locally provided symmetric key. |
- Version
- v0.41.0
- Published
- Mar 30, 2025
- Platform
- js/wasm
- Imports
- 7 packages
- Last checked
- 2 hours ago –
Tools for package owners.