From e7e879e937c06b9c2a15e16cce210e1447434598 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Mon, 15 Jul 2024 15:59:56 -0400 Subject: [PATCH 1/3] Updates for KES release 2024-06-17T15-47-05Z Closes #58 Changes for deprecating several `ls` commands Updates to the kes identity command Fix for kes identity new example --- .../ls.md => deprecated/identity-ls.md} | 5 ++ .../{kes-key/ls.md => deprecated/key-ls.md} | 5 ++ .../ls.md => deprecated/policy-ls.md} | 5 ++ content/cli/kes-identity/_index.md | 38 ++++++++-- content/cli/kes-identity/new.md | 2 +- content/cli/kes-key/_index.md | 7 +- content/cli/kes-ls/_index.md | 71 +++++++++++++++++++ content/cli/kes-policy/_index.md | 8 ++- content/concepts/environment-variables.md | 10 +++ 9 files changed, 142 insertions(+), 9 deletions(-) rename content/cli/{kes-identity/ls.md => deprecated/identity-ls.md} (80%) rename content/cli/{kes-key/ls.md => deprecated/key-ls.md} (82%) rename content/cli/{kes-policy/ls.md => deprecated/policy-ls.md} (80%) create mode 100644 content/cli/kes-ls/_index.md diff --git a/content/cli/kes-identity/ls.md b/content/cli/deprecated/identity-ls.md similarity index 80% rename from content/cli/kes-identity/ls.md rename to content/cli/deprecated/identity-ls.md index 558fcea..445cff6 100644 --- a/content/cli/kes-identity/ls.md +++ b/content/cli/deprecated/identity-ls.md @@ -6,6 +6,11 @@ draft: false tableOfContents: true --- +{{< admonition title="Command deprecated" type="important" >}} +The `kes identity ls` command has been deprecated as of KES release `2024-06-17T15-47-05Z`. +Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) instead. +{{< /admonition >}} + ## Overview List the identities for the KES server. diff --git a/content/cli/kes-key/ls.md b/content/cli/deprecated/key-ls.md similarity index 82% rename from content/cli/kes-key/ls.md rename to content/cli/deprecated/key-ls.md index cd1459a..ea6d494 100644 --- a/content/cli/kes-key/ls.md +++ b/content/cli/deprecated/key-ls.md @@ -6,6 +6,11 @@ draft: false tableOfContents: true --- +{{< admonition title="Command deprecated" type="important" >}} +The `kes identity ls` command has been deprecated as of KES release `2024-06-17T15-47-05Z`. +Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) instead. +{{< /admonition >}} + ## Overview Return a list of existing cryptographic keys. diff --git a/content/cli/kes-policy/ls.md b/content/cli/deprecated/policy-ls.md similarity index 80% rename from content/cli/kes-policy/ls.md rename to content/cli/deprecated/policy-ls.md index 775a08b..029a92b 100644 --- a/content/cli/kes-policy/ls.md +++ b/content/cli/deprecated/policy-ls.md @@ -6,6 +6,11 @@ draft: false tableOfContents: true --- +{{< admonition title="Command deprecated" type="important" >}} +The `kes identity ls` command has been deprecated as of KES release `2024-06-17T15-47-05Z`. +Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) instead. +{{< /admonition >}} + ## Overview Outputs a list of policies on the KES server. diff --git a/content/cli/kes-identity/_index.md b/content/cli/kes-identity/_index.md index 59aaa3a..f53fb84 100644 --- a/content/cli/kes-identity/_index.md +++ b/content/cli/kes-identity/_index.md @@ -8,21 +8,41 @@ tableOfContents: true ## Overview -Use the `kes identity` commands to temporarily manage the identities that access the KES server. -Use the command to display, list, create, or remove identities. +Use the `kes identity` commands to generate the API key of an PEM key file. -All changes made by `kes identity` are lost when the KES server restarts. +In addition, you can use subcommands to temporarily manage the identities that access the KES server. +Use the subcommand to display, create, or remove identities. + +All changes made by `kes identity` subcommands are lost when the KES server restarts. To make persistent changes to KES identities, modify the `Policies and Identities` section of the KES [configuration file]({{< relref "tutorials/configuration.md#config-file" >}}). Specifically, for each `policy.policyname` to modify, add/remove the identities to/from the `policy.policyname.identities` array. -This page provides reference information for the `kes identity` commands. +This page provides information for the `kes identity` commands. + +## Generate an API Key + +You can pass an Ed25519 type private key (``.PEM``) file with this command the KES returns an API key and identity for that key file. +You can also pass the certificate (`.crt`) file or an API key and return the identity. + +For example, passing the `my-private-key.pem` file returns the identity and API key to use for the private key. + +```sh {.copy} +kes identity my-private-key.pem +``` + +Passing a certificate or an API key instead of a PEM key returns only the identity for the passed value. + +```sh {.copy} +kes identity my-certificate.crt +``` + + ## Subcommands |Subcommands |Description | |:-------------------------------------------------|:-----------------------------------------| |[`info`]({{< relref "/cli/kes-identity/info" >}}) |Get information about a KES identity | -|[`ls`]({{< relref "/cli/kes-identity/ls" >}}) |List KES identities | |[`new`]({{< relref "/cli/kes-identity/new" >}}) |Create a KES identity | |[`of`]({{< relref "/cli/kes-identity/of" >}}) |Compute a KES identity from a certificate | @@ -30,4 +50,10 @@ This page provides reference information for the `kes identity` commands. ## Related Content - [KES Policy Configuration]({{< relref "/tutorials/configuration.md#policy-configuration" >}}) -- [Conceptual information on KES]({{< relref "/concepts/_index.md" >}}) \ No newline at end of file +- [Conceptual information on KES]({{< relref "/concepts/_index.md" >}}) + +## Deprecated + +|Subcommands |Description | +|:----------------------------------------------------|:----------------------------------------------| +|[`ls`]({{< relref "/cli/deprecated/identity-ls" >}}) | Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) | \ No newline at end of file diff --git a/content/cli/kes-identity/new.md b/content/cli/kes-identity/new.md index 7ad8e1b..1607c6b 100644 --- a/content/cli/kes-identity/new.md +++ b/content/cli/kes-identity/new.md @@ -122,7 +122,7 @@ $ kes identity new Create an identity that uses either of two IP addresses as a subject alternate name (SAN). ```sh {.copy} -$ kes identity new --ip "192.168.0.182" --ip "10.0.0.92" Client-1 +$ kes identity new --ip "192.168.0.182" --ip "10.0.0.92" --key private.key --cert public.crt Client-1 ``` Create an encrypted identity that expires in the default time of 30 days. diff --git a/content/cli/kes-key/_index.md b/content/cli/kes-key/_index.md index 7cf4882..e299514 100644 --- a/content/cli/kes-key/_index.md +++ b/content/cli/kes-key/_index.md @@ -21,9 +21,14 @@ This set of pages provides reference information for the `kes key` commands. |[`create`]({{< relref "/cli/kes-key/create" >}}) |Create a new cryptographic key | |[`import`]({{< relref "/cli/kes-key/import" >}}) |Import a cryptographic key | |[`info`]({{< relref "/cli/kes-key/info" >}}) |Output information about a cryptographic key | -|[`ls`]({{< relref "/cli/kes-key/ls" >}}) |List cryptographic keys | |[`rm`]({{< relref "/cli/kes-key/rm" >}}) |Delete a cryptographic key | | | | |[`encrypt`]({{< relref "/cli/kes-key/encrypt" >}}) |Encrypt a message | |[`decrypt`]({{< relref "/cli/kes-key/decrypt" >}}) |Decrypt an encrypted message | |[`dek`]({{< relref "/cli/kes-key/dek" >}}) |Generate a new data encryption key | + +## Deprecated + +|Subcommands |Description | +|:--------------------------------------------------|:---------------------------------------------| +|[`ls`]({{< relref "/cli/deprecated/key-ls" >}}) |Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) | diff --git a/content/cli/kes-ls/_index.md b/content/cli/kes-ls/_index.md new file mode 100644 index 0000000..78e6a90 --- /dev/null +++ b/content/cli/kes-ls/_index.md @@ -0,0 +1,71 @@ +--- +title: kes ls +date: 2023-03-03 +lastmod: :git +draft: false +tableOfContents: true +--- + +{{< admonition title="Replaces deprecated commands" type="note" >}} +The `kes ls` command replaces the following commands, which are deprecated: + +- `kes key ls` +- `kes policy ls` +- `kes identity ls` +{{< /admonition >}} + +## Overview + +Returns a list of keys, policies, or identities. + +## Syntax + +```sh +kes ls \ + --api-key, -a \ + --server, -s \ + --json \ + --identity, -i \ + --policy, -p \ + --insecure, -k +``` + +## Parameters + +### `--api-key, -a` + +*Optional* + +API key to use to authenticate to the KES Server. +Defaults to the value in the `$MINIO_KES_API_KEY` environment variable. + +### `--server, -s` + +*Optional* + +The `HOST[:PORT]` of the KES server to connect to. +Defaults to the value in the `$MINIO_KES_SERVER` environment variable. + +### `--json` + +*Optional* + +Print the output in JSON format. + +### `--identity, -i` + +*Optional* + +Print a list of identities. + +### `--policy, -p` + +*Optional* + +Print a list of policies. + +### `--insecure, -k` + +*Optional* + +Skip verification of the server's certificate. diff --git a/content/cli/kes-policy/_index.md b/content/cli/kes-policy/_index.md index 84ab106..d5ab6be 100644 --- a/content/cli/kes-policy/_index.md +++ b/content/cli/kes-policy/_index.md @@ -22,5 +22,11 @@ To make persistent changes to KES policies, modify the `policy` section of the K |[`assign`]({{< relref "/cli/kes-policy/assign" >}}) |Assign a policy to identities | |[`create`]({{< relref "/cli/kes-policy/create" >}}) |Create a new policy | |[`info`]({{< relref "/cli/kes-policy/info" >}}) |Get information about a policy | -|[`ls`]({{< relref "/cli/kes-policy/ls" >}}) |List policies | |[`show`]({{< relref "/cli/kes-policy/show" >}}) |Display a policy | + + +## Deprecated + +|Subcommands |Description | +|:--------------------------------------------------|:----------------------------------------------| +|[`ls`]({{< relref "/cli/deprecated/policy-ls" >}}) | Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) | \ No newline at end of file diff --git a/content/concepts/environment-variables.md b/content/concepts/environment-variables.md index 4aaac6a..1872443 100644 --- a/content/concepts/environment-variables.md +++ b/content/concepts/environment-variables.md @@ -34,3 +34,13 @@ MinIO uses this key for the following: - Encrypting backend data ( [IAM](https://min.io/docs/minio/linux/administration/identity-access-management.html#minio-authentication-and-identity-management), server configuration). - The default encryption key for Server-Side Encryption with [SSE-KMS](https://min.io/docs/minio/linux/administration/server-side-encryption/server-side-encryption-sse-kms.html#minio-encryption-sse-kms). - The encryption key for Server-Side Encryption with [SSE-S3](https://min.io/docs/minio/linux/administration/server-side-encryption/server-side-encryption-sse-s3.html#minio-encryption-sse-s3). + +## `MINIO_KES_SERVER` + +The server endpoint a client uses to connect to KES. +If not defined, the value defaults to `127.0.0.1.7373`. + + +## `MINIO_KES_API_KEY` + +The API key a client uses to authenticate to the KES server. \ No newline at end of file From 29795a0d5402da0be7baaec30c14df7cc303004e Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Mon, 15 Jul 2024 17:18:59 -0400 Subject: [PATCH 2/3] Fixes getting started page's server command `--auth` flag was deprecated in Nov 2023. Closes #59 --- content/cli/deprecated/_index.md | 19 +++++++++++++++++++ content/tutorials/getting-started.md | 2 +- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 content/cli/deprecated/_index.md diff --git a/content/cli/deprecated/_index.md b/content/cli/deprecated/_index.md new file mode 100644 index 0000000..f7d9c16 --- /dev/null +++ b/content/cli/deprecated/_index.md @@ -0,0 +1,19 @@ +--- +title: Deprecated commands +date: 2024-07-15 +lastmod: :git +draft: false +tableOfContents: true +weight: 1000 +--- + +The following commands have been deprecated. +Replacement commands are listed, where applicable. + +## Deprecated + +|Subcommands |Description | +|:-------------------------------------------------------------|:----------------------------------------------| +|[`identity ls`]({{< relref "/cli/deprecated/identity-ls" >}}) | Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) | +|[`key ls`]({{< relref "/cli/deprecated/key-ls" >}}) | Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) | +|[`policy ls`]({{< relref "/cli/deprecated/policy-ls" >}}) | Use [`kes ls`]({{< relref "/cli/kes-ls/" >}}) | diff --git a/content/tutorials/getting-started.md b/content/tutorials/getting-started.md index fa36b43..f770156 100644 --- a/content/tutorials/getting-started.md +++ b/content/tutorials/getting-started.md @@ -202,7 +202,7 @@ This starts a KES server on `127.0.0.1:7373` and stores keys in memory. Start the KES server instance: ```sh {.copy} - kes server --config config.yml --auth off + kes server --config config.yml ``` ## KES CLI Access From 2b085d672ba997e36305b12e3f0afe02a998efb5 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Tue, 16 Jul 2024 14:58:16 -0400 Subject: [PATCH 3/3] Applying PR feedback --- content/cli/kes-identity/new.md | 3 +++ content/cli/kes-key/_index.md | 2 +- content/cli/kes-ls/_index.md | 32 +++++++++++++++-------- content/concepts/environment-variables.md | 2 +- 4 files changed, 26 insertions(+), 13 deletions(-) diff --git a/content/cli/kes-identity/new.md b/content/cli/kes-identity/new.md index 1607c6b..90ec70d 100644 --- a/content/cli/kes-identity/new.md +++ b/content/cli/kes-identity/new.md @@ -38,6 +38,8 @@ The identity can be computed again via: ## Syntax + +```sh kes identity new [--cert ] [--dns ] @@ -47,6 +49,7 @@ kes identity new [--ip ] [--key ] [] +``` ## Parameters diff --git a/content/cli/kes-key/_index.md b/content/cli/kes-key/_index.md index e299514..8261a49 100644 --- a/content/cli/kes-key/_index.md +++ b/content/cli/kes-key/_index.md @@ -8,7 +8,7 @@ tableOfContents: true ## Overview -The :mc:`kes key` command creates, utilizes, displays, and deletes cryptographic keys (Secrets) through the MinIO Key Encryption Service (KES). +The `kes key` command creates, utilizes, displays, and deletes cryptographic keys (Secrets) through the MinIO Key Encryption Service (KES). KES stores created secrets on the configured [Key Management System (KMS)]({{< relref "/_index.md#supported-kms-targets" >}}) target. You can also use these commands to encrypt/decrypt messages or generate new data encryption keys. diff --git a/content/cli/kes-ls/_index.md b/content/cli/kes-ls/_index.md index 78e6a90..29ee67c 100644 --- a/content/cli/kes-ls/_index.md +++ b/content/cli/kes-ls/_index.md @@ -6,8 +6,8 @@ draft: false tableOfContents: true --- -{{< admonition title="Replaces deprecated commands" type="note" >}} -The `kes ls` command replaces the following commands, which are deprecated: +{{< admonition type="note" >}} +The `kes ls` command replaces the following [deprecated commands]({{< relref "/cli/deprecated/_index.md" >}}): - `kes key ls` - `kes policy ls` @@ -18,15 +18,17 @@ The `kes ls` command replaces the following commands, which are deprecated: Returns a list of keys, policies, or identities. +If the command does not specify to list policies or identities, the command returns a list of the names of keys for the KES server. + + ## Syntax ```sh -kes ls \ - --api-key, -a \ - --server, -s \ - --json \ - --identity, -i \ - --policy, -p \ +kes ls \ + --api-key, -a \ + --server, -s \ + --json \ + [ --identity, -i | --policy, -p ] \ --insecure, -k ``` @@ -37,14 +39,14 @@ kes ls \ *Optional* API key to use to authenticate to the KES Server. -Defaults to the value in the `$MINIO_KES_API_KEY` environment variable. +If not provided, the command uses the value in the [`$MINIO_KES_API_KEY`]({{< relref "/concepts/environment-variables/#minio_kes_api_key" >}}) environment variable. ### `--server, -s` *Optional* The `HOST[:PORT]` of the KES server to connect to. -Defaults to the value in the `$MINIO_KES_SERVER` environment variable. +If not provided, the command uses the value in the [`$MINIO_KES_SERVER`]({{< relref "/concepts/environment-variables/#minio_kes_server" >}}) environment variable. ### `--json` @@ -57,12 +59,20 @@ Print the output in JSON format. *Optional* Print a list of identities. +When used, the command returns only a list of the identities. + +This option is mutually exclusive with `--policy`. +You can use one or the other, but not both at the same time. ### `--policy, -p` *Optional* -Print a list of policies. +Print a list of policies names. +When used, the command returns only a list of the policies. + +This option is mutually exclusive with `--identity`. +You can use one or the other, but not both at the same time. ### `--insecure, -k` diff --git a/content/concepts/environment-variables.md b/content/concepts/environment-variables.md index 1872443..d45f88e 100644 --- a/content/concepts/environment-variables.md +++ b/content/concepts/environment-variables.md @@ -38,7 +38,7 @@ MinIO uses this key for the following: ## `MINIO_KES_SERVER` The server endpoint a client uses to connect to KES. -If not defined, the value defaults to `127.0.0.1.7373`. +If not defined, the value defaults to `127.0.0.1:7373`. ## `MINIO_KES_API_KEY`