cosmian_kms_interfaces — Plugin & Store Abstractions

This crate defines the trait boundaries between the KMS server core and every pluggable backend: SQL/Redis databases, HSMs, and software crypto oracles.

Nothing in this crate performs I/O; it only declares types and async trait signatures that other crates must implement.

Module map

cosmian_kms_interfaces
├── stores/
│   ├── ObjectsStore        — CRUD + search for KMIP objects
│   ├── PermissionsStore    — grant / revoke / query access rights
│   └── ObjectWithMetadata  — thin wrapper: Object + owner + State + Attributes
├── hsm/
│   ├── HSM                 — raw PKCS#11-level interface (create, encrypt, sign …)
│   └── HsmStore          — ObjectsStore + CryptoOracle adapter backed by an HSM
└── CryptoOracle            — software/HSM encryption, decryption, signing by key prefix

Trait overview

Store traits

classDiagram
    class ObjectsStore {
        <<trait>>
        +create(uid, owner, object, attrs, tags)
        +retrieve(uid) ObjectWithMetadata
        +retrieve_tags(uid) HashSet~String~
        +update_object(uid, object, attrs, tags)
        +update_state(uid, state)
        +delete(uid)
        +atomic(ops Vec~AtomicOperation~)
        +is_object_owned_by(uid, owner) bool
        +find(requestor, state, attrs) Vec~ObjectWithMetadata~
        +find_wrapped_by(wrapping_key_uid, user)
    }

    class PermissionsStore {
        <<trait>>
        +list_user_operations_granted(user)
        +list_object_operations_granted(uid)
        +grant_operations(uid, user, ops)
        +remove_operations(uid, user, ops)
        +list_user_operations_on_object(uid, user)
    }

    class ObjectWithMetadata {
        +id() str
        +object() Object
        +owner() str
        +state() State
        +attributes() Attributes
    }

    ObjectsStore --> ObjectWithMetadata : returns

HSM & crypto-oracle traits

classDiagram
    class HSM {
        <<trait>>
        +get_available_slot_list() Vec~usize~
        +get_supported_algorithms(slot_id)
        +create_key(slot_id, algo, len, sensitive)
        +create_keypair(slot_id, algo, key_len)
        +export(slot_id, object_id) HsmObject
        +delete(slot_id, object_id)
        +find(slot_id, filter) Vec~HsmObject~
        +encrypt(slot_id, key_id, data, params)
        +decrypt(slot_id, key_id, data, params)
        +sign(slot_id, key_id, data, algo)
        +generate_random(slot_id, len)
    }

    class HsmProvider {
        <<trait>>
        +low-level PKCS11 calls
    }

    class BaseHsmP {
        +impl HSM for BaseHsm~P~
        where P: HsmProvider
    }

    class CryptoOracle {
        <<trait>>
        +encrypt(uid, data, params) EncryptedContent
        +decrypt(uid, data, params) Zeroizing~Vec~u8~~
        +get_key_type(uid) KeyType
        +get_key_metadata(uid) KeyMetadata
        +sign(uid, data, algo)
    }

    class HsmStore {
        +Arc~dyn HSM~
        +Clone
        +impl ObjectsStore for HsmStore
        +impl CryptoOracle for HsmStore
    }

    HSM <|.. BaseHsmP : implements
    HsmProvider <|.. BaseHsmP : bounds P
    BaseHsmP --> HsmStore : wrapped in Arc
    HsmStore ..|> ObjectsStore : implements
    HsmStore ..|> CryptoOracle : implements

Global overview — who implements and who consumes

The diagram reads left-to-right: implementors on the left drive through the trait layer (centre) into the consumers on the right.

flowchart LR
    subgraph impl_db["SQL / KV backends<br/>(server_database)"]
        SQ["SQLite · PostgreSQL<br/>MySQL / MariaDB"]
        RD["Redis + Findex"]
    end

    subgraph impl_hsm["HSM chain"]
        PROV["5 × HsmProvider<br/>(pkcs11 loader crates)"]
        BH["BaseHsm&lt;P&gt;"]
        HB["HsmStore"]
    end

    subgraph traits["cosmian_kms_interfaces"]
        OS[ObjectsStore]
        PS[PermissionsStore]
        CO[CryptoOracle]
        HSMt[HSM]
    end

    subgraph consumers["cosmian_kms_server"]
        DB["Database struct"]
        KMS["KMS struct"]
    end

    SQ   -->|"OS + PS"| OS & PS
    RD   -->|"OS + PS"| OS & PS

    PROV -->|"impl HsmProvider"| BH
    BH   -->|"impl HSM"| HSMt
    HSMt -->|"Arc&lt;dyn HSM&gt;"| HB
    HB   -->|"impl OS"| OS
    HB   -->|"impl CO"| CO

    OS   -->|"Arc&lt;dyn&gt;"| DB
    PS   -->|"Arc&lt;dyn&gt;"| DB
    DB   -->|field| KMS
    CO   -->|"Box&lt;dyn&gt;"| KMS
    HSMt -->|"Option&lt;Arc&lt;dyn&gt;&gt;"| KMS

Store backends

All SQL engines implement ObjectsStore and PermissionsStore. Redis implements the same two traits.

flowchart LR
    subgraph backends["cosmian_kms_server_database"]
        SQ_S[SqlitePool]
        SQ_P[PgPool]
        SQ_M["MySqlPool / MariaDB"]
        RD[RedisWithFindex]
    end

    OS[ObjectsStore]
    PS[PermissionsStore]

    SQ_S & SQ_P & SQ_M -->|impl| OS & PS
    RD                  -->|impl| OS & PS

HSM chain

Five provider crates each implement HsmProvider. BaseHsm<P> uses that bound to satisfy HSM. A single HsmStore wraps the resulting Arc<dyn HSM> and is Cloned to fill both the object-store map and the crypto-oracle map in KMS::instantiate().

flowchart LR
    subgraph providers["PKCS#11 loader crates"]
        SFT[softhsm2]
        UTI[utimaco]
        PRT[proteccio]
        C2P[crypt2pay]
        SCH[smartcard-hsm]
    end

    subgraph base["cosmian_kms_base_hsm"]
        BH["BaseHsm<P: HsmProvider>"]
    end

    subgraph iface["cosmian_kms_interfaces"]
        HSMt["HSM trait"]
        HB["HsmStore (Clone)"]
        OS[ObjectsStore]
        CO[CryptoOracle]
    end

    SFT & UTI & PRT & C2P & SCH -->|"impl HsmProvider"| BH
    BH  -->|"impl HSM"| HSMt
    HSMt -->|"Arc<dyn HSM>"| HB
    HB  -->|"impl"| OS
    HB  -->|"impl"| CO

Key types

Adding a new backend

1. Add a crate dependency on cosmian_kms_interfaces.
2. Implement ObjectsStore and PermissionsStore (required for SQL/KV stores).
3. For HSM backends: implement HsmProvider in a new *_pkcs11_loader crate; BaseHsm<YourProvider> then automatically satisfies HSM, and HsmStore::new() becomes usable as bothObjectsStoreandCryptoOracle` without further code.
4. Register the backend in cosmian_kms_server_database (SQL) or KMS::instantiate() (HSM / crypto oracle).