diff --git a/documentation/docs/authentication.md b/documentation/docs/authentication.md new file mode 100644 index 00000000..9f553fd5 --- /dev/null +++ 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 index 486e1198..477d16ea 100644 --- 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 index 6c3f711a..b4ed1cb0 100644 --- 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 index acab3254..84d80cdf 100644 --- 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 {!../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 = "xxx@yyyy.iam.gserviceaccount.com" -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 new file mode 100644 index 00000000..45f20edd --- /dev/null +++ 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 = "xxx@yyyy.iam.gserviceaccount.com" +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" +``` diff --git a/documentation/docs/usage.md b/documentation/docs/usage.md index 2d2ad8ab..8914e68b 100644 --- a/documentation/docs/usage.md +++ b/documentation/docs/usage.md @@ -11,22 +11,14 @@ Commands: help Print this message or the help of the given subcommand(s) Options: - -c, --conf - Configuration file location - --kms-url - The URL of the KMS - --kms-accept-invalid-certs - Allow to connect using a self-signed cert or untrusted cert chain [possible values: true, false] - --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 - --findex-url - The URL of the Findex server - --findex-accept-invalid-certs - Allow to connect using a self-signed cert or untrusted cert chain [possible values: true, false] - -h, --help - Print help (see more with '--help') - -V, --version - Print version + -c, --conf-path Configuration file location [env: COSMIAN_CLI_CONF_PATH=] + --kms-url The URL of the KMS [env: KMS_DEFAULT_URL=] + --kms-accept-invalid-certs Allow to connect using a self-signed cert or untrusted cert chain + --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 + --findex-url The URL of the Findex server [env: FINDEX_SERVER_DEFAULT_URL=] + --findex-accept-invalid-certs Allow to connect using a self-signed cert or untrusted cert chain + -h, --help Print help (see more with '--help') + -V, --version Print version ``` ## KMS commands @@ -65,20 +57,17 @@ Usage: cosmian findex-server Commands: encrypt-and-index Encrypt entries and index the corresponding database UUIDs with the Findex. - First the CSV file is read and encrypted on client-side with KEM-DEM crypto-system - KEM: Key Encapsulation Mechanism - DEM: Data Encapsulation Mechanism search-and-decrypt Search keywords and decrypt the content of corresponding UUIDs. delete-dataset Delete encrypted entries. (Indexes are not deleted) - index Index new keywords + datasets Manage encrypted datasets delete Delete indexed keywords - search Findex: Search keywords. - server-version Print the version of the server + index Index new keywords login Login to the Identity Provider of the Findex server using the `OAuth2` authorization code flow. logout Logout from the Identity Provider. permissions Manage the users permissions to the indexes - datasets Manage encrypted datasets + search Findex: Search keywords. + server-version Print the version of the server help Print this message or the help of the given subcommand(s) Options: diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 58a109b9..286d60e8 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -54,7 +54,8 @@ nav: - Getting started: index.md - Installation: installation.md - Configuration: - - TOML format: configuration.md - - Authorizing users with access rights: authorization.md + - Authentication: authentication.md + - KMS access rights: authorization.md + - Examples: configuration.md - Usage: usage.md - User manual: cli/main_commands.md