kms

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2024 License: AGPL-3.0 Imports: 35 Imported by: 0

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrPermission is returned when the client has insufficient permissions
	// for performing the tried operation. For example, policy associated to the
	// client's identity may not allow or even deny the request or the client
	// may try to perform an admin operation without admin permissions.
	ErrPermission = Error{http.StatusForbidden, "access denied: insufficient permissions"}

	// ErrEnclaveExists is returned when trying to create an enclave
	// that already exists.
	ErrEnclaveExists = Error{http.StatusConflict, "enclave already exists"}

	// ErrEnclaveNotFound is returned when trying to operate within
	// an enclave that does not exist. For example, when trying to
	// create a key in a non-existing enclave.
	ErrEnclaveNotFound = Error{http.StatusNotFound, "enclave does not exist"}

	// ErrKeyExists is returned when trying to create a key in an
	// enclave that already contains a key with the same name.
	ErrKeyExists = Error{http.StatusConflict, "key already exists"}

	// ErrKeyNotFound is returned when trying to use a key that
	// that does not exist.
	ErrKeyNotFound = Error{http.StatusNotFound, "key does not exist"}

	// ErrPolicyNotFound is returned when trying to fetch or delete a policy
	// that does not exist.
	ErrPolicyNotFound = Error{http.StatusNotFound, "policy does not exist"}

	// ErrIdentityNotFound is returned when trying to access or delete a identity
	// that does not exist.
	ErrIdentityNotFound = Error{http.StatusNotFound, "identity does not exist"}

	// ErrDecrypt is returned when trying to decrypt an invalid or modified
	// ciphertext or when the wrong key is used for decryption.
	ErrDecrypt = Error{http.StatusBadRequest, "invalid ciphertext"}
)

MinIO KMS API errors.

Functions

This section is empty.

Types

type APIKey 

type APIKey interface {
	// Public returns the API key's public key.
	Public() crypto.PublicKey

	// Private returns the API key's private key.
	Private() crypto.PrivateKey

	// Identity returns the Identity associated with the
	// public key.
	Identity() Identity

	// String returns the API key's string representation.
	String() string
}

An APIKey represents a public/private key pair. An API key can be used to authenticate to a TLS server via mTLS¹ by generating a X.509 certificate from the API key's public key.

Ref: [1] https://en.wikipedia.org/wiki/Mutual_authentication#mTLS

func GenerateAPIKey 

func GenerateAPIKey(random io.Reader) (APIKey, error)

GenerateAPIKey generates a new API key using the given io.Reader as source of randomness.

If random is nil, the standard library crypto/rand.Reader is used.

func ParseAPIKey 

func ParseAPIKey(s string) (APIKey, error)

ParseAPIKey parses s as formatted API key.

Example 
package main

import (
	"fmt"
	"log"

	"github.com/minio/kms-go/kms"
)

func main() {
	key, err := kms.ParseAPIKey("k1:d7cY_5k8HbBGkZpoy2hGmvkxg83QDBXsA_nFXDfTk2E")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(key)
}

Output:

k1:d7cY_5k8HbBGkZpoy2hGmvkxg83QDBXsA_nFXDfTk2E

type AddClusterNodeRequest added in v0.4.0 

type AddClusterNodeRequest struct {
	// Host is the KMS server that should join a cluster.
	// It must be of the form "host" or "host:port".
	Host string
}

AddClusterNodeRequest describes which KMS server to add to an existing.

func (*AddClusterNodeRequest) MarshalPB added in v0.4.0 

func (r *AddClusterNodeRequest) MarshalPB(v *pb.AddClusterNodeRequest) error

MarshalPB converts the AddClusterNodeRequest into its protobuf representation.

func (*AddClusterNodeRequest) UnmarshalPB added in v0.4.0 

func (r *AddClusterNodeRequest) UnmarshalPB(v *pb.AddClusterNodeRequest) error

UnmarshalPB initializes the AddClusterNodeRequest from its protobuf representation.

type AssignPolicyRequest added in v0.3.0 

type AssignPolicyRequest struct {
	// Enclave is the KMS enclave containing the policy and identity.
	Enclave string

	// Policy is the name of the policy that gets assigned to the identity.
	Policy string

	// Identity is the identity to which the policy should apply.
	Identity Identity
}

AssignPolicyRequest contains options for assigning a policy to an identity.

func (*AssignPolicyRequest) MarshalPB added in v0.3.0 

func (r *AssignPolicyRequest) MarshalPB(v *pb.AssignPolicyRequest) error

MarshalPB converts the AssignPolicyRequest into its protobuf representation.

func (*AssignPolicyRequest) UnmarshalPB added in v0.3.0 

func (r *AssignPolicyRequest) UnmarshalPB(v *pb.AssignPolicyRequest) error

UnmarshalPB initializes the AssignPolicyRequest from its protobuf representation.

type BackupDBRequest added in v0.4.0 

type BackupDBRequest struct{}

BackupDBRequest contains options for requesting a database backup from a KMS server.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a KMS client. It performs client-side load balancing across all its KMS cluster node endpoints.

func NewClient 

func NewClient(conf *Config) (*Client, error)

NewClient returns a new Client with the given configuration.

func (*Client) AddNode added in v0.2.0 

func (c *Client) AddNode(ctx context.Context, req *AddClusterNodeRequest) error

AddNode adds the KMS server at req.Host to the current KMS cluster. It returns an error if the server is already part of the cluster.

Nodes can only join a cluster if the cluster has a leader. The KMS server at req.Host must be fresh in the sense that it must not be part of a multi-node cluster already.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) AssignPolicy added in v0.3.0 

func (c *Client) AssignPolicy(ctx context.Context, req *AssignPolicyRequest) error

AssignPolicy assigns the req.Policy within req.Enclave to the req.Identity. Both, the policy and identity, must reside within the same enclave.

It returns ErrEnclaveNotFound if no such enclave exists, ErrPolicyNotFound if no such policy exists and ErrIdentityNotFound if no such identity exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) ClusterStatus added in v0.2.0 

func (c *Client) ClusterStatus(ctx context.Context, _ *ClusterStatusRequest) (*ClusterStatusResponse, error)

ClusterStatus returns status information about the entire KMS cluster. The returned ClusterStatusResponse contains status information for all nodes within the cluster. It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) CreateEnclave added in v0.2.0 

func (c *Client) CreateEnclave(ctx context.Context, req *CreateEnclaveRequest) error

CreateEnclave creates a new enclave with the name req.Name.

It returns ErrEnclaveExists if such an enclave already exists wrapped in HostError.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) CreateIdentity added in v0.3.0 

func (c *Client) CreateIdentity(ctx context.Context, req *CreateIdentityRequest) error

CreateIdentity creates a new or overwrites an exisiting identity with the name req.Identity within req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) CreateKey added in v0.2.0 

func (c *Client) CreateKey(ctx context.Context, req *CreateKeyRequest) error

CreateKey creates a new key with the name req.Name within req.Enclave. By default, a new key is created if and only if no such key exists. If req.AddVersion is true, a new key version is added to an existing key. The later is often referred to as key rotation.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyExists if such a key already exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) CreatePolicy added in v0.3.0 

func (c *Client) CreatePolicy(ctx context.Context, req *CreatePolicyRequest) error

CreatePolicy creates a new or overwrites an exisiting policy with the name req.Name within req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) Decrypt 

func (c *Client) Decrypt(ctx context.Context, req *DecryptRequest) (*DecryptResponse, error)

Decrypt decrypts the req.Ciphertext with the key req.Name within the req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyNotFound if no such key exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) DeleteEnclave added in v0.2.0 

func (c *Client) DeleteEnclave(ctx context.Context, req *DeleteEnclaveRequest) error

DeleteEnclave deletes the enclave with the name req.Name.

It returns ErrEnclaveNotFound if no such enclave exists wrapped in a HostError.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) DeleteIdentity added in v0.3.0 

func (c *Client) DeleteIdentity(ctx context.Context, req *DeleteIdentityRequest) error

DeleteIdentity deletes the identity with the name req.Identity within req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrIdentityNotFound if such identity exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) DeleteKey added in v0.3.0 

func (c *Client) DeleteKey(ctx context.Context, req *DeleteKeyRequest) error

DeleteKey deletes the key with the version req.Version from the key ring with the name req.Name within req.Enclave. It deletes the latest key version if no key version is specified and the entire key and all versions if req.AllVersions is true.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyNotFound if such key or key version exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) DeletePolicy added in v0.3.0 

func (c *Client) DeletePolicy(ctx context.Context, req *DeletePolicyRequest) error

DeletePolicy deletes the policy with the name req.Name within req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrPolicyNotFound if such policy exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) DescribeEnclave added in v0.2.0 

func (c *Client) DescribeEnclave(ctx context.Context, req *EnclaveStatusRequest) (*EnclaveStatusResponse, error)

DescribeEnclave returns metadata about the enclave with the the name req.Name.

It returns ErrEnclaveNotFound if no such enclave exists wrapped in a HostError.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) DescribeKeyVersion added in v0.2.0 

func (c *Client) DescribeKeyVersion(ctx context.Context, req *KeyStatusRequest) (*KeyStatusResponse, error)

DescribeKeyVersion returns metadata about the key req.Name within the req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyNotFound if no such key exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) DescribePolicy added in v0.3.0 

func (c *Client) DescribePolicy(ctx context.Context, req *PolicyRequest) (*PolicyStatusResponse, error)

DescribePolicy returns metadata about the policy req.Name within the req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrPolicyNotFound if no such policy exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) EditCluster added in v0.3.0 

func (c *Client) EditCluster(ctx context.Context, req *EditClusterRequest) error

EditCluster edits the cluster definition of the KMS server req.Host. If req.Host is empty, the first host of the client's host list is used.

Usually, editing the cluster definition directly is only ever necessary when repairing a cluster that has lost some nodes permanently. Hence, applications should only edit the cluster definition of one particular KMS server node and only when some cluster nodes are permanently unavailable.

The client does not retry the request in case of a network error. Applications should make sure that the server node is available before editing its cluster definition. Refer to ServerStatus or ClusterStatus.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) Encrypt 

func (c *Client) Encrypt(ctx context.Context, req *EncryptRequest) (*EncryptResponse, error)

Encrypt encrypts the req.Plaintext with the key req.Name within the req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyNotFound if no such key exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) GenerateKey 

func (c *Client) GenerateKey(ctx context.Context, req *GenerateKeyRequest) (*GenerateKeyResponse, error)

GenerateKey generates a new unique data encryption key. The returned GenerateKeyResponse contains a plaintext data encryption key with the requested length and a ciphertext version. The ciphertext is the plaintext data encryption key encrypted with the key within the given enclave.

Applications should use, but never store, the plaintext data encryption key for cryptographic operations and remember the ciphertext version of the data encryption key. For example, encrypt a file with the plaintext data encryption key and store the ciphertext version of data encryption key alongside the encrypted file. The plaintext data encryption key can be obtained by decrypting the ciphertext data encryption key using Decrypt.

Applications should also persist the key version that is used to prepare for future key rotation.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyNotFound if no such key exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) GetIdentity added in v0.4.0 

func (c *Client) GetIdentity(ctx context.Context, req *IdentityRequest) (*IdentityResponse, error)

GetIdentity returns identity req.Identity within the req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrIdentityNotFound if no such identity exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) GetPolicy added in v0.3.0 

func (c *Client) GetPolicy(ctx context.Context, req *PolicyRequest) (*PolicyResponse, error)

GetPolicy fetches the policy req.Name within the req.Enclave.

It returns ErrEnclaveNotFound if no such enclave exists and ErrPolicyNotFound if no such policy exists wrapped in a HostError. The returned error is of type *HostError.

func (*Client) Hosts added in v0.4.0 

func (c *Client) Hosts() []string

Hosts returns a list of KMS servers currently used by client.

func (*Client) ImportKey added in v0.4.0 

func (c *Client) ImportKey(ctx context.Context, req *ImportKeyRequest) error

ImportKey imports an existing key with the name req.Name into req.Enclave. By default, a new key is created if and only if no such key exists. If req.AddVersion is true, a new key version is added to an existing key. The later is often referred to as key rotation.

Keys that imported are marked by the KMS server to distinguish them from keys that never left the KMS boundary.

It returns ErrEnclaveNotFound if no such enclave exists and ErrKeyExists if such a key already exists wrapped in a HostError.

The returned error is of type *HostError.

func (*Client) ListEnclaves added in v0.3.0 

func (c *Client) ListEnclaves(ctx context.Context, req *ListRequest) (*Page[EnclaveStatusResponse], error)

ListEnclaves returns the next page of a paginated listing of enclaves. All enclave names start with the req.Prefix and the first enclave name matches req.ContinueAt. The page contains at most req.Limit enclaves.

ListEnclaves implements paginated listing. For iterating over a stream of enclaves combine it with an Iter.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) ListIdentities added in v0.3.0 

func (c *Client) ListIdentities(ctx context.Context, req *ListRequest) (*Page[IdentityResponse], error)

ListIdentities returns the next page of a paginated listing of identites. All identities start with the req.Prefix and the first identity matches req.ContinueAt. The page contains at most req.Limit identities.

ListIdentities implements paginated listing. For iterating over a stream of identities combine it with an Iter.

The returned error is of type *HostError.

func (*Client) ListKeys added in v0.3.0 

func (c *Client) ListKeys(ctx context.Context, req *ListRequest) (*Page[KeyStatusResponse], error)

ListKeys returns the next page of a paginated listing of secret keys. All key names start with the req.Prefix and the first key name matches req.ContinueAt. The page contains at most req.Limit keys.

ListKeys implements paginated listing. For iterating over a stream of keys combine it with an Iter.

The returned error is of type *HostError.

func (*Client) ListPolicies added in v0.3.0 

func (c *Client) ListPolicies(ctx context.Context, req *ListRequest) (*Page[PolicyStatusResponse], error)

ListPolicies returns the next page of a paginated listing of policies. All policy names start with the req.Prefix and the first policy name matches req.ContinueAt. The page contains at most req.Limit policies.

ListPolicies implements paginated listing. For iterating over a stream of policies combine it with an Iter.

The returned error is of type *HostError.

func (*Client) Live added in v0.4.0 

func (c *Client) Live(ctx context.Context, req *LivenessRequest) error

Live reports whether one or multiple KMS servers are alive. If req.Hosts is empty, the Client checks the liveness of all hosts.

The liveness probe just reports whether the KMS servers are listening and responding to requests at all. It does not report whether the servers are ready to handle requests. Use the Ready method for checking the servers ability to handle read or write requests.

For a single host, Live returns a nil error if the host is alive or a HostError wrapping the encountered error.

For multiple hosts, Live only returns a nil error if all hosts are alive. If some nodes are not alive, it returns a joined error that implements the "Unwrap() []error" interface. Each of these errors are of type HostError.

func (*Client) ReadDB added in v0.4.0 

func (c *Client) ReadDB(ctx context.Context) (*ReadDBResponse, error)

ReadDB returns a snapshot of current KMS server database. The returned ReadDBResponse must be closed by the caller.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) Ready added in v0.4.0 

func (c *Client) Ready(ctx context.Context, req *ReadinessRequest) error

Ready reports whether one or multiple KMS servers are ready to serve requests. If req.Hosts is empty, the Client checks the readiness of all hosts.

By default, the readiness probe reports whether the servers are ready to serve "read" requests. Most KMS API operations, including en/decryption, signing or data key generation, are considered read requests. For checking the readiness for handling write requests, like key creation or deletion, set req.Write to true.

For a single host, Ready returns a nil error if the host is ready to serve requests or a HostError wrapping the encountered error.

For multiple hosts, Ready only returns a nil error if all hosts are ready. If some nodes are not ready, it returns a joined error that implements the "Unwrap() []error" interface. Each of these errors are of type HostError.

func (*Client) RemoveNode added in v0.2.0 

func (c *Client) RemoveNode(ctx context.Context, req *RemoveClusterNodeRequest) error

RemoveNode removes the KMS server at req.Host from the current KMS cluster. It returns an error if the server is not part of the cluster.

It requires SysAdmin privileges.

The returned error is of type *HostError.

func (*Client) Send added in v0.4.0 

func (c *Client) Send(ctx context.Context, req *Request) (*http.Response, error)

Send executes a KMS request, returning a Response for the provided Request.

If req.Host is empty, the Client selects the KMS server automatically and retries failed requests on other KMS servers, if available. When this behavior is not desirable, for example when trying to communicate with one particular KMS server, req.Host should be set to the server host or host:port.

Send is a low-level API. Most callers should use higher-level functionality, like creating a key using CreateKey.

The returned error is of type *HostError.

func (*Client) Version added in v0.4.0 

func (c *Client) Version(ctx context.Context, req *VersionRequest) ([]*VersionResponse, error)

Version returns version information from one or multiple KMS servers. If req.Hosts is empty, the Client tries to fetch version information from all its hosts.

For a single host, Version returns its version information and a HostError wrapping the first error encountered, if any.

For multiple hosts, Version returns a list of version responses. If it fails to fetch version information from some hosts, it returns a joined error that implements the "Unwrap() []error" interface. Each of these errors are of type HostError.

type ClusterStatusRequest added in v0.4.0 

type ClusterStatusRequest struct{}

ClusterStatusRequest contains options for fetching KMS cluster status information.

func (*ClusterStatusRequest) MarshalPB added in v0.4.0 

func (r *ClusterStatusRequest) MarshalPB(*pb.ClusterStatusRequest) error

MarshalPB converts the ClusterStatusRequest into its protobuf representation.

func (*ClusterStatusRequest) UnmarshalPB added in v0.4.0 

func (r *ClusterStatusRequest) UnmarshalPB(*pb.ClusterStatusRequest) error

UnmarshalPB initializes the ClusterStatusRequest from its protobuf representation.

type ClusterStatusResponse added in v0.2.0 

type ClusterStatusResponse struct {
	// NodesUp is a map of node IDs to the corresponding node status
	// information.
	NodesUp map[int]*ServerStatusResponse

	// NodesDown is a map of node IDs to node addresses containing
	// all nodes that were not reachable or failed to respond in time.
	NodesDown map[int]string
}

ClusterStatusResponse contains status information about a KMS cluster.

The overall view of the current cluster status, in particular which nodes are reachable, may vary from node to node in case of network partitions. For example, two nodes within two network partitions will consider themselves as up and their peer as down.

func (*ClusterStatusResponse) MarshalPB added in v0.2.0 

func (s *ClusterStatusResponse) MarshalPB(v *pb.ClusterStatusResponse) error

MarshalPB converts the ClusterStatusResponse into its protobuf representation.

func (*ClusterStatusResponse) UnmarshalPB added in v0.2.0 

func (s *ClusterStatusResponse) UnmarshalPB(v *pb.ClusterStatusResponse) error

UnmarshalPB initializes the ClusterStatusResponse from its protobuf representation.

type Config 

type Config struct {
	// List of KMS cluster node endpoints. The Client
	// tries to distribute requests uniformly across
	// all endpoints.
	Endpoints []string

	// APIKey to authenticate to the KMS cluster.
	//
	// When providing an API key, no TLS.Certificates
	// or TLS.GetClientCertificate must be present.
	APIKey APIKey

	// Optional TLS configuration.
	//
	// If no API key is set, either a TLS.Certificates
	// or TLS.GetClientCertificate must be present.
	TLS *tls.Config
}

Config is a structure containing configuration options for KMS clients.

type CreateEnclaveRequest added in v0.2.0 

type CreateEnclaveRequest struct {
	// Name is the name of the enclave to create.
	Name string
}

CreateEnclaveRequest contains options for creating enclaves.

func (*CreateEnclaveRequest) MarshalPB added in v0.4.0 

func (r *CreateEnclaveRequest) MarshalPB(v *pb.CreateEnclaveRequest) error

MarshalPB converts the CreateEnclaveRequest into its protobuf representation.

func (*CreateEnclaveRequest) UnmarshalPB added in v0.4.0 

func (r *CreateEnclaveRequest) UnmarshalPB(v *pb.CreateEnclaveRequest) error

UnmarshalPB initializes the CreateEnclaveRequest from its protobuf representation.

type CreateIdentityRequest added in v0.3.0 

type CreateIdentityRequest struct {
	// Enclave is the KMS enclave in which the identity is created.
	Enclave string

	// Identity is the identity that is created.
	Identity Identity

	// Privilege is the identity's privilege. If empty, defaults to User.
	Privilege Privilege

	// IsServiceAccount indicates whether this identity is a service
	// account.
	IsServiceAccount bool
}

CreateIdentityRequest contains options for creating new identities.

func (*CreateIdentityRequest) MarshalPB added in v0.3.0 

func (r *CreateIdentityRequest) MarshalPB(v *pb.CreateIdentityRequest) error

MarshalPB converts the CreateIdentityequest into its protobuf representation.

func (*CreateIdentityRequest) UnmarshalPB added in v0.3.0 

func (r *CreateIdentityRequest) UnmarshalPB(v *pb.CreateIdentityRequest) error

UnmarshalPB initializes the CreateIdentityRequest from its protobuf representation.

type CreateKeyRequest added in v0.2.0 

type CreateKeyRequest struct {
	// Enclave is the KMS enclave in which the key is created.
	Enclave string

	// Name is the name of the key to create.
	Name string

	// Type of the key that is created. For example, AES256.
	// If not set, the server will pick a key type.
	Type SecretKeyType

	// AddVersion indicates whether a new key version is created.
	// By default, trying to create a key that already exists fails.
	// If AddVersion is true, a new key version is created.
	//
	// Adding versions to an existing key is often referred to as
	// key rotation.
	AddVersion bool
}

CreateKeyRequest contains options for creating secret keys.

func (*CreateKeyRequest) MarshalPB added in v0.2.0 

func (r *CreateKeyRequest) MarshalPB(v *pb.CreateKeyRequest) error

MarshalPB converts the CreateKeyRequest into its protobuf representation.

func (*CreateKeyRequest) UnmarshalPB added in v0.2.0 

func (r *CreateKeyRequest) UnmarshalPB(v *pb.CreateKeyRequest) error

UnmarshalPB initializes the CreateKeyRequest from its protobuf representation.

type CreatePolicyRequest added in v0.3.0 

type CreatePolicyRequest struct {
	// Enclave is the KMS enclave in which the policy is created.
	Enclave string

	// Name is the name of the policy that is created.
	Name string

	// Allow is a set of allow rules.
	Allow map[cmds.Command]RuleSet

	// Deny is a set of deny rules.
	Deny map[cmds.Command]RuleSet
}

CreatePolicyRequest contains options for creating policies.

func (*CreatePolicyRequest) MarshalPB added in v0.3.0 

func (r *CreatePolicyRequest) MarshalPB(v *pb.CreatePolicyRequest) error

MarshalPB converts the CreatePolicyRequest into its protobuf representation.

func (*CreatePolicyRequest) UnmarshalPB added in v0.3.0 

func (r *CreatePolicyRequest) UnmarshalPB(v *pb.CreatePolicyRequest) error

UnmarshalPB initializes the CreatePolicyRequest from its protobuf representation.

type DecryptRequest 

type DecryptRequest struct {
	// Enclave is the KMS enclave containing the master key.
	Enclave string

	// Name is the name of the master key.
	Name string

	// Version identifies the key version within the key ring that should be
	// used to decrypt the ciphertext.
	Version int

	// Ciphertext is the encrypted message that is decrypted.
	Ciphertext []byte

	// AssociatedData is additional data that has been crypto. bound to the
	// ciphertext.
	AssociatedData []byte
}

DecryptRequest contains a ciphertext message that should be decrypted.

func (*DecryptRequest) MarshalPB 

func (r *DecryptRequest) MarshalPB(v *pb.DecryptRequest) error

MarshalPB converts the DecryptKeyRequest into its protobuf representation.

func (*DecryptRequest) UnmarshalPB 

func (r *DecryptRequest) UnmarshalPB(v *pb.DecryptRequest) error

UnmarshalPB initializes the DecryptKeyRequest from its protobuf representation.

type DecryptResponse 

type DecryptResponse struct {
	// Plaintext is the decrypted message.
	Plaintext []byte
}

DecryptResponse contains the decrypted plaintext message.

func (*DecryptResponse) MarshalPB 

func (r *DecryptResponse) MarshalPB(v *pb.DecryptResponse) error

MarshalPB converts the DecryptResponse into its protobuf representation.

func (*DecryptResponse) UnmarshalPB 

func (r *DecryptResponse) UnmarshalPB(v *pb.DecryptResponse) error

UnmarshalPB initializes the DecryptResponse from its protobuf representation.

type DeleteEnclaveRequest added in v0.2.0 

type DeleteEnclaveRequest struct {
	// Name is the name of the enclave to delete.
	Name string
}

DeleteEnclaveRequest contains options for deleting enclaves.

func (*DeleteEnclaveRequest) MarshalPB added in v0.4.0 

func (r *DeleteEnclaveRequest) MarshalPB(v *pb.DeleteEnclaveRequest) error

MarshalPB converts the DeleteEnclaveRequest into its protobuf representation.

func (*DeleteEnclaveRequest) UnmarshalPB added in v0.4.0 

func (r *DeleteEnclaveRequest) UnmarshalPB(v *pb.DeleteEnclaveRequest) error

UnmarshalPB initializes the EnclaveStatusRequest from its protobuf representation.

type DeleteIdentityRequest added in v0.3.0 

type DeleteIdentityRequest struct {
	// Enclave is the KMS enclave containing the identity.
	Enclave string

	// Identity is the identity that is deleted.
	Identity Identity
}

DeleteIdentityRequest contains options for deleting an identity.

func (*DeleteIdentityRequest) MarshalPB added in v0.4.0 

func (r *DeleteIdentityRequest) MarshalPB(v *pb.DeleteIdentityRequest) error

MarshalPB converts the DeleteIdentityRequest into its protobuf representation.

func (*DeleteIdentityRequest) UnmarshalPB added in v0.4.0 

func (r *DeleteIdentityRequest) UnmarshalPB(v *pb.DeleteIdentityRequest) error

UnmarshalPB initializes the DeleteIdentityRequest from its protobuf representation.

type DeleteKeyRequest added in v0.3.0 

type DeleteKeyRequest struct {
	// Enclave is the KMS enclave containing the master key.
	Enclave string

	// Name is the name of the key to delete.
	Name string

	// Version is the key version to remove. If <= 0, refers
	// to latest key version currently present. Once a key
	// version has been removed it cannot be added again.
	Version int

	// AllVersions indicates whether all key versions should be removed.
	// If true, Version must be 0.
	AllVersions bool
}

DeleteKeyRequest contains options for deleting secret keys.

For removing just a single key version from a key refer to Client.RemoveKeyVersion and RemoveKeyVersionRequest.

func (*DeleteKeyRequest) MarshalPB added in v0.3.0 

func (r *DeleteKeyRequest) MarshalPB(v *pb.DeleteKeyRequest) error

MarshalPB converts the DeleteKeyRequest into its protobuf representation.

func (*DeleteKeyRequest) UnmarshalPB added in v0.3.0 

func (r *DeleteKeyRequest) UnmarshalPB(v *pb.DeleteKeyRequest) error

UnmarshalPB initializes the DeleteKeyRequest from its protobuf representation.

type DeletePolicyRequest added in v0.3.0 

type DeletePolicyRequest struct {
	// Enclave is the KMS enclave containing the policy.
	Enclave string

	// Name is the name of the policy that is deleted.
	Name string
}

DeletePolicyRequest contains options for deleting a policy.

func (*DeletePolicyRequest) MarshalPB added in v0.4.0 

func (r *DeletePolicyRequest) MarshalPB(v *pb.DeletePolicyRequest) error

MarshalPB converts the DeletePolicyRequest into its protobuf representation.

func (*DeletePolicyRequest) UnmarshalPB added in v0.4.0 

func (r *DeletePolicyRequest) UnmarshalPB(v *pb.DeletePolicyRequest) error

UnmarshalPB initializes the DeletePolicyRequest from its protobuf representation.

type EditClusterRequest added in v0.3.0 

type EditClusterRequest struct {
	// Host is the KMS server where the cluster definition should be
	// modified. If empty, a Client will use its first host.
	Host string

	// Remove is a list of KMS server node IDs that are removed
	// from the cluster definition of the KMS server that receives
	// the request.
	Remove []int
}

EditClusterRequest contains updates to the cluster definition and allows clients to edit the cluster definition directly without requiring write quorum.

func (*EditClusterRequest) MarshalPB added in v0.3.0 

func (r *EditClusterRequest) MarshalPB(v *pb.EditClusterRequest) error

MarshalPB converts the EditClusterRequest into its protobuf representation.

func (*EditClusterRequest) UnmarshalPB added in v0.3.0 

func (r *EditClusterRequest) UnmarshalPB(v *pb.EditClusterRequest) error

UnmarshalPB initializes the EditClusterRequest from its protobuf representation.

type EnclaveStatusRequest added in v0.4.0 

type EnclaveStatusRequest struct {
	// Name is the name of the enclave to delete.
	Name string
}

EnclaveStatusRequest contains options for fetching metadata about an enclave.

func (*EnclaveStatusRequest) MarshalPB added in v0.4.0 

func (r *EnclaveStatusRequest) MarshalPB(v *pb.CreateEnclaveRequest) error

MarshalPB converts the EnclaveStatusRequest into its protobuf representation.

func (*EnclaveStatusRequest) UnmarshalPB added in v0.4.0 

func (r *EnclaveStatusRequest) UnmarshalPB(v *pb.EnclaveStatusRequest) error

UnmarshalPB initializes the EnclaveStatusRequest from its protobuf representation.

type EnclaveStatusResponse added in v0.4.0 

type EnclaveStatusResponse struct {
	// Name is the name of the enclave.
	Name string

	// CreatedAt is the point in time when the enclave has been created.
	CreatedAt time.Time

	// CreatedBy is the identity that created the enclave.
	CreatedBy Identity
}

EnclaveStatusResponse contains information about an enclave.

func (*EnclaveStatusResponse) MarshalPB added in v0.4.0 

func (r *EnclaveStatusResponse) MarshalPB(v *pb.EnclaveStatusResponse) error

MarshalPB converts the EnclaveStatusResponse into its protobuf representation.

func (*EnclaveStatusResponse) UnmarshalPB added in v0.4.0 

func (r *EnclaveStatusResponse) UnmarshalPB(v *pb.EnclaveStatusResponse) error

UnmarshalPB initializes the EnclaveStatusResponse from its protobuf representation.

type EncryptRequest 

type EncryptRequest struct {
	// Enclave is the KMS enclave containing the master key.
	Enclave string

	// Name is the name of the master key.
	Name string

	// Version is the key version used for encryption.
	// If <= 0, refers to latest key version currently
	// present.
	Version int

	// Plaintext is the plain message that is encrypted.
	Plaintext []byte

	// AssociatedData is additional data that is not encrypted but crypto. bound
	// to the ciphertext. The same associated data must be provided when decrypting
	// the ciphertext.
	//
	// Associated data should describe the context of the plaintext data. For example,
	// the name of the file that gets encrypted.
	AssociatedData []byte
}

EncryptRequest contains a plaintext message that should be encrypted and associated data that is crypto. bound to the resulting ciphertext.

func (*EncryptRequest) MarshalPB 

func (r *EncryptRequest) MarshalPB(v *pb.EncryptRequest) error

MarshalPB converts the EncryptRequest into its protobuf representation.

func (*EncryptRequest) UnmarshalPB 

func (r *EncryptRequest) UnmarshalPB(v *pb.EncryptRequest) error

UnmarshalPB initializes the EncryptRequest from its protobuf representation.

type EncryptResponse 

type EncryptResponse struct {
	// Version identifies the particular key within a key ring used to encrypt
	// the message.
	Version int

	// Ciphertext is the encrypted message.
	Ciphertext []byte
}

EncryptResponse contains the ciphertext of an encrypted message and the key version used to encrypt the message.

func (*EncryptResponse) MarshalPB 

func (r *EncryptResponse) MarshalPB(v *pb.EncryptResponse) error

MarshalPB converts the EncryptResponse into its protobuf representation.

func (*EncryptResponse) UnmarshalPB 

func (r *EncryptResponse) UnmarshalPB(v *pb.EncryptResponse) error

UnmarshalPB initializes the EncryptResponse from its protobuf representation.

type Error 

type Error struct {
	Code int    // The HTTP response status code
	Err  string // The error message
}

Error is a KMS API error.

func (Error) Error 

func (e Error) Error() string

Error returns the Error's error string.

func (Error) Status 

func (e Error) Status() int

Status returns the Error's HTTP response status code.

type GenerateKeyRequest 

type GenerateKeyRequest struct {
	// Enclave is the KMS enclave containing the master key.
	Enclave string

	// Name is the name of the master key.
	Name string

	Version int

	// AssociatedData is additional data that is not encrypted but crypto. bound
	// to the ciphertext of the data encryption key. The same associated data must
	// be provided when decrypting the ciphertext.
	//
	// Associated data should describe the context within the data encryption key
	// is used. For example, the name of the file that gets encrypted with the
	// data encryption key.
	AssociatedData []byte

	// Length is an optional length of the generated plaintext data encryption key
	// in bytes. At most 1024 (8192 bits). If <= 0, defaults to 32 (256 bits).
	Length int
}

GenerateKeyRequest contains options for generating a new unique data encryption key.

func (*GenerateKeyRequest) MarshalPB 

func (r *GenerateKeyRequest) MarshalPB(v *pb.GenerateKeyRequest) error

MarshalPB converts the GenerateKeyRequest into its protobuf representation.

func (*GenerateKeyRequest) UnmarshalPB 

func (r *GenerateKeyRequest) UnmarshalPB(v *pb.GenerateKeyRequest) error

UnmarshalPB initializes the GenerateKeyRequest from its protobuf representation.

type GenerateKeyResponse 

type GenerateKeyResponse struct {
	// Version identifies the particular key within a key ring used to generate
	// and encrypt this data encryption key.
	Version int

	// Plaintext is the plain data encryption key. It may be used by applications
	// to perform crypto. operations.
	Plaintext []byte

	// Ciphertext is the encrypted data encryption key. Applications should store
	// it to obtain the plain data encryption key in the future again.
	Ciphertext []byte
}

GenerateKeyResponse contains data encryption key that consists of a plaintext data encryption key and an encrypted ciphertext. Applications should use, but never store, the plaintext data encryption key for crypto. operations and store the ciphertext and key version.

func (*GenerateKeyResponse) MarshalPB 

func (r *GenerateKeyResponse) MarshalPB(v *pb.GenerateKeyResponse) error

MarshalPB converts the GenerateKeyResponse into its protobuf representation.

func (*GenerateKeyResponse) UnmarshalPB 

func (r *GenerateKeyResponse) UnmarshalPB(v *pb.GenerateKeyResponse) error

UnmarshalPB initializes the GenerateKeyResponse from its protobuf representation.

type HostError added in v0.4.0 

type HostError struct {
	Host string // The host for which an operation failed
	Err  error  // The underlying error
}

HostError captures an error returned by a host. It implements the net.Error interface.

func AsHostError added in v0.4.0 

func AsHostError(err error) *HostError

AsHostError returns the first error in err's tree, using errors.As, that is of type *HostError. Otherwise, it returns nil.

func UnwrapHostErrors added in v0.4.0 

func UnwrapHostErrors(err error) []*HostError

UnwrapHostErrors returns a list of all HostError within err's tree. If err is nil or err's tree contains no HostError it returns nil.

The tree consists of err itself, followed by the errors obtained by repeatedly calling errors.Unwrap. When err wraps multiple errors, UnwrapHostErrors examines err followed by a depth-first traversal of its children.

func (*HostError) Error added in v0.4.0 

func (e *HostError) Error() string

Error returns the underlying error message prefixed by the host.

func (*HostError) Temporary deprecated added in v0.4.0 

func (e *HostError) Temporary() bool

Temporary reports whether the error is temporary.

Deprecated: Temporary errors are not well-defined. It is only there to satisfy the net.Error interface.

func (*HostError) Timeout added in v0.4.0 

func (e *HostError) Timeout() bool

Timeout reports whether the error s caused by a timeout.

func (*HostError) Unwrap added in v0.4.0 

func (e *HostError) Unwrap() error

Unwrap returns the underlying error.

type Identity 

type Identity string

An Identity uniquely identifies a private/public key pair. It consists of a prefix for the hash function followed by the URL base64-encoded hash of the public key.

For example: 

h1:BPbFim5DqUozIYOjcaRAtImU6TdD6W2_chOgxDyCuDw

This package uses the "h1:" prefix for SHA-256 and computes the hash of X.509 certificates from the certificate's DER-encoded public key info.

For example: 

shasum := sha256.Sum256(cert.RawSubjectPublicKeyInfo)
identity := "h1:" + base64.RawURLEncoding.EncodeToString(shasum[:])

By verifying the peer's identity, two parties can detect MitM¹ attacks during a protocol handshake, like in TLS. An identity pins the public key, similar to SSH² or HPKP³.

The empty string represents a pseudo identity and indicates that no public key has been provided.

Ref: [1] https://en.wikipedia.org/wiki/Man-in-the-middle_attack [2] https://en.wikipedia.org/wiki/Key_fingerprint [3] https://en.wikipedia.org/wiki/HTTP_Public_Key_Pinning

func (Identity) String 

func (i Identity) String() string

type IdentityRequest added in v0.3.0 

type IdentityRequest struct {
	// Enclave is the KMS enclave containing the identity.
	Enclave string

	// Identity is the identity.
	Identity Identity
}

IdentityRequest contains options for fetching identity metadata.

func (*IdentityRequest) MarshalPB added in v0.4.0 

func (r *IdentityRequest) MarshalPB(v *pb.IdentityRequest) error

MarshalPB converts the IdentityRequest into its protobuf representation.

func (*IdentityRequest) UnmarshalPB added in v0.4.0 

func (r *IdentityRequest) UnmarshalPB(v *pb.IdentityRequest) error

UnmarshalPB initializes the IdentityRequest from its protobuf representation.

type IdentityResponse added in v0.4.0 

type IdentityResponse struct {
	// Identity is the identity referring to a private/public key pair.
	Identity Identity

	// Privilege is the identity's privilege.
	Privilege Privilege

	// Policy is the name of the assigned policy, if any. It is empty
	// if the identity's privilege is Admin or SysAdmin.
	Policy string

	// CreatedAt is the point in time when this identity was created.
	CreatedAt time.Time

	// CreatedBy is the identity that created this identity.
	CreatedBy Identity

	// IsServiceAccount indicates whether this identity is a service
	// account. By default, service accounts inherit the permissions
	// of their parent identity. Service accounts are removed
	// automatically when their parent identity is deleted.
	IsServiceAccount bool

	// ServiceAccounts contains all service accounts of this identity.
	ServiceAccounts []Identity
}

IdentityResponse contains information about an identity.

func (*IdentityResponse) MarshalPB added in v0.4.0 

func (r *IdentityResponse) MarshalPB(v *pb.IdentityResponse) error

MarshalPB converts the IdentityResponse into its protobuf representation.

func (*IdentityResponse) UnmarshalPB added in v0.4.0 

func (r *IdentityResponse) UnmarshalPB(v *pb.IdentityResponse) error

UnmarshalPB initializes the IdentityResponse from its protobuf representation.

type ImportKeyRequest added in v0.4.0 

type ImportKeyRequest struct {
	// Enclave is the KMS enclave in which the key is created.
	Enclave string

	// Name is the name of the key to create.
	Name string

	// Type of the key that is created. For example, AES256.
	// If not set, the server will pick a key type.
	Type SecretKeyType

	// Key is the secret key imported into the KMS server.
	// It must be a valid key for the given key type.
	Key []byte
}

ImportKeyRequest contains options for importing secret keys.

func (*ImportKeyRequest) MarshalPB added in v0.4.0 

func (r *ImportKeyRequest) MarshalPB(v *pb.ImportKeyRequest) error

MarshalPB converts the ImportKeyRequest into its protobuf representation.

func (*ImportKeyRequest) UnmarshalPB added in v0.4.0 

func (r *ImportKeyRequest) UnmarshalPB(v *pb.ImportKeyRequest) error

UnmarshalPB initializes the ImportKeyRequest from its protobuf representation.

type Iter added in v0.2.0 

type Iter[T any] struct {
	// NextFn is a function that returns the next page from
	// a paginated list.
	NextFn func(context.Context, *ListRequest) (*Page[T], error)
	// contains filtered or unexported fields
}

Iter is an iterator over elements of type T. It turns a paginated listing provided by the NextFn into a continuous stream of items.

func (*Iter[T]) Next added in v0.2.0 

func (i *Iter[T]) Next(ctx context.Context) (item T, err error)

Next returns the next item from the stream or io.EOF at the end. The context is used when Next has to fetch the next page of the paginated listing.

func (*Iter[T]) SeekTo added in v0.2.0 

func (i *Iter[T]) SeekTo(ctx context.Context, req *ListRequest) (item T, err error)

SeekTo seeks to a specific position within the stream and returns the item at this position.

type KeyStatusRequest added in v0.4.0 

type KeyStatusRequest struct {
	// Enclave is the KMS enclave containing the master key.
	Enclave string

	// Name is the name of the master key.
	Name string

	// Version is the key version. If <= 0, refers to
	// latest key version currently present.
	Version int
}

KeyStatusRequest contains options for fetching metadata about a key version.

func (*KeyStatusRequest) MarshalPB added in v0.4.0 

func (r *KeyStatusRequest) MarshalPB(v *pb.KeyStatusRequest) error

MarshalPB converts the KeyStatusRequest into its protobuf representation.

func (*KeyStatusRequest) UnmarshalPB added in v0.4.0 

func (r *KeyStatusRequest) UnmarshalPB(v *pb.KeyStatusRequest) error

UnmarshalPB initializes the KeyStatusRequest from its protobuf representation.

type KeyStatusResponse added in v0.4.0 

type KeyStatusResponse struct {
	// Name is the name of the secret key ring.
	Name string

	// Version is the verion of this key identifying it within the key ring.
	Version int

	// Type is the type of the secret key. For example, AES256.
	Type SecretKeyType

	// CreatedAt is the point in time when this key version has been created.
	CreatedAt time.Time

	// CreatedBy is the identity that created this key version.
	CreatedBy Identity
}

KeyStatusResponse contains information about a secret key version.

func (*KeyStatusResponse) MarshalPB added in v0.4.0 

func (r *KeyStatusResponse) MarshalPB(v *pb.KeyStatusResponse) error

MarshalPB converts the KeyStatusResponse into its protobuf representation.

func (*KeyStatusResponse) UnmarshalPB added in v0.4.0 

func (r *KeyStatusResponse) UnmarshalPB(v *pb.KeyStatusResponse) error

UnmarshalPB initializes the KeyStatusResponse from its protobuf representation.

type ListRequest added in v0.2.0 

type ListRequest struct {
	// Enclave is the enclave in which to list elements. For
	// example keys or policies. It is ignored when listing
	// enclaves.
	Enclave string

	// Prefix is an optional prefix to start the listing from.
	// For example, an application may want to list all keys
	// starting with "foo", like "foo-1" and "foobar".
	//
	// Only elements with a name that match this prefix are
	// returned by list operations. An empty prefix matches
	// any name.
	Prefix string

	// ContinueAt specifies an element name from where to
	// continue a list operation. When listing a lot of
	// elements, not all may fit into a single ListResponse.
	// Applications can paginate through a long list of
	// elements by setting a ContinueAt value.
	//
	// ContinueAt must match an element's name exactly.
	// Using a ContinueAt value that does not start with
	// the Prefix will lead to an empty listing result.
	ContinueAt string

	// Limit limits the number of elements returned by
	// a list operation. If <= 0, no limit is specified
	// and the server limits listing results to a
	// reasonable max. size.
	Limit int
}

ListRequest contains generic options for listing elements, like enclaves or keys.

func (*ListRequest) MarshalPB added in v0.4.0 

func (r *ListRequest) MarshalPB(v *pb.ListRequest) error

MarshalPB converts the ListRequest into its protobuf representation.

func (*ListRequest) UnmarshalPB added in v0.4.0 

func (r *ListRequest) UnmarshalPB(v *pb.ListRequest) error

UnmarshalPB initializes the ListRequest from its protobuf representation.

type LivenessRequest added in v0.4.0 

type LivenessRequest struct {
	// List of endpoints for which the liveness state is
	// checked. If empty, the client checks the liveness
	// state on all known endpoints.
	Hosts []string
}

LivenessRequest contains options for checking whether one or multiple KMS servers are alive.

type Page added in v0.3.0 

type Page[T any] struct {
	Items []T // The next items from the listing.

	// ContinueAt refers to the first item on the next
	// page from where to resume the listing. Empty at
	// the end of the listing.
	ContinueAt string
}

A Page contains the next items of type T from a paginated listing. It's ContinueAt pointer refers to the next page, if any.

type PolicyRequest added in v0.3.0 

type PolicyRequest struct {
	// Enclave is the KMS enclave containing the policy.
	Enclave string

	// Name is the name of the policy.
	Name string
}

PolicyRequest contains options for fetching a policy and policy metadata.

func (*PolicyRequest) MarshalPB added in v0.4.0 

func (r *PolicyRequest) MarshalPB(v *pb.PolicyRequest) error

MarshalPB converts the PolicyRequest into its protobuf representation.

func (*PolicyRequest) UnmarshalPB added in v0.4.0 

func (r *PolicyRequest) UnmarshalPB(v *pb.PolicyRequest) error

UnmarshalPB initializes the PolicyRequest from its protobuf representation.

type PolicyResponse added in v0.3.0 

type PolicyResponse struct {
	// Name is the name of the policy.
	Name string

	// Allow is the set of allow rules.
	Allow map[cmds.Command]RuleSet

	// Deny is the set of deny rules.
	Deny map[cmds.Command]RuleSet

	// CreatedAt is the point in time when the policy has been created.
	CreatedAt time.Time

	// CreatedBy is the identity that created the policy.
	CreatedBy Identity
}

PolicyResponse contains information about a policy and the policy definition.

func (*PolicyResponse) MarshalPB added in v0.3.0 

func (r *PolicyResponse) MarshalPB(v *pb.PolicyResponse) error

MarshalPB converts the PolicyResponse into its protobuf representation.

func (*PolicyResponse) UnmarshalPB added in v0.3.0 

func (r *PolicyResponse) UnmarshalPB(v *pb.PolicyResponse) error

UnmarshalPB initializes the PolicyResponse from its protobuf representation.

type PolicyStatusResponse added in v0.4.0 

type PolicyStatusResponse struct {
	// Name is the name of the policy.
	Name string

	// CreatedAt is the point in time when the policy has been created.
	CreatedAt time.Time

	// CreatedBy is the identity that created the policy.
	CreatedBy Identity
}

PolicyStatusResponse contains information about a policy.

func (*PolicyStatusResponse) MarshalPB added in v0.4.0 

func (r *PolicyStatusResponse) MarshalPB(v *pb.PolicyStatusResponse) error

MarshalPB converts the PolicyStatusResponse into its protobuf representation.

func (*PolicyStatusResponse) UnmarshalPB added in v0.4.0 

func (r *PolicyStatusResponse) UnmarshalPB(v *pb.PolicyStatusResponse) error

UnmarshalPB initializes the PolicyStatusResponse from its protobuf representation.

type Privilege added in v0.3.0 

type Privilege uint

Privilege represents an access control role of identities. An identity with a higher privilege has access to more APIs.

As a general security best practice, identities should have the lowest privilege required to perform their tasks. 

const (
	// SysAdmin is the highest privilege within the KMS, similar to
	// root on unix systems. An identity with the SysAdmin privilege
	// has access to all public APIs. Identities with the SysAdmin
	// privilege should be used for provisioning and to manage the
	// KMS cluster.
	SysAdmin Privilege = iota + 1

	// Admin is the privilege that allows identities to perform all
	// operations within an enclave. In contrast to sysadmins, admins
	// cannot peform cluster management tasks or manage enclaves.
	Admin

	// User is the privilege with limited access within an enclave.
	// Identities with the User privilege can only perform operations
	// within an enclave and only with an associated policy allowing
	// the API operation.
	User
)

Supported privileges.

func ParsePrivilege added in v0.3.0 

func ParsePrivilege(s string) (Privilege, error)

ParsePrivilege parses s as privilege string representation.

func (Privilege) String added in v0.3.0 

func (p Privilege) String() string

String returns the string representation of the Privilege.

type ReadDBResponse added in v0.4.0 

type ReadDBResponse struct {
	Body io.ReadCloser // The database content
}

ReadDBResponse contains the database content received from a KMS server.

func (*ReadDBResponse) Close added in v0.4.0 

func (r *ReadDBResponse) Close() error

Close closes the underlying response body.

func (*ReadDBResponse) Read added in v0.4.0 

func (r *ReadDBResponse) Read(b []byte) (int, error)

Read reads data from the response body into b.

type ReadinessRequest added in v0.4.0 

type ReadinessRequest struct {
	// List of endpoints for which the readiness state is
	// checked. If empty, the client checks the readiness
	// state on all known endpoints.
	Hosts []string

	// Write, if true, checks whether the servers are
	// ready to serve "write" requests that change the
	// KMS state.
	Write bool
}

ReadinessRequest contains options for checking whether one or multiple KMS servers are ready to serve requests.

type RemoveClusterNodeRequest added in v0.4.0 

type RemoveClusterNodeRequest struct {
	// Host is the KMS server that should leave a cluster.
	// It must be of the form "host" or "host:port".
	Host string
}

RemoveClusterNodeRequest describes which server to remove from a KMS cluster.

func (*RemoveClusterNodeRequest) MarshalPB added in v0.4.0 

func (r *RemoveClusterNodeRequest) MarshalPB(v *pb.RemoveClusterNodeRequest) error

MarshalPB converts the RemoveClusterNodeRequest into its protobuf representation.

func (*RemoveClusterNodeRequest) UnmarshalPB added in v0.4.0 

func (r *RemoveClusterNodeRequest) UnmarshalPB(v *pb.RemoveClusterNodeRequest) error

UnmarshalPB initializes the RemoveClusterNodeRequest from its protobuf representation.

type Request added in v0.4.0 

type Request struct {
	// Host is the DNS hostname or IP address of the
	// KMS server. If empty, the Client will pick one
	// of its KMS servers and perform client-side
	// load balancing. Providing a host explicitly
	// circumvents the client load balancer. This
	// may be desirable when trying to communicate
	// with one particular KMS server.
	//
	// Host may start with the HTTPS URI scheme "https://"
	// and can contain an optional port number.
	Host string

	// Enclave is the KMS enclave in which all KMS
	// commands specified in the request body are
	// executed.
	//
	// For KMS cluster commands, like fetching cluster
	// status information, that don't operate within
	// any enclave, Enclave is empty.
	Enclave string

	// Body is the request body. It contains one or
	// multiple encoded commands to be executed by
	// the KMS.
	Body []byte
}

Request is a structure describing a KMS request.

type Rule added in v0.3.0 

type Rule struct{}

Rule is a policy rule allowing for more fine-grain API access control.

type RuleSet added in v0.4.0 

type RuleSet map[string]Rule

A RuleSet is a set of patterns and their associated rules. It defines which rule should be applied when an argument matches a pattern.

For example, the RuleSet {"my-key*": {}} applies the empty Rule, one without any restrictions, whenever a request or command argument matches the "my-key*" pattern.

The RuleSet is the building block for KMS policies. Such a policy defines which RuleSet is applied for which KMS commands. For example, the RuleSet from above may be used for the CreateKey command. In this case, the policy would allow the creation of keys if and only if the key name would match the "my-key*" pattern.

A RuleSet can be represented as protobuf message or JSON object. Usually, policies are defined in JSON to be human readable. For ease of use, a RuleSet can not just be represented as JSON object but also as JSON array or JSON string if the RuleSet contains just a single entry. For example the following to JSON documents are decoded into equal RuleSets:

  1. RuleSet as JSON object:

    { "my-key*": {}, }

  2. RuleSet as JSON array:

    ["my-key*"]

  3. RuleSet as JSON string:

    "my-key*"

The 2nd and 3rd forms are shorter and easier to read than the 1st one. However, the 1st one more accurately represenets the RuleSet's in memory representation and allows future extensions.

func (RuleSet) MarshalJSON added in v0.4.0 

func (r RuleSet) MarshalJSON() ([]byte, error)

MarshalJSON returns the RuleSet's JSON representation.

If the RuleSet contains only empty Rules, or no Rules, MarshalJSON returns a list of the RuleSet's patterns as JSON array.

Otherwise, it returns a JSON object with each pattern being a key and the JSON representation of the corresponding Rule the associated value.

func (*RuleSet) MarshalPB added in v0.4.0 

func (r *RuleSet) MarshalPB(v *pb.RuleSet) error

MarshalPB converts the RuleSet into its protobuf representation.

func (*RuleSet) UnmarshalJSON added in v0.4.0 

func (r *RuleSet) UnmarshalJSON(b []byte) error

UnmarshalJSON initializes the RuleSet from its JSON representation. UnmarshalJSON is able to decode RuleSet JSON objects produced by MarshalJSON. Therefore, b may be an array of patterns as strings or a JSON object containing the patterns as strings and the Rules as JSON objects.

func (*RuleSet) UnmarshalPB added in v0.4.0 

func (r *RuleSet) UnmarshalPB(v *pb.RuleSet) error

UnmarshalPB initializes the RuleSet from its protobuf representation.

type SecretKeyType added in v0.2.0 

type SecretKeyType uint

SecretKeyType defines the type of a secret key. Secret keys with different types are not compatible since they may differ in the encryption algorithm, key length, cipher mode, etc. 

const (
	// AES256 represents the AES-256-GCM secret key type.
	AES256 SecretKeyType = iota + 1

	// ChaCha20 represents the ChaCha20-Poly1305 secret key type.
	ChaCha20
)

Supported secret key types.

func ParseSecretKeyType added in v0.4.0 

func ParseSecretKeyType(s string) (SecretKeyType, error)

ParseSecretKeyType returns a SecretKeyType from its string representation.

func (SecretKeyType) String added in v0.2.0 

func (s SecretKeyType) String() string

String returns the string representation of the SecretKeyType.

type ServerStatusRequest added in v0.4.0 

type ServerStatusRequest struct {
	// List of endpoints from which status information
	// is requested. If empty, the client requests status
	// information from all known endpoints.
	Hosts []string
}

ServerStatusRequest contains options for fetching status information for one particular KMS server.

type ServerStatusResponse added in v0.2.0 

type ServerStatusResponse struct {
	// Version is the version of the KMS server. It's the timestamp of
	// the latest commit formatted as 'yyyy-mm-ddThh-mm-ssZ'. For example,
	// "2023-12-01T16-06-52Z"
	Version string

	// APIVersion is the API version supported by the KMS server.
	// For example, "v1".
	APIVersion string

	// Host is the KMS server endpoint as 'host' or 'host:port'.
	Host string

	// UpTime is the amount of time the KMS server is up and running.
	UpTime time.Duration

	// Role is the current role the KMS server node has within the cluster.
	// Either, "Leader", "Follower" or "Candidate".
	Role string

	// Commit is the number of state changes applied to this KMS server.
	Commit uint64

	// Nodes is a list of KMS server nodes within the KMS cluster as a map
	// of node IDs to KMS server addresses of the form 'host' or 'host:port'.
	Nodes map[int]string

	// ID is the node ID of this KMS server. It only changes if the node
	// joins a cluster.
	ID int

	// LeaderID is the ID of the current cluster leader or negative if
	// the cluster has no leader.
	LeaderID int

	// LastHeartbeat is the duration since the KMS server has sent or received
	// a heartbeat. As long as there is a cluster leader, it should be lower
	// than the ElectionTimeout.
	LastHeartbeat time.Duration

	// HeartbeatInterval defines the frequency in which this KMS server, as cluster
	// leader, sends heartbeats to its follower nodes. All nodes within a cluster
	// should use the same heartbeat interval.
	HeartbeatInterval time.Duration

	// ElectionTimeout defines how long a KMS server node waits for heartbeats before
	// it considers the cluster leaders as down and starts a leader election to become
	// the cluster leader itself.
	//
	// Each cluster node should have a slightly different election timeout to avoid
	// spliting votes. Typically, base election timeout + random jitter. The average
	// or base election timeout of all cluster nodes should be balanced with the
	// HeartbeatInterval to prevent nodes from starting elections even though a leader
	// is present. A reasonable default may be:
	//
	//   ElectionTimeout = 3 * HeartbeatInterval.
	ElectionTimeout time.Duration

	// OS identifies the operating system the KMS server is running on.
	// For example, "linux" or "darwin".
	OS string

	// CPUArch is the CPU architecture of the KMS server. For example, "amd64".
	CPUArch string

	// CPUs is the number of logical CPUs that can execite the KMS server process.
	// However, the KMS server may not use all of these CPUs. It might be limited
	// to fewer CPUs.
	CPUs uint

	// UsableCPUs is the number of CPUs actually used by the KMS server process.
	// Unless the KMS server has been limited to fewer CPUs, equal to CPUs field.
	UsableCPUs uint

	// HeapMemInUse is the amount of heap memory currently occupied by the KMS server.
	// The total amount of memory used by the KMS server process is HeapMemInUse +
	// StackMemInUse.
	HeapMemInUse uint64

	// StackMemInUse is the amount of stack memory currently occupied by the KMS server.
	// The total amount of memory used by the KMS server process is HeapMemInUse +
	// StackMemInUse.
	StackMemInUse uint64
}

ServerStatusResponse contains status information about a single KMS server.

func (*ServerStatusResponse) MarshalPB added in v0.2.0 

func (s *ServerStatusResponse) MarshalPB(v *pb.ServerStatusResponse) error

MarshalPB converts the ServerStatusResponse into its protobuf representation.

func (*ServerStatusResponse) UnmarshalPB added in v0.2.0 

func (s *ServerStatusResponse) UnmarshalPB(v *pb.ServerStatusResponse) error

UnmarshalPB initializes the ServerStatusResponse from its protobuf representation.

type VersionRequest added in v0.4.0 

type VersionRequest struct {
	// List of endpoints from which version information
	// is requested. If empty, the client requests version
	// information from all known endpoints.
	Hosts []string
}

VersionRequest contains options for fetching version information for one or multiple KMS servers.

type VersionResponse added in v0.2.0 

type VersionResponse struct {
	// Version is the version of the KMS server. It's the timestamp of
	// the latest commit formatted as 'yyyy-mm-ddThh-mm-ssZ'. For example,
	// "2023-12-01T16-06-52Z"
	Version string

	// Commit is the commit ID of the most latest code change of the KMS
	// server.
	Commit string

	// APIVersion is the API version supported by the KMS server.
	// For example, "v1".
	APIVersion string

	// Host is the KMS server endpoint as 'host' or 'host:port'.
	Host string
}

VersionResponse contains version information about a KMS server.

func (*VersionResponse) MarshalPB added in v0.2.0 

func (r *VersionResponse) MarshalPB(v *pb.VersionResponse) error

MarshalPB converts the VersionResponse into its protobuf representation.

func (*VersionResponse) UnmarshalPB added in v0.2.0 

func (r *VersionResponse) UnmarshalPB(v *pb.VersionResponse) error

UnmarshalPB initializes the VersionResponse from its protobuf representation.

Source Files

View all Source files

Directories

Path Synopsis
internal
api
headers
Package headers defines common HTTP headers.
 Package headers defines common HTTP headers.
https

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.