126 lines
5.6 KiB
Go
126 lines
5.6 KiB
Go
// Copyright (c) HashiCorp, Inc.
|
|
// SPDX-License-Identifier: MPL-2.0
|
|
|
|
package logical
|
|
|
|
import (
|
|
"context"
|
|
"crypto"
|
|
"io"
|
|
|
|
wrapping "github.com/hashicorp/go-kms-wrapping/v2"
|
|
)
|
|
|
|
type KeyUsage int
|
|
|
|
const (
|
|
KeyUsageEncrypt KeyUsage = 1 + iota
|
|
KeyUsageDecrypt
|
|
KeyUsageSign
|
|
KeyUsageVerify
|
|
KeyUsageWrap
|
|
KeyUsageUnwrap
|
|
KeyUsageGenerateRandom
|
|
)
|
|
|
|
type ManagedKey interface {
|
|
// Name is a human-readable identifier for a managed key that may change/renamed. Use Uuid if a
|
|
// long term consistent identifier is needed.
|
|
Name() string
|
|
// UUID is a unique identifier for a managed key that is guaranteed to remain
|
|
// consistent even if a key is migrated or renamed.
|
|
UUID() string
|
|
// Present returns true if the key is established in the KMS. This may return false if for example
|
|
// an HSM library is not configured on all cluster nodes.
|
|
Present(ctx context.Context) (bool, error)
|
|
|
|
// AllowsAll returns true if all the requested usages are supported by the managed key.
|
|
AllowsAll(usages []KeyUsage) bool
|
|
}
|
|
|
|
type (
|
|
ManagedKeyConsumer func(context.Context, ManagedKey) error
|
|
ManagedSigningKeyConsumer func(context.Context, ManagedSigningKey) error
|
|
ManagedEncryptingKeyConsumer func(context.Context, ManagedEncryptingKey) error
|
|
ManagedMACKeyConsumer func(context.Context, ManagedMACKey) error
|
|
ManagedKeyRandomSourceConsumer func(context.Context, ManagedKeyRandomSource) error
|
|
)
|
|
|
|
type ManagedKeySystemView interface {
|
|
// WithManagedKeyByName retrieves an instantiated managed key for consumption by the given function. The
|
|
// provided key can only be used within the scope of that function call
|
|
WithManagedKeyByName(ctx context.Context, keyName, backendUUID string, f ManagedKeyConsumer) error
|
|
// WithManagedKeyByUUID retrieves an instantiated managed key for consumption by the given function. The
|
|
// provided key can only be used within the scope of that function call
|
|
WithManagedKeyByUUID(ctx context.Context, keyUuid, backendUUID string, f ManagedKeyConsumer) error
|
|
|
|
// WithManagedSigningKeyByName retrieves an instantiated managed signing key for consumption by the given function,
|
|
// with the same semantics as WithManagedKeyByName
|
|
WithManagedSigningKeyByName(ctx context.Context, keyName, backendUUID string, f ManagedSigningKeyConsumer) error
|
|
// WithManagedSigningKeyByUUID retrieves an instantiated managed signing key for consumption by the given function,
|
|
// with the same semantics as WithManagedKeyByUUID
|
|
WithManagedSigningKeyByUUID(ctx context.Context, keyUuid, backendUUID string, f ManagedSigningKeyConsumer) error
|
|
// WithManagedSigningKeyByName retrieves an instantiated managed signing key for consumption by the given function,
|
|
// with the same semantics as WithManagedKeyByName
|
|
WithManagedEncryptingKeyByName(ctx context.Context, keyName, backendUUID string, f ManagedEncryptingKeyConsumer) error
|
|
// WithManagedSigningKeyByUUID retrieves an instantiated managed signing key for consumption by the given function,
|
|
// with the same semantics as WithManagedKeyByUUID
|
|
WithManagedEncryptingKeyByUUID(ctx context.Context, keyUuid, backendUUID string, f ManagedEncryptingKeyConsumer) error
|
|
// WithManagedMACKeyByName retrieves an instantiated managed MAC key by name for consumption by the given function,
|
|
// with the same semantics as WithManagedKeyByName.
|
|
WithManagedMACKeyByName(ctx context.Context, keyName, backendUUID string, f ManagedMACKeyConsumer) error
|
|
// WithManagedMACKeyByUUID retrieves an instantiated managed MAC key by UUID for consumption by the given function,
|
|
// with the same semantics as WithManagedKeyByUUID.
|
|
WithManagedMACKeyByUUID(ctx context.Context, keyUUID, backendUUID string, f ManagedMACKeyConsumer) error
|
|
}
|
|
|
|
type ManagedAsymmetricKey interface {
|
|
ManagedKey
|
|
GetPublicKey(ctx context.Context) (crypto.PublicKey, error)
|
|
}
|
|
|
|
type ManagedKeyLifecycle interface {
|
|
// GenerateKey generates a key in the KMS if it didn't yet exist, returning the id.
|
|
// If it already existed, returns the existing id. KMSKey's key material is ignored if present.
|
|
GenerateKey(ctx context.Context) (string, error)
|
|
}
|
|
|
|
type ManagedSigningKey interface {
|
|
ManagedAsymmetricKey
|
|
|
|
// Sign returns a digital signature of the provided value. The SignerOpts param must provide the hash function
|
|
// that generated the value (if any).
|
|
// The optional randomSource specifies the source of random values and may be ignored by the implementation
|
|
// (such as on HSMs with their own internal RNG)
|
|
Sign(ctx context.Context, value []byte, randomSource io.Reader, opts crypto.SignerOpts) ([]byte, error)
|
|
|
|
// Verify verifies the provided signature against the value. The SignerOpts param must provide the hash function
|
|
// that generated the value (if any).
|
|
// If true is returned the signature is correct, false otherwise.
|
|
Verify(ctx context.Context, signature, value []byte, opts crypto.SignerOpts) (bool, error)
|
|
|
|
// GetSigner returns an implementation of crypto.Signer backed by the managed key. This should be called
|
|
// as needed so as to use per request contexts.
|
|
GetSigner(context.Context) (crypto.Signer, error)
|
|
}
|
|
|
|
type ManagedEncryptingKey interface {
|
|
ManagedKey
|
|
Encrypt(ctx context.Context, plaintext []byte, options ...wrapping.Option) ([]byte, error)
|
|
Decrypt(ctx context.Context, ciphertext []byte, options ...wrapping.Option) ([]byte, error)
|
|
}
|
|
|
|
type ManagedMACKey interface {
|
|
ManagedKey
|
|
|
|
// MAC generates a MAC tag using the provided algorithm for the provided value.
|
|
MAC(ctx context.Context, algorithm string, data []byte) ([]byte, error)
|
|
}
|
|
|
|
type ManagedKeyRandomSource interface {
|
|
ManagedKey
|
|
|
|
// GetRandomBytes returns a number (specified by the count parameter) of random bytes sourced from the target managed key.
|
|
GetRandomBytes(count int) ([]byte, error)
|
|
}
|