Cosmian · Manuthor · Dec 23, 2024 · Dec 23, 2024
diff --git a/documentation/docs/authentication.md b/documentation/docs/authentication.md
@@ -0,0 +1,99 @@
+# Authentication
+
+Cosmian CLI can connect both to KMS and Findex server and requires different authentication methods:
+
+The default configuration file is located at `~/.cosmian/cosmian.toml` where `~` is your home folder and by default,
+Cosmian CLI use no authentication when connecting the KMS and Findex server.
+
+An alternate location can be used by setting the `COSMIAN_CLI_CONF` environment
+variable.
+
+A minimum configuration file is created automatically when the CLI is used for the
+first time with the following values
+
+```toml
+[kms_config.http_config]
+server_url = "http://0.0.0.0:9998"
+
+[findex_config.http_config]
+server_url = "http://0.0.0.0:6668"
+```
+
+The configuration file should be edited manually to reflect the actual
+configuration of the products KMS and Findex server.
+Each product has its own `http_config` configuration.
+
+
+- `server_url` is MANDATORY and is the URL of the server
+- `access_token` is OPTIONAL and is the access token used to authenticate to
+  the server.
+- `ssl_client_pkcs12_path`: is OPTIONAL and is the path to the PKCS12 file
+  containing the client certificate and private key to use when authenticating
+  to the server using a certificate.
+- `ssl_client_pkcs12_password`: is OPTIONAL and is the password to open the
+  PKCS12 file when authenticating to the server using a certificate.
+- `oauth2_conf`: is OPTIONAL and is the OAuth2 configuration (
+  see [OAuth2/OIDC configuration](./authentication.md))
+  to use when authenticating to the server using OAuth2 or Open ID Connect.
+- `database_secret` is OPTIONAL and is the base 64 encoded secret to use
+  when connecting to the server using an encrypted database
+- `accept_invalid_certs` is OPTIONAL and should be set to "true" to allow the
+  CLI to connect to the server using an "invalid" certificate, such as a self-signed
+  SSL certificate. Useful to run tests with a self-signed certificate.
+- `verified_cert` contains the verified PEM TLS certificate used for certificate
+  pinning
+
+In addition for KMS, a service account can be used to fetch Gmail API and
+handle easily S/MIME elements (identities, key pairs)
+(see [S/MIME Gmail service account configuration](./smime_gmail.md))
+
+## Example
+
+Here is an example configuration with:
+
+- a KMS server without authentication
+- a Findex server with TLS authentication and a client-side encrypted database:
+
+```toml
+[kms_config.http_config]
+server_url = "http://127.0.0.1:9998"
+
+[findex_config.http_config]
+accept_invalid_certs = true
+server_url = "https://127.0.0.1:6660"
+ssl_client_pkcs12_path = "./certificates/john.doe.acme.p12"
+ssl_client_pkcs12_password = "pkcs12_password"
+database_secret = "eyJncm91cF9pZCI6MjkzMjY3MjM2AND...Cw0MiwyANDYsMTgzLDg1XX0="
+```
+
+## OAuth2/OIDC configuration
+
+When authenticating using OAuth2 or Open ID Connect, the
+`oauth2_conf` field should be set in the configuration file to provide the necessary
+information to first authenticate to Identity Provider and get a token to authenticate
+to the KMS server.
+
+Getting a Token from an Identity Provider is performed using the `cosmian kms login` command. The token
+will be saved in the `cosmian` configuration file. To remove the token, use the `cosmian kms logout` command.
+
+The `oauth2_conf` field is a TOML object with the following fields:
+
+- `client_id`: the client ID to use when authenticating to the Identity Provider
+- `client_secret`: the client secret to use when authenticating to the Identity Provider
+- `authorize_url`: the URL to use when authorizing the client
+- `token_url`: the URL to use when requesting an access token
+- `scopes`: the optional list of scopes to request when authenticating to the KMS server
+
+Example Google Identity Provider configuration:
+
+```toml
+[kms_config.http_config]
+server_url = "http://127.0.0.1:9998"
+
+[kms_config.http_config.oauth2_conf]
+client_id = "99999999-abababababababababab.apps.googleusercontent.com"
+client_secret = "G0ABCD-aAbBcDeFgHiJkLmNoPqRsTuVwXyZ"
+authorize_url = "https://accounts.google.com/o/oauth2/v2/auth"
+token_url = "https://oauth2.googleapis.com/token"
+scopes = ["openid", "email"]
+```
diff --git a/documentation/docs/authorization.md b/documentation/docs/authorization.md
@@ -1,4 +1,7 @@
-# Authorizing users with access objects
+# KMS Authorizing users with access objects
+
+When [authentication](./authentication.md) is enabled, each KMS object requires explicit authorization from its owner to be accessed or used by others.
+The Cosmian CLI then allows to manage the access rights of users to cryptographic objects stored in the KMS.
 
 ## Granting an access right
 

diff --git a/documentation/docs/configuration.md b/documentation/docs/configuration.md
@@ -1,7 +1,7 @@
 
 # Configuration file
 
-By default, the server expects to find:
+By default, the client expects to find:
 
 - a TOML configuration file in `/etc/cosmian/cosmian.toml`.
 - or an environment variable `COSMIAN_CLI_CONF` that contains the path to the configuration file.
@@ -22,18 +22,20 @@ server_url = "http://0.0.0.0:6668"
 ```toml
 [kms_config.http_config]
 server_url = "http://0.0.0.0:9990"
-ssl_client_pkcs12_path = "../../test_data/certificates/client_server/owner/owner.client.acme.com.p12"
+ssl_client_pkcs12_path = "../../test_data/certificates/client_server/owner/kms.client.acme.com.p12"
 ssl_client_pkcs12_password = "password"
 
 [findex_config.http_config]
 accept_invalid_certs = true
 server_url = "https://0.0.0.0:6660"
-ssl_client_pkcs12_path = "../../test_data/certificates/client_server/owner/owner.client.acme.com.p12"
+ssl_client_pkcs12_path = "../../test_data/certificates/client_server/owner/findex.client.acme.com.p12"
 ssl_client_pkcs12_password = "password"
 ```
 
 ## Example with OpenID authentication
 
+Both KMS and Findex server can be configured with OpenID Connect (OIDC) authentication. In that case, Cosmian CLI must use the `oauth2_conf` field to authenticate to the servers.
+
 ```toml
 [kms_config.http_config]
 server_url = "http://0.0.0.0:9998"
@@ -51,7 +53,11 @@ server_url = "http://0.0.0.0:6668"
 access_token = "eyJhbGciOiJSUzI1...OjPY84GRMmvpYZfyaJbDDql3A"
 ```
 
-## Example with S/MIME Gmail service account configuration for KMS server
+## S/MIME Gmail service account configuration for KMS server
+
+Google Workspace can delegate encryption/decryption of Gmail (and other services such as Drive, Meet, Calendar) to an external Key Management System (KMS). In that case, the KMS can be used to encrypt and decrypt the S/MIME elements (identities, key pairs) and store them securely.
+
+When using S/MIME, the `gmail_api_conf` field should be set in the configuration file to provide the necessary information about the configured service account to interact with Gmail API, and handle identities and keypairs easily from the KMS.
 
 ```toml
 [kms_config.http_config]

diff --git a/documentation/docs/index.md b/documentation/docs/index.md
@@ -13,9 +13,8 @@ By leveraging Cosmian CLI, users can seamlessly integrate advanced cryptographic
 
 - [Cosmian Command Line Interface (CLI)](#cosmian-command-line-interface-cli)
   - [Installation](#installation)
-  - [Configuring the clients](#configuring-the-clients)
-  - [OAuth2/OIDC configuration](#oauth2oidc-configuration)
-  - [S/MIME Gmail service account configuration](#smime-gmail-service-account-configuration)
+  - [Configuration](#configuration)
+  - [KMS objects access rights](#kms-objects-access-rights)
   - [Usage](#usage)
 
 !!! info "Download cosmian and cosmian_gui"
@@ -30,142 +29,14 @@ By leveraging Cosmian CLI, users can seamlessly integrate advanced cryptographic
 <!-- To test locally, test with path `installation.md` -->
 {!../cli/documentation/docs/installation.md!}
 
-## Configuring the clients
-
-Both clients - and the PKCS#11 provider library - expect a configuration file to be located
-at `~/.cosmian/cosmian.toml` where `~` is your home folder.
-
-An alternate location can be used by setting the `COSMIAN_CLI_CONF_ENV` environment
-variable.
-
-A minimum configuration file is created automatically when the CLI is used for the
-first time with the following values
-
-```toml
-[kms_config.http_config]
-server_url = "http://0.0.0.0:9998"
-
-[findex_config.http_config]
-server_url = "http://0.0.0.0:6668"
-```
-
-The configuration file should be edited manually to reflect the actual
-configuration of the products KMS and Findex server.
-
-- `server_url` is MANDATORY and is the URL of the KMS server
-- `access_token` is OPTIONAL and is the access token used to authenticate to
-  the KMS server.
-- `ssl_client_pkcs12_path`: is OPTIONAL and is the path to the PKCS12 file
-  containing the client certificate and private key to use when authenticating
-  to a KMS server using a certificate.
-- `ssl_client_pkcs12_password`: is OPTIONAL and is the password to open the
-  PKCS12 file when authenticating to the KMS server using a certificate.
-- `oauth2_conf`: is OPTIONAL and is the OAuth2 configuration (
-  see [below](#oauth2oidc-configuration))
-  to use when authenticating to the KMS server using OAuth2 or Open ID Connect.
-- `database_secret` is OPTIONAL and is the base 64 encoded secret to use
-  when connecting to a KMS using an encrypted database
-- `accept_invalid_certs` is OPTIONAL and should be set to "true" to allow the
-  CLI to connect to a KMS using an "invalid" certificate, such as a self-signed
-  SSL certificate. Useful to run tests with a self-signed certificate.
-- `verified_cert` contains the verified PEM TLS certificate used for certificate
-  pinning
-- `gmail_api_conf` is OPTIONAL and contains information about the configured
-  service account used to fetch Gmail API and handle easily S/MIME elements (identities, key pairs)
-  (see [below](#smime-gmail-service-account-configuration))
-
-Here is an example configuration with TLS authentication and a client-side encrypted
-database:
-
-```toml
-[kms_config.http_config]
-server_url = "http://127.0.0.1:9998"
-
-[findex_config.http_config]
-accept_invalid_certs = true
-server_url = "https://127.0.0.1:6660"
-ssl_client_pkcs12_path = "./certificates/john.doe.acme.p12"
-ssl_client_pkcs12_password = "pkcs12_password"
-database_secret = "eyJncm91cF9pZCI6MjkzMjY3MjM2NDU3ODgyMjIzMjM0NDY2MjkxNTY2NDk5Nzc0NTk1LCJrZXkiOlsyMTgsNDIsMTkzLDE4Myw1OSwyMzQsMTY3LDE3Niw4OCwxNjYsMjUyLDYyLDk5LDU4LDM0LDUxLDE1Nyw5NiwyMjEsMjE1LDIwMSwxOTcsODYsOTksMTI1LDIxMSw2Niw0MCw0MiwyNDYsMTgzLDg1XX0="
-```
-
-## OAuth2/OIDC configuration
-
-When authenticating using OAuth2 or Open ID Connect, the
-`oauth2_conf` field should be set in the configuration file to provide the necessary
-information to first authenticate to Identity Provider and get a token to authenticate
-to the KMS server.
-
-Getting a Token from an Identity Provider is performed using the `ckms login` command. The token
-will be saved in the `ckms` configuration file. To remove the token, use the `ckms logout` command.
-
-The `oauth2_conf` field is a TOML object with the following fields:
-
-- `client_id`: the client ID to use when authenticating to the Identity Provider
-- `client_secret`: the client secret to use when authenticating to the Identity Provider
-- `authorize_url`: the URL to use when authorizing the client
-- `token_url`: the URL to use when requesting an access token
-- `scopes`: the optional list of scopes to request when authenticating to the KMS server
-
-Example Google Identity Provider configuration:
-
-```toml
-[kms_config.http_config]
-server_url = "http://127.0.0.1:9998"
-
-[kms_config.http_config.oauth2_conf]
-client_id = "99999999-abababababababababab.apps.googleusercontent.com"
-client_secret = "G0ABCD-aAbBcDeFgHiJkLmNoPqRsTuVwXyZ"
-authorize_url = "https://accounts.google.com/o/oauth2/v2/auth"
-token_url = "https://oauth2.googleapis.com/token"
-scopes = ["openid", "email"]
-```
-
-## S/MIME Gmail service account configuration
-
-When using S/MIME, the `gmail_api_conf` field should be set in the configuration file to provide
-the necessary information about the configured service account to interact with Gmail API, and
-handle
-identities and keypairs easily from the ckms.
-
-This configuration is mandatory for `ckms google` subcommands.
-
-The `gmail_api_conf` field is a TOML object with the following fields:
-
-- `account_type`
-- `project_id`
-- `private_key_id`
-- `private_key`
-- `client_email`
-- `client_id`
-- `auth_uri`
-- `token_uri`
-- `auth_provider_x509_cert_url`
-- `client_x509_cert_url`
-- `universe_domain`
-
-I can be retrieved directly from a TOML file downloaded from Google interface when creating
-and configuring the service account (following Google documentation).
-
-Example:
-
-```toml
-[kms_config.http_config]
-server_url = "http://127.0.0.1:9998"
-
-[kms_config.gmail_api_conf]
-account_type = "service_account"
-project_id = "project_id"
-private_key_id = "abc123abc123abc123abc123abc123abc123"
-private_key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
-client_email = "[email protected]"
-client_id = "12345678901234567890"
-auth_uri = "https://accounts.google.com/o/oauth2/auth"
-token_uri = "https://oauth2.googleapis.com/token"
-auth_provider_x509_cert_url = "https://www.googleapis.com/oauth2/v1/certs"
-client_x509_cert_url = "https://www.googleapis.com/robot/v1/metadata/x509/xxx%40yyyy.iam.gserviceaccount.com"
-universe_domain = "googleapis.com"
-```
+## Configuration
+
+To communicate with KMS and Findex server, the clients `cosmian` and `cosmian_gui` expect the same configuration file. Please read the [configuration](./configuration.md) section.
+
+## KMS objects access rights
+
+When [authentication](./authentication.md) is enabled, each KMS object requires explicit authorization from its owner to be accessed or used by others.
+The Cosmian CLI then [allows to manage the access rights](./authorization.md) of users to cryptographic objects stored in the KMS.
 
 ## Usage
 

diff --git a/documentation/docs/smime_gmail.md b/documentation/docs/smime_gmail.md
@@ -0,0 +1,45 @@
+# S/MIME Gmail service account configuration
+
+When using S/MIME, the `gmail_api_conf` field should be set in the configuration file to provide
+the necessary information about the configured service account to interact with Gmail API, and
+handle
+identities and keypairs easily from the ckms.
+
+This configuration is mandatory for `ckms google` subcommands.
+
+The `gmail_api_conf` field is a TOML object with the following fields:
+
+- `account_type`
+- `project_id`
+- `private_key_id`
+- `private_key`
+- `client_email`
+- `client_id`
+- `auth_uri`
+- `token_uri`
+- `auth_provider_x509_cert_url`
+- `client_x509_cert_url`
+- `universe_domain`
+
+I can be retrieved directly from a TOML file downloaded from Google interface when creating
+and configuring the service account (following Google documentation).
+
+Example:
+
+```toml
+[kms_config.http_config]
+server_url = "http://127.0.0.1:9998"
+
+[kms_config.gmail_api_conf]
+account_type = "service_account"
+project_id = "project_id"
+private_key_id = "abc123abc123abc123abc123abc123abc123"
+private_key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+client_email = "[email protected]"
+client_id = "12345678901234567890"
+auth_uri = "https://accounts.google.com/o/oauth2/auth"
+token_uri = "https://oauth2.googleapis.com/token"
+auth_provider_x509_cert_url = "https://www.googleapis.com/oauth2/v1/certs"
+client_x509_cert_url = "https://www.googleapis.com/robot/v1/metadata/x509/xxx%40yyyy.iam.gserviceaccount.com"
+universe_domain = "googleapis.com"
+```