diff --git a/.github/reusable_scripts b/.github/reusable_scripts index 85ae8439bc..5216e05f11 160000 --- a/.github/reusable_scripts +++ b/.github/reusable_scripts @@ -1 +1 @@ -Subproject commit 85ae8439bc0326e43d2f9d0c8102a73487a51e68 +Subproject commit 5216e05f11e37c472d75dac40818ea9e02c857dc diff --git a/CHANGELOG/feat_split_key.md b/CHANGELOG/feat_split_key.md new file mode 100644 index 0000000000..2b4c5a70c4 --- /dev/null +++ b/CHANGELOG/feat_split_key.md @@ -0,0 +1,162 @@ +# CHANGELOG — feat/split_key + +## Documentation + +- **Four-role ceremony guide** (`documentation/docs/configuration/authorization/key_ceremony.md`): + renamed from "Administrator Key Ceremony" to "Role Management and Key Ceremonies"; added full + **Auditor role** section (NIST SP 800-57 Part 2 Rev 1 §4.9) covering both config-only + and ceremony-gated modes, 4-phase Mermaid sequence diagrams, `x-cosmian-auditor-ceremony` vendor + attribute tag, CLI quick reference (`ckms access-rights auditor status/disable`), and updated + Security Properties and Permission Model sections. Updated normative requirements table with + NIST SP 800-57 Part 2 Rev 1 §4.9 entries. +- **Administrator key ceremony guide** (same file): + full explanation of privilege escalation via split-key ceremony, normative references (NIST SP 800-57 Part 2 Rev 1 §4.6, + ISO/IEC 19790 §7.4, ANSI/INCITS 359-2004), role operation tables, 4-phase Mermaid sequence diagrams, and + permission evaluation flowchart. Registered in `documentation/mkdocs.yml`. +- `documentation/docs/configuration/authorization.md`: replaced stale **Super-admin role** section + with correct **Administrator role** section covering `administrator_*` config keys, activation + modes, ceremony flow, disable procedures, actual REST endpoints (`/access/administrator/*`), + and updated permission evaluation order table. + +## Features — Web UI + +- **Administrator Role page** (`/ui/access-rights/administrator`): new status page showing role + configuration, ceremony activation state, list of admin users, and a Disable button (visible + only when a ceremony is active; requires active Administrator privileges to use). +- **Auditor Role page** (`/ui/access-rights/auditor`): equivalent status page for the Auditor role; + Disable button requires active Administrator privileges (an Auditor cannot revoke their own + ceremony — enforced in both UI and server). +- Both pages wired into the **Access Rights** sidebar section with two new menu items and + React Router routes. No server-side SPA route change needed (existing wildcard covers them). + +## Features — CLI + +- `ckms access-rights administrator status` — print Administrator role configuration and + ceremony activation status (calls `GET /access/administrator/status`). +- `ckms access-rights administrator disable` — revoke an active Administrator ceremony + (calls `POST /access/administrator/disable`; requires active Administrator). +- `ckms access-rights auditor status` — print Auditor role configuration and ceremony status. +- `ckms access-rights auditor disable` — revoke an active Auditor ceremony (requires active + Administrator; an Auditor cannot disable their own ceremony). +- CLI docs regenerated in `cli_documentation/docs/main_commands.md`. + +- **Unified Administrator role**: merged the separate `SuperAdminConfig` and + `administrator_users` into a single `AdministratorConfig` within `RoleConfig`. + The Administrator role now provides both operation bypass (all 23 KMIP ops) AND + ownership bypass (access any object without grant) in one coherent concept. + References: NIST SP 800-57 Part 2 Rev 1 §4.6 (Dual Control), ANSI/INCITS 359-2004 §4.3. +- **Renamed `super_admin` → `administrator` across the entire stack**: DB trait methods, + route paths, ceremony attributes, config fields, test infra, SQL table + (`administrator_activations`), SQL query names, test vector directories, and config files. + Removed residual `SuperAdminConfig` dead code (`super_admin_config.rs`). + +## Security + +- Administrator access is audit-logged at `WARN` level (`ADMINISTRATOR_ACCESS`, `ADMINISTRATOR_DISABLED`). +- Ceremony activation record stores a SHA-256 fingerprint of the reconstructed secret. +- Config-only mode provides always-on access; ceremony mode provides defence-in-depth. +- **Fail-secure unenrolled users**: when role enforcement is active, users not listed in any + role now default to Operator (minimum privilege) instead of being unrestricted. + Per NIST SP 800-57 Part 2 Rev 1 §4.8 (access control / need-to-know). +- **Ceremony initiator check**: `JoinSplitKey` verifies the **assembling user** is in + `administrator_users` before activating the Administrator ceremony. +- **Administrator bypass excludes HSM-backed keys**: HSM objects continue to use their own + admin rules; the Administrator bypass applies only to non-HSM Managed Objects. +- **`role_for()` ceremony guard**: when `administrator_require_ceremony = true`, ceremony + candidates are not granted Administrator privileges at dispatch time until the DB-backed + `is_administrator()` check confirms the ceremony has been completed. +- **Role separation validation**: `RoleConfig::validate()` rejects configs where a user + appears in multiple role lists (ISO/IEC 19790 §7.4 separation of duty). + +## Bug Fixes + +- **`create_split_key`: ceremony auto-tag now applies regardless of caller identity**: + Previously, the server only auto-tagged split-key shares with the ceremony + attribute when the *calling user* was in `super_admin.users`. Because the master key is always + created by the *owner* (not the super-admin user), the auto-tag was silently skipped and the + ceremony could never activate. Fixed: when `require_ceremony = true`, every + `CreateSplitKey` operation produces ceremony-tagged shares unconditionally. + +## Features + +- **3-role RBAC system** (ISO/IEC 19790 §7.4, KMIP 2.1 §9, ANSI/INCITS 359-2004): introduced + `Role` enum and `RoleConfig` struct with `AdministratorConfig`. `privileged_users` renamed + to `crypto_officer_users`; new `operator_users` and `administrator` fields. + Role enforcement happens at dispatch time before any object-level permission check. + ([#651](https://github.com/Cosmian/kms/issues/651)) +- **Administrator role**: server-wide privilege granting full owner-equivalent access to all + Managed Objects in the KMS, regardless of ownership or delegation grants. Bypasses + `user_has_permission()` and the `Locate` ownership filter. +- **Split-key ceremony (XOR n-of-n)**: two KMIP 2.1 operations — + `CreateSplitKey` and `JoinSplitKey` — implement XOR-based split knowledge (all shares required). + The ceremony mode requires all $n$ custodians to submit shares before the Administrator role activates. +- **`GET /access/administrator/status`**: returns current Administrator configuration and + ceremony activation state (available to any authenticated user). +- **`POST /access/administrator/disable`**: revokes an active ceremony activation (caller must + be an active Administrator; ceremony mode only). +- **`super_admin_activations` table**: DB table (SQLite / PostgreSQL / MySQL) persisting + ceremony activation events (activated\_by, participants, key\_hash, revoked\_at / revoked\_by). +- **`find_all()`** on `ObjectsStore` / database: super-admin `Locate` path that returns all + matching objects without user ownership filtering. +- **`[super_admin]` TOML section**: new server configuration block with `users`, + `require_split_key_ceremony`, `split_key_threshold`, and `split_key_total_parts` fields. + +## Testing + +- **7 new test vectors** for the super-admin and split-key ceremony feature: + - `access_control/super_admin_config_only` — config-only mode, user Gets owner's key + - `access_control/super_admin_locate_all` — super-admin Locate sees all owners' objects + - `access_control/super_admin_ceremony_disable` — full ceremony lifecycle: activate → access → disable → denied + - `fips/kmip_operations/create_split_key_xor` — XOR n-of-n round-trip (CreateSplitKey + JoinSplitKey) + - `fips/kmip_operations/create_split_key_xor` — XOR 2-of-2 round-trip + - `negative/create_split_key_threshold_too_low` — threshold=1 → InvalidRequest + - `negative/create_split_key_parts_less_than_threshold` — parts(3) < threshold(5) → InvalidRequest +- New `CaptureNthEntry` / `capture_nth` manifest field in the vector runner to capture the Nth + occurrence of a repeated TTLV tag (needed for individual share UIDs from `CreateSplitKeyResponse`). +- New `SuperAdminStatus` / `SuperAdminDisable` step operations in the vector runner routing to + the flat-JSON REST endpoints (`GET /access/super-admin/status`, `POST /access/super-admin/disable`). +- Two new server config TOMLs: `cert_auth_super_admin.toml` (config-only, port 9997) and + `cert_auth_super_admin_ceremony.toml` (ceremony mode, port 9996). + +## Features — Auditor Role + +- **Auditor role** (NIST SP 800-57 Part 2 Rev 1 §4.9): new read-only role that + can inspect metadata on **all** objects in the KMS (Locate, GetAttributes, Validate only). + Strictly blocked from key material access (Get, Export), crypto ops (Encrypt, Decrypt, + Sign, MAC), and lifecycle mutations (Create, Destroy, Revoke, Activate). +- **Config-only mode**: `auditor_users = ["user@example.com"]` with + `auditor_require_ceremony = false` grants immediate Auditor access. +- **Ceremony mode**: `auditor_require_ceremony = true` + split-key ceremony activation + via `JoinSplitKey` (same pattern as Administrator ceremony but with + `x-cosmian-auditor-ceremony` vendor attribute). +- **`GET /access/auditor/status`**: returns current Auditor configuration and ceremony + activation state. +- **`POST /access/auditor/disable`**: revokes an active Auditor ceremony (caller must be + an active Administrator). +- **Role enforcement in RequestMessage path**: `check_role_permission` is now called from + `process_operation()` (message.rs) in addition to `dispatch_inner()`, ensuring consistent + RBAC enforcement regardless of request format (single-operation TTLV or batched RequestMessage). + +## Security — Auditor + +- Auditor role is **dispatch-gated**: unlike Operator/CryptoOfficer which defer to handler + checks, Auditor operations are blocked at the dispatch layer (the only gate). +- Auditor ceremony candidates are exempt from the `JoinSplitKey` create-permission check + (same pattern as Administrator candidates). +- Non-auditor users cannot complete the Auditor ceremony (`JoinSplitKey` rejects if the + assembling user is not in `auditor.users`). +- Role separation enforced: `RoleConfig::validate()` rejects configs where a user appears + in both `auditor_users` and any other role list. + +## Testing — Auditor + +- **7 new test vectors** for the Auditor role and role-separation-of-duty: + - `access_control/auditor_config_only_allowed` — Auditor can Locate and GetAttributes on any object + - `access_control/auditor_config_only_blocked_keymat` — Auditor blocked from Get, Encrypt, Create, Destroy + - `access_control/auditor_ceremony_activate` — full ceremony lifecycle: split → grant → join → audit → blocked + - `access_control/auditor_ceremony_blocked_before_activation` — Auditor candidate has no bypass before ceremony + - `access_control/operator_role_blocked_lifecycle` — Operator cannot CreateKeyPair or CreateSplitKey + - `access_control/crypto_officer_role_allowed_ops` — CryptoOfficer can Create, CreateKeyPair, Get, Destroy + - `access_control/privilege_escalation_auditor_ceremony_wrong_user` — non-auditor cannot activate ceremony +- 4 new server config TOMLs: `cert_auth_auditor.toml`, `cert_auth_auditor_ceremony.toml`, + `cert_auth_auditor_ceremony_fresh.toml`, `cert_auth_operator_and_crypto_officer.toml`. diff --git a/Cargo.lock b/Cargo.lock index c52d4f78f6..3bf8561cf9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1347,6 +1347,7 @@ dependencies = [ "p256", "rand 0.10.1", "rand_chacha 0.10.0", + "rand_core 0.10.1", "rand_distr", "regex", "rust-ini", @@ -1418,6 +1419,8 @@ dependencies = [ "opentelemetry_sdk", "pem", "proteccio_pkcs11_loader", + "rand 0.10.1", + "rand_chacha 0.10.0", "reqwest", "scratchstack-aws-signature", "serde", @@ -1445,6 +1448,7 @@ name = "cosmian_kms_server_database" version = "5.24.0" dependencies = [ "async-trait", + "base64 0.22.1", "cosmian_findex", "cosmian_kmip", "cosmian_kms_crypto", @@ -1452,6 +1456,7 @@ dependencies = [ "cosmian_logger", "cosmian_sse_memories", "deadpool-postgres", + "hex", "moka", "mysql_async", "openssl", diff --git a/cli_documentation/docs/main_commands.md b/cli_documentation/docs/main_commands.md new file mode 100644 index 0000000000..214f63967c --- /dev/null +++ b/cli_documentation/docs/main_commands.md @@ -0,0 +1,3334 @@ + +## ckms + +Command Line Interface used to manage the Cosmian KMS server. + +If any assistance is needed, please either visit the Cosmian technical documentation at +or contact the Cosmian support team on Discord + +### Usage + +`ckms [options]` + +### Arguments + +`--conf-path [-c] ` Configuration file location + +`--url ` The URL of the KMS + +`--print-json ` Output the KMS JSON KMIP request and response. This is useful to understand JSON POST requests and responses required to programmatically call the KMS on the `/kmip/2_1` endpoint + +Possible values: `"true", "false"` + +`--accept-invalid-certs ` Allow to connect using a self-signed cert or untrusted cert chain + +Possible values: `"true", "false"` + +`--header [-H] ` Add a custom HTTP header to every request sent to the KMS server. + +`--proxy-url ` The proxy URL: + +- e.g., `https://secure.example` for an HTTP proxy +- e.g., `socks5://192.168.1.1:9000` for a SOCKS proxy + +`--proxy-basic-auth-username ` Set the Proxy-Authorization header username using Basic auth. + +`--proxy-basic-auth-password ` Set the Proxy-Authorization header password using Basic auth. + +`--proxy-custom-auth-header ` Set the Proxy-Authorization header to a specified value. + +`--proxy-exclusion-list ` The No Proxy exclusion list to this Proxy + +### Subcommands + +**`access-rights`** [[1]](#1-ckms-access-rights) Manage the users' access rights to the cryptographic objects + +**`attributes`** [[2]](#2-ckms-attributes) Get/Set/Delete/Modify the KMIP object attributes + +**`azure`** [[3]](#3-ckms-azure) Support for Azure specific interactions + +**`aws`** [[4]](#4-ckms-aws) Support for AWS specific interactions + +**`bench`** [[5]](#5-ckms-bench) Run benchmarks using criterion for statistical analysis. + +**`certificates`** [[6]](#6-ckms-certificates) Manage certificates. Create, import, destroy and revoke. Encrypt and decrypt data + +**`cng`** [[7]](#7-ckms-cng) Manage the Windows CNG Key Storage Provider (KSP) + +**`derive-key`** [[8]](#8-ckms-derive-key) Derive a new key from an existing key + +**`ec`** [[9]](#9-ckms-ec) Manage elliptic curve keys. Encrypt and decrypt data using ECIES + +**`google`** [[10]](#10-ckms-google) Manage google elements. Handle key pairs and identities from Gmail API + +**`locate`** [[11]](#11-ckms-locate) Locate cryptographic objects inside the KMS + +**`login`** [[12]](#12-ckms-login) Login to the Identity Provider of the KMS server using the `OAuth2` authorization code flow. + +**`logout`** [[13]](#13-ckms-logout) Logout from the Identity Provider + +**`hash`** [[14]](#14-ckms-hash) Hash arbitrary data. + +**`mac`** [[15]](#15-ckms-mac) MAC utilities: compute or verify a MAC value. + +**`rng`** [[16]](#16-ckms-rng) RNG utilities: retrieve random bytes or seed RNG + +**`server`** [[17]](#17-ckms-server) Server-related commands + +**`rsa`** [[18]](#18-ckms-rsa) Manage RSA keys. Encrypt and decrypt data using RSA keys + +**`opaque-object`** [[19]](#19-ckms-opaque-object) Create, import, export, revoke and destroy Opaque Objects + +**`pkcs11`** [[20]](#20-ckms-pkcs11) Verify PKCS#11 shared library integration + +**`secret-data`** [[21]](#21-ckms-secret-data) Create, import, export and destroy secret data + +**`sym`** [[22]](#22-ckms-sym) Manage symmetric keys. Encrypt and decrypt data + +**`markdown`** [[23]](#23-ckms-markdown) Regenerate the CLI documentation in Markdown format + +**`configure`** [[24]](#24-ckms-configure) Configure the KMS CLI (create ckms.toml) + +--- + +## 1 ckms access-rights + +Manage the users' access rights to the cryptographic objects + +### Usage + +`ckms access-rights ` + +### Subcommands + +**`grant`** [[1.1]](#11-ckms-access-rights-grant) Grant another user one or multiple access rights to an object + +**`revoke`** [[1.2]](#12-ckms-access-rights-revoke) Revoke another user one or multiple access rights to an object + +**`list`** [[1.3]](#13-ckms-access-rights-list) List the access rights granted on an object to other users + +**`owned`** [[1.4]](#14-ckms-access-rights-owned) List the objects owned by the calling user + +**`obtained`** [[1.5]](#15-ckms-access-rights-obtained) List the access rights obtained by the calling user + +**`crypto-officer`** [[1.6]](#16-ckms-access-rights-crypto-officer) Query or manage the Crypto Officer role + +--- + +## 1.1 ckms access-rights grant + +Grant another user one or multiple access rights to an object + +### Usage + +`ckms access-rights grant [options] + ... +` + +### Arguments + +`` The user identifier to allow + +`--object-uid [-i] ` The object unique identifier stored in the KMS + +`` The operations to grant (`create`, `get`, `encrypt`, `decrypt`, `import`, `revoke`, `locate`, `rekey`, `destroy`, `get_attributes`) + +--- + +## 1.2 ckms access-rights revoke + +Revoke another user one or multiple access rights to an object + +### Usage + +`ckms access-rights revoke [options] + ... +` + +### Arguments + +`` The user to revoke access to + +`--object-uid [-i] ` The object unique identifier stored in the KMS + +`` The operations to revoke (`create`, `get`, `encrypt`, `decrypt`, `import`, `revoke`, `locate`, `rekey`, `destroy`) + +--- + +## 1.3 ckms access-rights list + +List the access rights granted on an object to other users + +### Usage + +`ckms access-rights list [options] +` + +### Arguments + +`` The object unique identifier + +--- + +## 1.4 ckms access-rights owned + +List the objects owned by the calling user + +### Usage + +`ckms access-rights owned` + +--- + +## 1.5 ckms access-rights obtained + +List the access rights obtained by the calling user + +### Usage + +`ckms access-rights obtained` + +--- + +## 1.6 ckms access-rights crypto-officer + +Query or manage the Crypto Officer role + +### Usage + +`ckms access-rights crypto-officer ` + +### Subcommands + +**`status`** [[1.6.1]](#161-ckms-access-rights-crypto-officer-status) Print the current Crypto Officer role configuration and ceremony activation status + +**`disable`** [[1.6.2]](#162-ckms-access-rights-crypto-officer-disable) Disable an active Crypto Officer ceremony (requires active Crypto Officer privileges) + +--- + +## 1.6.1 ckms access-rights crypto-officer status + +Print the current Crypto Officer role configuration and ceremony activation status + +### Usage + +`ckms access-rights crypto-officer status` + +--- + +## 1.6.2 ckms access-rights crypto-officer disable + +Disable an active Crypto Officer ceremony (requires active Crypto Officer privileges) + +### Usage + +`ckms access-rights crypto-officer disable` + +--- + +## 2 ckms attributes + +Get/Set/Delete/Modify the KMIP object attributes + +### Usage + +`ckms attributes ` + +### Subcommands + +**`get`** [[2.1]](#21-ckms-attributes-get) Get the KMIP object attributes and tags. + +**`set`** [[2.2]](#22-ckms-attributes-set) Set the KMIP object attributes. + +**`delete`** [[2.3]](#23-ckms-attributes-delete) Delete the KMIP object attributes. + +**`modify`** [[2.4]](#24-ckms-attributes-modify) Modify existing KMIP object attributes. + +--- + +## 2.1 ckms attributes get + +Get the KMIP object attributes and tags. + +### Usage + +`ckms attributes get [options]` + +### Arguments + +`--id [-i] ` The unique identifier of the cryptographic object. If not specified, tags should be specified + +`--tag [-t] ` Tag to use to retrieve the key when no key id is specified. To specify multiple tags, use the option multiple times + +`--attribute [-a] ` The KMIP attribute to retrieve. +To specify multiple attributes, use the option multiple times. +If not specified, all possible attributes are returned. +To retrieve the tags, use `Tag` as an attribute value. + +`--link-type [-l] ` Filter on retrieved links. Only if KMIP tag `LinkType` is used in `attribute` parameter. +To specify multiple attributes, use the option multiple times. +If not specified, all possible link types are returned. + +Possible values: `"certificate", "public-key", "private-key", "derivation-base-object", "derived-key", "replacement-object", "replaced-object", "parent", "child", "previous", "next", "pkcs12-certificate", "pkcs12-password", "wrapping-key"` + +`--output-file [-o] ` An optional file where to export the attributes. +The attributes will be in JSON TTLV format. + +--- + +## 2.2 ckms attributes set + +Set the KMIP object attributes. + +### Usage + +`ckms attributes set [options]` + +### Arguments + +`--id [-i] ` The unique identifier of the cryptographic object. If not specified, tags should be specified + +`--tag [-t] ` Tag to use to retrieve the key when no key id is specified. To specify multiple tags, use the option multiple times + +`--activation-date [-d] ` Set the activation date of the key. Epoch time (or Unix time) in milliseconds + +`--cryptographic-algorithm [-a] ` The cryptographic algorithm used by the key + +Possible values: `"aes", "rsa", "ecdsa", "ecdh", "ec", "chacha20", "chacha20-poly1305", "sha3224", "sha3256", "sha3384", "sha3512", "ed25519", "ed448", "covercrypt", "covercrypt-bulk"` + +`--cryptographic-length ` The length of the cryptographic key + +`--key-usage [-u] ` The key usage. Add multiple times to specify multiple key usages + +Possible values: `"sign", "verify", "encrypt", "decrypt", "wrap-key", "unwrap-key", "mac-generate", "mac-verify", "derive-key", "key-agreement", "certificate-sign", "crl-sign", "authenticate", "unrestricted"` + +`--public-key-id ` The link to the corresponding public key id if any + +`--private-key-id ` The link to the corresponding private key id if any + +`--certificate-id ` The link to the corresponding certificate id if any + +`--p12-id ` The link to the corresponding PKCS12 certificate id if any + +`--p12-pwd ` The link to the corresponding PKCS12 password certificate if any + +`--parent-id ` The link to the corresponding parent id if any + +`--child-id ` The link to the corresponding child id if any + +`--name ` The name of the object (standard KMIP Name attribute). The name is stored as an `UninterpretedTextString` by default + +`--vendor-identification [-v] ` The vendor identification + +`--attribute-name [-n] ` The attribute name + +`--attribute-value ` The attribute value (in hex format) + +--- + +## 2.3 ckms attributes delete + +Delete the KMIP object attributes. + +### Usage + +`ckms attributes delete [options]` + +### Arguments + +`--id [-i] ` The unique identifier of the cryptographic object. If not specified, tags should be specified + +`--tag [-t] ` Tag to use to retrieve the key when no key id is specified. To specify multiple tags, use the option multiple times + +`--activation-date [-d] ` Set the activation date of the key. Epoch time (or Unix time) in milliseconds + +`--cryptographic-algorithm [-a] ` The cryptographic algorithm used by the key + +Possible values: `"aes", "rsa", "ecdsa", "ecdh", "ec", "chacha20", "chacha20-poly1305", "sha3224", "sha3256", "sha3384", "sha3512", "ed25519", "ed448", "covercrypt", "covercrypt-bulk"` + +`--cryptographic-length ` The length of the cryptographic key + +`--key-usage [-u] ` The key usage. Add multiple times to specify multiple key usages + +Possible values: `"sign", "verify", "encrypt", "decrypt", "wrap-key", "unwrap-key", "mac-generate", "mac-verify", "derive-key", "key-agreement", "certificate-sign", "crl-sign", "authenticate", "unrestricted"` + +`--public-key-id ` The link to the corresponding public key id if any + +`--private-key-id ` The link to the corresponding private key id if any + +`--certificate-id ` The link to the corresponding certificate id if any + +`--p12-id ` The link to the corresponding PKCS12 certificate id if any + +`--p12-pwd ` The link to the corresponding PKCS12 password certificate if any + +`--parent-id ` The link to the corresponding parent id if any + +`--child-id ` The link to the corresponding child id if any + +`--name ` The name of the object (standard KMIP Name attribute). The name is stored as an `UninterpretedTextString` by default + +`--vendor-identification [-v] ` The vendor identification + +`--attribute-name [-n] ` The attribute name + +`--attribute-value ` The attribute value (in hex format) + +`--attribute ` The attributes or tags to retrieve. +To specify multiple attributes, use the option multiple times. + +--- + +## 2.4 ckms attributes modify + +Modify existing KMIP object attributes. + +### Usage + +`ckms attributes modify [options]` + +### Arguments + +`--id [-i] ` The unique identifier of the cryptographic object. If not specified, tags should be specified + +`--tag [-t] ` Tag to use to retrieve the key when no key id is specified. To specify multiple tags, use the option multiple times + +`--activation-date [-d] ` Set the activation date of the key. Epoch time (or Unix time) in milliseconds + +`--cryptographic-algorithm [-a] ` The cryptographic algorithm used by the key + +Possible values: `"aes", "rsa", "ecdsa", "ecdh", "ec", "chacha20", "chacha20-poly1305", "sha3224", "sha3256", "sha3384", "sha3512", "ed25519", "ed448", "covercrypt", "covercrypt-bulk"` + +`--cryptographic-length ` The length of the cryptographic key + +`--key-usage [-u] ` The key usage. Add multiple times to specify multiple key usages + +Possible values: `"sign", "verify", "encrypt", "decrypt", "wrap-key", "unwrap-key", "mac-generate", "mac-verify", "derive-key", "key-agreement", "certificate-sign", "crl-sign", "authenticate", "unrestricted"` + +`--public-key-id ` The link to the corresponding public key id if any + +`--private-key-id ` The link to the corresponding private key id if any + +`--certificate-id ` The link to the corresponding certificate id if any + +`--p12-id ` The link to the corresponding PKCS12 certificate id if any + +`--p12-pwd ` The link to the corresponding PKCS12 password certificate if any + +`--parent-id ` The link to the corresponding parent id if any + +`--child-id ` The link to the corresponding child id if any + +`--name ` The name of the object (standard KMIP Name attribute). The name is stored as an `UninterpretedTextString` by default + +`--vendor-identification [-v] ` The vendor identification + +`--attribute-name [-n] ` The attribute name + +`--attribute-value ` The attribute value (in hex format) + +--- + +## 3 ckms azure + +Support for Azure specific interactions + +### Usage + +`ckms azure ` + +### Subcommands + +**`byok`** [[3.1]](#31-ckms-azure-byok) Azure BYOK support. See: + +--- + +## 3.1 ckms azure byok + +Azure BYOK support. See: + +### Usage + +`ckms azure byok ` + +### Subcommands + +**`import`** [[3.1.1]](#311-ckms-azure-byok-import) Import into the KMS an RSA Key Encryption Key (KEK) generated on Azure Key Vault. +See: + +**`export`** [[3.1.2]](#312-ckms-azure-byok-export) Wrap a KMS key with an Azure Key Encryption Key (KEK), +previously imported using the `ckms azure byok import` command. +Generate the `.byok` file that can be used to import the KMS key into Azure Key Vault. +See: + +--- + +## 3.1.1 ckms azure byok import + +Import into the KMS an RSA Key Encryption Key (KEK) generated on Azure Key Vault. +See: + +### Usage + +`ckms azure byok import [options] + + [KEY_ID] +` + +### Arguments + +`` The RSA Key Encryption Key (KEK) file exported from the Azure Key Vault in PKCS#8 PEM format + +`` The Azure Key ID (kid). It should be something like: + + +`` The unique ID of the key in this KMS; a random UUID is generated if not specified + +--- + +## 3.1.2 ckms azure byok export + +Wrap a KMS key with an Azure Key Encryption Key (KEK), +previously imported using the `ckms azure byok import` command. +Generate the `.byok` file that can be used to import the KMS key into Azure Key Vault. +See: + +### Usage + +`ckms azure byok export [options] + + [BYOK_FILE] +` + +### Arguments + +`` The unique ID of the KMS private key that will be wrapped and then exported + +`` The Azure KEK ID in this KMS + +`` The file path to export the `.byok` file to. If not specified, the file will be called `.byok` + +--- + +## 4 ckms aws + +Support for AWS specific interactions + +### Usage + +`ckms aws ` + +### Subcommands + +**`byok`** [[4.1]](#41-ckms-aws-byok) AWS BYOK support. See: + +--- + +## 4.1 ckms aws byok + +AWS BYOK support. See: + +### Usage + +`ckms aws byok ` + +### Subcommands + +**`import`** [[4.1.1]](#411-ckms-aws-byok-import) Import an AWS Key Encryption Key (KEK) into the KMS. + +**`export`** [[4.1.2]](#412-ckms-aws-byok-export) Wrap a KMS key with an AWS Key Encryption Key (KEK). + +--- + +## 4.1.1 ckms aws byok import + +Import an AWS Key Encryption Key (KEK) into the KMS. + +### Usage + +`ckms aws byok import [options]` + +### Arguments + +`--kek-base64 [-b] ` The RSA Key Encryption public key (the KEK) as a base64-encoded string + +`--kek-file [-f] ` In case of KEK provided as a file blob + +`--wrapping-algorithm [-w] ` +Possible values: `"RSAES_OAEP_SHA_1", "RSAES_OAEP_SHA_256", "RSA_AES_KEY_WRAP_SHA_1", "RSA_AES_KEY_WRAP_SHA_256"` + +`--key-arn [-a] ` The Amazon Resource Name (key ARN) of the KMS key. It's recommended to provide it for an easier export later + +`--key-id [-i] ` The unique ID of the key in this KMS; a random UUID is generated if not specified + +--- + +## 4.1.2 ckms aws byok export + +Wrap a KMS key with an AWS Key Encryption Key (KEK). + +### Usage + +`ckms aws byok export [options] + + [TOKEN_FILE_PATH] + [OUTPUT_FILE_PATH] +` + +### Arguments + +`` The unique ID of the KMS private key that will be wrapped and then exported + +`` The AWS KEK ID in this KMS + +`` The file path containing the import token previously generated when importing the KEK. This file isn't read and neither used by the KMS, it's simply for providing copy-paste ready output for aws cli users upon a successful key material wrapping + +`` If not specified, a base64 encoded blob containing the key material will be printed to stdout. Can be piped to desired file or command + +--- + +## 5 ckms bench + +Run benchmarks using criterion for statistical analysis. + +### Usage + +`ckms bench [options]` + +### Arguments + +`--mode [-m] ` Benchmark category (default: all) + +Possible values: `"all", "encrypt", "key-creation", "sign-verify", "batch"` [default: `"all"`] + +`--format [-f] ` Output format + +Possible values: `"text", "json", "markdown", "compact", "html"` [default: `"text"`] + +`--speed [-s] ` Benchmark speed mode: normal (default), quick, or sanity. Sanity auto-selects --format compact when no explicit format is given + +Possible values: `"normal", "quick", "sanity"` [default: `"normal"`] + +`--time [-t]