Configuring the KACLS

The KACLS is configured in the kacls section of the config.json file. You can configure it independantly for each tenant. The template for KACLS configuration block is as follows:

 "kacls": {
        "enable": true,
        "user_authentication": {
          "enable_wellknown_cse_discovery": "_ENABLE_WELLKNOWN_CSE_DISCOVERY_",
          "idps": [
            {
              "discovery_uri": "_AUTHENTICATION_OPEN_ID_CONFIGURATION_URL_",
              "client_id": "_AUTHENTICATION_AUDIENCE_"
            },
            {
              "jwks_uri": "_IDPS_JWKS_URL_",
              "audience": "_IDPS_AUDIENCE_",
              "issuer": "_IDPS_ISSUER_"
            }
          ]
        },
        "admin_authentication": [
          {
            "discovery_uri": "_ADMIN_AUTHENTICATION_DISCOVERY_URI_",
            "client_id": "_ADMIN_AUTHENTICATION_ISSUER_"
          }
        ],
        "wrapprivatekey_authentication": [
          {
            "discovery_uri": "_WRAPPRIVATEKEY_AUTHENTICATION_DISCOVERY_URI_",
            "client_id": "_WRAPPRIVATEKEY_AUTHENTICATION_ISSUER_"
          }
        ],
        "migration": {
          "enable": "_ENABLE_",
          "kaclstokacls_token": {
            "kid": "_KACLS_TO_KACLS_KEY_",
            "format": "_FORMAT_",
            "key": "_KEY_",
            "duration": "_DURATION_"
          },
          "acls": {
            "kacls_urls": ["_ALLOWED_KACLS_URL_"]
          }
        },
        "delegate": {
          "enable": "_ENABLE_",
          "authentication": {
            "key": "_PRIVATE_KEY_BASE64_"
          }
        },
        "keys": {
          "users_private_keys": {
            "crypto_backend": {
              "id": "_CRYPTO_BACKEND_ID_"
            }
          }
        },
        "crypto_backends": [
          {
            "id": "_CRYPTO_BACKEND_ID_",
            "name": "_CRYPTO_BACKEND_NAME_",
            "type": "_CRYPTO_BACKEND_TYPE_",
            "configuration": {
              "host": "_HOST_",
              "port": "_PORT_",
              "vendor": "_VENDOR_",
              "model": "_MODEL_",
              "credentials": {
                "key": "_KEY_",
                "cert": "_CERT_",
                "ca": "_CA_"
              },
              "domain_id": "_KMS_CRYPTO_BACKEND_DOMAIN_ID_"
            }
          }
        ],
        "policy_enforcement": {
          "enable": false,
          "type": "_POLICY_ENFORCEMENT_TYPE_",
          "opa_server": {
            "url": "_URL_",
            "authentication": {
              "type": "basic",
              "user_id": "_USER_ID_",
              "password": "_PASSWORD_"
            }
          }
        }
      },

user_authentication parameters

Object containing the configurations that allow the client to authenticate.

The values of the authentication parameters depends on the method used:

• OpenID configuration file (for OneLogin for instance):

  • _AUTHENTICATION_OPEN_ID_CONFIGURATION_URL_ is the URL for the OpenID configuration file. For OneLogin authentication, it must resemble: https://<domain>.onelogin.com/oidc/2/.well-known/openid-configuration.
    
    For Google authentication, it is similar to:
    
    https://accounts.google.com/.well-known/openid-configuration.
    
    
  • _AUTHENTICATION_AUDIENCE_
    
    For OneLogin authentication, it corresponds to the audience setting.
    
    For Google authentication, it corresponds to the OAuth Client ID setting.
• JSON Web Key Set file (JWKS):
  • _IDPS_JWKS_URL_ corresponds to the URL for the JWKS file that contains the signature and/or encryption keys.
    
    For Google authentication, it is similar to:
    
    https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-drive@system.gserviceaccount.com
  • _IDPS_AUDIENCE_
    
    For Google authentication, it corresponds to the OAuth Client ID setting.
  • _IDPS_ISSUER_ corresponds to the issuer of the authentication token.
    
    For Google authentication, it is similar to gsuitecse-tokenissuer-drive@system.gserviceaccount.com

For more information, see section Retrieving import values

admin_authentication parameter

JSON object array describing how to validate the authentication of administration routes via a local configuration.

wrapprivatekey_authentication parameter

JSON object array describing how to validate the authentication of /wrapprivatekey routes via a local configuration. For more information, see Migrating an external key service to another.

migration parameter

JSON object array containing information for the migration of a KACLS to another or the use of a backup KACLS.

crypto_backends parameter

JSON object array containing the definition of the backend component performing the cryptographic operations.

When using a crypto backend of type "kms" with a KMS domain, the domain_id values of all the tenant configurations must imperatively be the same and match the domain used by the KMIP configuration.

For more information, refer to section kmip_configuration parameters and the Thales documentation.

WARNING
Stormshield does not guarantee the proper functioning of the product if you do not follow these instructions.

Configuration of the cryptographic backend

A cryptographic backend is a tool used by the CSE for Gmail, allowing to choose the type of encryption and signature that the KACLS will apply, including the Gmail private keys. Two backend modes are available: 'node' for the KACLS, and 'kms' for the KMS.

The supported algorithms for each mode are:

• With the 'kms' mode, be aware of the following:

  • The KACLS is only compatible with the API of the Ciphertrust Manager from Thales.

  • Only one version of the private keys associated with a Ciphertrust keyname is supported. You should therefore not use the versioning feature of the Thales Ciphertrust Manager KMS for the encryption or signature keys used for the KACLS for Gmail.

  • For maximum security and flexibility, you can use a specific KMS key domain (Ciphertrust domains) via the domain_id parameter. In this case, also verify that dependent SDS products share the same domain (e.g., SDS Orchestrator). For more information on this configuration, refer to the Thales documentation and contact your KMS administrator.

  • Since PKCS 1.5 message signing is not compatible with Ciphertrust's REST API, the KACLS uses the KMIP protocol to perform signing operations. Configure the section kmip_configuration of the config.json file to sign messages in PKCS 1.5.

• In ‘node’ mode, data encryption using the PKCS 1.5 algorithm is vulnerable, particularly to the Marvin Attack. NodeJS version 20.11.1 has therefore removed the use of this algorithm via CVE-2023-46809. As Google only supports PKCS 1.5 for message signature and encryption, you must disable this CVE in NodeJS for the KACLS to use this feature.
  
  To do so, in RPM mode:

  1. Open the /etc/systemd/system/cse.service file.

  2. Replace the ExecStart=/usr/bin/env node cse
     
     - by -
     
     ExecStart=/usr/bin/env node --security-revert=CVE-2023-46809 cse

  This bypass is not useful if you are in 'kms' mode.

In Docker mode, CVE-2023-4680 is applied by default and you do not have to modify cse.service. A warning log notifying that the CVE is disabled is issued when the KACLS starts, which is normal.

NOTE

If the HTTP proxy is enabled, you must exclude the KMS domain from the proxy via the no_proxy environment variable. For more information, see the section Configuring proxy access.

Below is an example of a cryptographic backend configuration in "kms" mode with the Thales Ciphertrust Manager KMS:

"crypto_backends": [
  {
    "id": "3711cab6-83fc-4a97-9438-a1500edfd01a",
    "name": "My crypto tool",
    "type": "kms",
    "configuration": {
      "host": "https://web.ciphertrustmanager.local",
      "model": "ciphertrust",
      "vendor": "thales",
      "port": 443,
      "credentials": {
         "ca": "/etc/stormshield/cse/ca_kms.pem",
         "cert": "/etc/stormshield/cse/cert_kms.pem",
         "key": "/etc/stormshield/cse/key_kms.pem"
      }
    }
  }
],
"keys": {
    "users_private_keys": {
      "crypto_backend": {
         "id": "3711cab6-83fc-4a97-9438-a1500edfd01a"
      }  
    }
}

keys parameter

Object containing the UUID of the cryptographic backend to be used for cryptographic operations.

delegate parameter

JSON object array containing the definition of the delegate software component performing the delegation operations.

policy_enforcement parameter

JSON object containing the configuration of the OPA Policy for the KACLS. For more information about OPA Policy, refer to Implementing the authorization rules with Open Policy Agent.

For more information about Open Policy Agent, refer to section Implementing the authorization rules with Open Policy Agent and Customizing the authorization rules.