Module zerokms 

The zerokms module provides a client for interacting with the ZeroKMS service.

ZeroKMS provides key management and encryption services using CipherStash’s “Vitur” protocol. This client provides a high-level interface for managing keys, granting access and encrypting/decrypting data.

Creating a ZeroKMS Client

The recommended way to create a ZeroKMS client is using ZeroKMSBuilder, which resolves the ZeroKMS endpoint automatically from the token’s services claim:

use cipherstash_client::zerokms::ZeroKMSBuilder;
use stack_auth::AutoStrategy;

let strategy = AutoStrategy::detect()?;
let zerokms = ZeroKMSBuilder::new(strategy)
    .build()?;

Workspaces, Keysets and Clients

ZeroKMS is built around the concept of Keysets and Clients that are encapsulated within a Workspace.

• Workspaces are the top-level entity that encapsulates all Keysets and Clients.
• Keysets represent a set of data that is encrypted under the same key heirarchy.
• Clients are entities that can generate and retrieve keys for one or more keysets.

Authentication

To use the ZeroKMS client, a valid access token is required. You don’t need to provide this directly: it is handled by the client using one of 2 methods:

• Stash CLI: You can use the stash CLI to authenticate and store the access token
• Client Access Key: You can provide a client access key to the client to authenticate

Stash CLI is best for local development and testing, while the client access key is best for production.

ZeroKMS Client

The ZeroKMS client provides a high-level interface for managing Keysets and Clients in ZeroKMS. It does not provide methods to encrypt or decrypt data. For that, you need to use a ZeroKMSWithClientKey client.

The ZeroKMS client can perform the following operations:

• Create a new Keyset
• Grant and Revoke access to a Keyset for a client
• List all Keysets in a Workspace
• Enable and Disable a Keyset
• Modify a Keyset’s name or description
• Create a new Client for a Keyset
• List all Clients in a Workspace
• Revoke (Delete) a Client

ZeroKMSWithClientKey Client

The ZeroKMSWithClientKey is the same as ZeroKMS but with the ability to encrypt and decrypt data. Use it only when you need to perform encryption and decryption operations. If your client only needs to manage Keysets and Clients, use the ZeroKMS client.

The ZeroKMSWithClientKey client can perform the following operations:

• Encrypt one or many values
• Decrypt one or many values
• Save and Load a Keyset’s configuration

See also ClientKey and EncryptPayload.

Descriptors

ZeroKMSWithClientKey includes the concept of a “descriptor” which is a string that describes the data being encrypted. It provides a way to identify the data being encrypted and decrypted which can be used to ensure the data is being used correctly.

Descriptors are included in the “Authenticated Associated Data” (AAD) of the encryption and decryption operations. This means that the descriptor is included in the authentication tag and any tampering with the descriptor will cause the decryption to fail. Descriptors are also used by ZeroKMS to track the usage of keys and data.

Re-exports

pub use key_provider::EnvKeyProvider;

pub use key_provider::FallbackKeyProvider;

pub use key_provider::KeyProvider;

pub use key_provider::KeyProviderError;

pub use key_provider::StaticKeyProvider;

Modules

encrypted_record

key_provider

Trait and implementations for loading a ClientKey from various sources.

Structs

ClientKey

NOTE: Debug is safe to implement because KeySet is opaque.

CreateClientResponse

Response message to a CreateClientRequest.

CreateClientSpec

Specification for creating a client alongside a keyset.

CreateKeysetResponse

Response to a CreateKeysetRequest.

CreatedClient

Details of a client created as part of a CreateKeysetRequest.

DataKey

DataKeyWithTag

DatasetConfig

Struct to manage the config for a given database. At connection time, the Driver will retrieve config from Vitur for the currently connected database

DatasetConfigWithIndexRootKey

DeleteClientResponse

EncryptPayload

EncryptedRecord

Represents an encrypted record for storage in the database. Implements serialization and deserialization so you can use it with any serde-compatible format however convenience methods are provided for CBOR, MessagePack, Hex, and Base85 encoding.

GenerateKeyPayload

The requirements for generating a data key from Vitur.

Keyset

Struct representing a keyset. This is the response to a CreateKeysetRequest and a in a vector in the response to a ListKeysetRequest.

KeysetClient

Response type for a ListClientRequest.

RecordDecryptError

RetrieveKeyPayload

The requirements for retrieving a data key from Vitur.

SecretKey

A device-scoped client key, stored in secretkey.json within the profile directory.

ViturKeyMaterial

Key material type used in GenerateKeyRequest and RetrieveKeyRequest as well as CreateClientResponse.

WithContext

WithKeyProvider

Newtype wrapper that marks a KeyProvider in the builder’s type state.

ZeroKMS

ZeroKMSBuilder

A builder for creating ZeroKMS and ZeroKMSWithClientKey clients.

ZeroKMSClientOpts

Enums

ClientKeysetId

Struct representing the keyset ids associated with a client which could be a single keyset or multiple keysets.

ClientType

The type of client to create.

Context

Represents a contextual attribute for a data key which is used to “lock” the key to a specific context. Context attributes are included key tag generation which is in turn used as AAD in the final encryption step in the client. Context attributes should never include any sensitive information.

DecryptError

Error

IdentifiedBy

A UUID or textual name that can uniquely identify a resource. Whereas a UUID is a global identifier, name is not implied to be globally unique, but unique within scope implied scope: e.g. a workspace.

RetrieveKeyError

ZeroKMSBuilderError

Error type for ZeroKMSBuilder operations.

Traits

Decryptable

Functions

decrypt

encrypt

Type Aliases

ZeroKMSWithClientKey