zerokms_protocol/

lib.rs

mod base64_array;
mod base64_vec;
mod error;

use async_trait::async_trait;
use cipherstash_config::DatasetConfig;
use serde::{Deserialize, Serialize};
use std::{borrow::Cow, ops::Deref};
use uuid::Uuid;
use zeroize::{Zeroize, ZeroizeOnDrop};

pub use cipherstash_config;
/// Re-exports
pub use error::*;
pub mod testing;

#[async_trait]
pub trait ViturConnection {
    async fn send<Request: ViturRequest>(
        &self,
        request: Request,
        access_token: &str,
    ) -> Result<Request::Response, ViturRequestError>;
}

pub trait ViturResponse: Serialize + for<'de> Deserialize<'de> + Send {}

#[async_trait]
pub trait ViturRequest: Serialize + for<'de> Deserialize<'de> + Sized + Send {
    type Response: ViturResponse;

    const SCOPE: &'static str;
    const ENDPOINT: &'static str;
}

/// Request message to create a new [Dataset] with the given name and description.
///
/// Requies the `dataset:create` scope.
#[derive(Debug, Serialize, Deserialize)]
pub struct CreateDatasetRequest<'a> {
    pub name: Cow<'a, str>,
    pub description: Cow<'a, str>,
}

impl ViturRequest for CreateDatasetRequest<'_> {
    type Response = Dataset;

    const ENDPOINT: &'static str = "create-dataset";
    const SCOPE: &'static str = "dataset:create";
}

/// Request message to list all [Dataset]s.
///
/// Requires the `dataset:list` scope.
/// Response is a vector of [Dataset]s.
#[derive(Default, Debug, Serialize, Deserialize)]
pub struct ListDatasetRequest {
    #[serde(default)]
    pub show_disabled: bool,
}

impl ViturRequest for ListDatasetRequest {
    type Response = Vec<Dataset>;

    const ENDPOINT: &'static str = "list-datasets";
    const SCOPE: &'static str = "dataset:list";
}

/// Struct representing a dataset.
/// This is the response to a [CreateDatasetRequest] and a in a vector in the response to a [ListDatasetRequest].
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct Dataset {
    pub id: Uuid,
    pub name: String,
    pub description: String,
}

impl ViturResponse for Dataset {}
impl ViturResponse for Vec<Dataset> {}

/// Represents an empty response for requests that don't return any data.
#[derive(Default, Debug, Serialize, Deserialize)]
pub struct EmptyResponse {}

impl ViturResponse for EmptyResponse {}

/// Request message to create a new client with the given name, description and dataset_id.
///
/// Requires the `client:create` scope.
/// Response is a [CreateClientResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct CreateClientRequest<'a> {
    pub dataset_id: Uuid,
    pub name: Cow<'a, str>,
    pub description: Cow<'a, str>,
}

impl<'a> ViturRequest for CreateClientRequest<'a> {
    type Response = CreateClientResponse;

    const ENDPOINT: &'static str = "create-client";
    const SCOPE: &'static str = "client:create";
}

/// Response message to a [CreateClientRequest].
///
/// Contains the `client_id`` and the `client_key, the latter being a base64 encoded 32 byte key.
/// The `client_key` should be considered sensitive and should be stored securely.
#[derive(Debug, Serialize, Deserialize)]
pub struct CreateClientResponse {
    pub id: Uuid,
    pub dataset_id: Uuid,
    pub name: String,
    pub description: String,
    pub client_key: ViturKeyMaterial,
}

impl ViturResponse for CreateClientResponse {}

/// Request message to list all clients.
///
/// Requires the `client:list` scope.
/// Response is a vector of [DatasetClient]s.
#[derive(Debug, Serialize, Deserialize)]
pub struct ListClientRequest;

impl ViturRequest for ListClientRequest {
    type Response = Vec<DatasetClient>;

    const ENDPOINT: &'static str = "list-clients";
    const SCOPE: &'static str = "client:list";
}

/// Struct representing the dataset ids associated with a client
/// which could be a single dataset or multiple datasets.
#[derive(Debug, Deserialize, Serialize, PartialEq, Eq)]
#[serde(untagged)]
pub enum ClientDatasetId {
    Single(Uuid),
    Multiple(Vec<Uuid>),
}

/// A `Uuid` is comparable with `ClientDatasetId` if the `ClientDatasetId` is a `Single` variant.
impl PartialEq<Uuid> for ClientDatasetId {
    fn eq(&self, other: &Uuid) -> bool {
        if let ClientDatasetId::Single(id) = self {
            id == other
        } else {
            false
        }
    }
}

/// Response type for a [ListClientRequest].
#[derive(Debug, Serialize, Deserialize)]
pub struct DatasetClient {
    pub id: Uuid,
    pub dataset_id: ClientDatasetId,
    pub name: String,
    pub description: String,
}

impl ViturResponse for Vec<DatasetClient> {}

/// Request message to delete a client and all associated authority keys.
///
/// Requires the `client:revoke` scope.
/// Response is an [DeleteClientResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct DeleteClientRequest {
    pub client_id: Uuid,
}

impl ViturRequest for DeleteClientRequest {
    type Response = DeleteClientResponse;

    const ENDPOINT: &'static str = "delete-client";
    const SCOPE: &'static str = "client:delete";
}

#[derive(Default, Debug, Serialize, Deserialize)]
pub struct DeleteClientResponse {}

impl ViturResponse for DeleteClientResponse {}

/// Key material type used in [GenerateKeyRequest] and [RetrieveKeyRequest] as well as [CreateClientResponse].
#[derive(Serialize, Deserialize, Zeroize, ZeroizeOnDrop)]
pub struct ViturKeyMaterial(#[serde(with = "base64_vec")] Vec<u8>);
opaque_debug::implement!(ViturKeyMaterial);

impl From<Vec<u8>> for ViturKeyMaterial {
    fn from(inner: Vec<u8>) -> Self {
        Self(inner)
    }
}

impl Deref for ViturKeyMaterial {
    type Target = [u8];

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

/// Represents generated data key material which is used by the client to derive data keys with its own key material.
///
/// Returned in the response to a [GenerateKeyRequest].
#[derive(Debug, Serialize, Deserialize)]
pub struct GeneratedKey {
    pub key_material: ViturKeyMaterial,
    // FIXME: Use Vitamin C Equatable type
    #[serde(with = "base64_vec")]
    pub tag: Vec<u8>,
}

/// Response to a [GenerateKeyRequest].
#[derive(Debug, Serialize, Deserialize)]
pub struct GenerateKeyResponse {
    pub keys: Vec<GeneratedKey>,
}

impl ViturResponse for GenerateKeyResponse {}

/// A specification for generating a data key used in a [GenerateKeyRequest].
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct GenerateKeySpec<'a> {
    // FIXME: Remove IV and have the server generate it instead
    #[serde(with = "base64_array")]
    pub iv: [u8; 16],
    pub descriptor: Cow<'a, str>,
}

/// A request message to generate a data key made on behalf of a client
/// in the given dataset.
///
/// Requires the `data_key:generate` scope.
/// Response is a [GenerateKeyResponse].
///
/// See also [GenerateKeySpec].
#[derive(Debug, Serialize, Deserialize)]
pub struct GenerateKeyRequest<'a> {
    pub client_id: Uuid,
    pub dataset_id: Option<Uuid>,
    pub keys: Cow<'a, [GenerateKeySpec<'a>]>,
}

impl ViturRequest for GenerateKeyRequest<'_> {
    type Response = GenerateKeyResponse;

    const ENDPOINT: &'static str = "generate-data-key";
    const SCOPE: &'static str = "data_key:generate";
}

/// Returned type from a [RetrieveKeyRequest].
#[derive(Debug, Serialize, Deserialize)]
pub struct RetrievedKey {
    pub key_material: ViturKeyMaterial,
}

/// Response to a [RetrieveKeyRequest].
/// Contains a list of [RetrievedKey]s.
#[derive(Debug, Serialize, Deserialize)]
pub struct RetrieveKeyResponse {
    pub keys: Vec<RetrievedKey>,
}

impl ViturResponse for RetrieveKeyResponse {}

/// A specification for retrieving a data key used in a [RetrieveKeyRequest].
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct RetrieveKeySpec<'a> {
    #[serde(with = "base64_array")]
    pub iv: [u8; 16],
    pub descriptor: Cow<'a, str>,
    pub tag: Cow<'a, [u8]>,

    // Since this field will be removed in the future allow older versions of Vitur to be able to
    // parse a RetrieveKeySpec that doesn't include the tag_version.
    #[serde(default)]
    pub tag_version: usize,
}

/// Request to retrieve a data key on behalf of a client in the given dataset.
/// Requires the `data_key:retrieve` scope.
/// Response is a [RetrieveKeyResponse].
///
/// See also [RetrieveKeySpec].
#[derive(Debug, Serialize, Deserialize)]
pub struct RetrieveKeyRequest<'a> {
    pub client_id: Uuid,
    pub dataset_id: Option<Uuid>,
    pub keys: Cow<'a, [RetrieveKeySpec<'a>]>,
}

impl ViturRequest for RetrieveKeyRequest<'_> {
    type Response = RetrieveKeyResponse;

    const ENDPOINT: &'static str = "retrieve-data-key";
    const SCOPE: &'static str = "data_key:retrieve";
}

#[derive(Debug, Serialize, Deserialize)]
pub struct SaveConfigRequest<'a> {
    pub client_id: Uuid,
    #[serde(with = "base64_vec")]
    pub encrypted_index_root_key: Vec<u8>,
    pub dataset_config: Cow<'a, DatasetConfig>,
    pub dataset_id: Option<Uuid>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct SaveConfigResponse {}

impl ViturResponse for SaveConfigResponse {}

impl ViturRequest for SaveConfigRequest<'_> {
    type Response = SaveConfigResponse;

    const ENDPOINT: &'static str = "save-config";
    const SCOPE: &'static str = "config:write";
}

#[derive(Debug, Serialize, Deserialize)]
pub struct LoadConfigRequest {
    pub client_id: Uuid,
    pub dataset_id: Option<Uuid>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct LoadConfigResponse {
    #[serde(with = "base64_vec")]
    pub encrypted_index_root_key: Vec<u8>,
    pub dataset_config: DatasetConfig,
}

impl ViturResponse for LoadConfigResponse {}

impl ViturRequest for LoadConfigRequest {
    type Response = LoadConfigResponse;

    const ENDPOINT: &'static str = "load-config";
    const SCOPE: &'static str = "config:read";
}

/// Request message to disable a dataset.
/// Requires the `dataset:disable` scope.
/// Response is an [EmptyResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct DisableDatasetRequest {
    pub dataset_id: Uuid,
}

impl ViturRequest for DisableDatasetRequest {
    type Response = EmptyResponse;

    const ENDPOINT: &'static str = "disable-dataset";
    const SCOPE: &'static str = "dataset:disable";
}

/// Request message to enable a dataset that has was previously disabled.
/// Requires the `dataset:enable` scope.
/// Response is an [EmptyResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct EnableDatasetRequest {
    pub dataset_id: Uuid,
}

impl ViturRequest for EnableDatasetRequest {
    type Response = EmptyResponse;

    const ENDPOINT: &'static str = "enable-dataset";
    const SCOPE: &'static str = "dataset:enable";
}

/// Request message to modify a dataset with the given dataset_id.
/// `name` and `description` are optional and will be updated if provided.
///
/// Requires the `dataset:modify` scope.
/// Response is an [EmptyResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct ModifyDatasetRequest<'a> {
    pub dataset_id: Uuid,

    pub name: Option<Cow<'a, str>>,
    pub description: Option<Cow<'a, str>>,
}

impl ViturRequest for ModifyDatasetRequest<'_> {
    type Response = EmptyResponse;

    const ENDPOINT: &'static str = "modify-dataset";
    const SCOPE: &'static str = "dataset:modify";
}

/// Request message to grant a client access to a dataset.
/// Requires the `dataset:grant` scope.
///
/// Response is an [EmptyResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct GrantDatasetRequest {
    pub client_id: Uuid,
    pub dataset_id: Uuid,
}

impl ViturRequest for GrantDatasetRequest {
    type Response = EmptyResponse;

    const ENDPOINT: &'static str = "grant-dataset";
    const SCOPE: &'static str = "dataset:grant";
}

/// Request message to revoke a client's access to a dataset.
/// Requires the `dataset:revoke` scope.
/// Response is an [EmptyResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct RevokeDatasetRequest {
    pub client_id: Uuid,
    pub dataset_id: Uuid,
}

impl ViturRequest for RevokeDatasetRequest {
    type Response = EmptyResponse;

    const ENDPOINT: &'static str = "revoke-dataset";
    const SCOPE: &'static str = "dataset:revoke";
}

/// Request to load a dataset on behalf of a client.
/// This is used by clients before indexing or querying data and includes
/// key material which can be derived by the client to generate encrypted index terms.
///
/// If a dataset_id is not provided the client's default dataset will be loaded.
///
/// Requires the `data_key:retrieve` scope (though this may change in the future).
/// Response is a [LoadDatasetResponse].
#[derive(Debug, Serialize, Deserialize)]
pub struct LoadDatasetRequest {
    pub client_id: Uuid,
    pub dataset_id: Option<Uuid>,
}

impl ViturRequest for LoadDatasetRequest {
    type Response = LoadDatasetResponse;

    const ENDPOINT: &'static str = "load-dataset";
    // NOTE: We don't currently support the ability to allow an operation
    // based on any one of several possible scopes so we'll just use `data_key:retrieve` for now.
    // This should probably be allowed for any operation that requires indexing or querying.
    const SCOPE: &'static str = "data_key:retrieve";
}

/// Response to a [LoadDatasetRequest].
/// The response includes the key material required to derive data keys.
/// It is analogous to a [RetrieveKeyResponse] but where the server generated the key.
#[derive(Debug, Serialize, Deserialize)]
pub struct LoadDatasetResponse {
    pub partial_index_key: RetrievedKey,
    pub dataset: Dataset,
}

impl ViturResponse for LoadDatasetResponse {}