Configuring PKI

The PKI is configured in the pki section of the config.json file. You can configure it independently for each tenant.

The template for the PKI configuration block is as follows:

Copy

"pki": {
        "enable": false,
        "default": "_PKI_DEFAULT_PKI_",
        "pki_engines": [
          {
            "id": "_PKI_ENGINE_ID_",
            "name": "_PKI_ENGINE_NAME_",
            "ra": {
              "type": "_PKI_ENGINE_RA_TYPE_",
              "authentication": [
                {
                  "name": "_PKI_RA_API_KEY_NAME",
                  "api_key": "_PKI_RA_API_KEY_VALUE"
                }
              ]
            },
            "ca": {
              "type": "_PKI_ENGINE_CA_TYPE_",
              "key_path": "_PKI_ENGINE_KEY_PATH_",
              "full_chain_certificates_path": "_PKI_ENGINE_CERT_CHAIN_PATH_",
              "certificate_signature": {
                "algorithms": {
                  "hash": "_PKI_ENGINE_HASH_ALGO_",
                  "signature": "_PKI_ENGINE_SIGNATURE_ALGO_"
                },
                "parameters": {
                  "salt_length": 20
                }
              },
              "certificate_profiles": {
                "validity_period": 31536000
              }
            }
          }
        ]
      },

	Description	Type	Optional/ mandatory
enable	Enables or disables the PKI for the tenant.	Boolean	Mandatory to use the PKI feature
default	Identifier of the tenant default PKI engine. It must match one of the id parameter of the pki_engines object. It is used as the default PKI engine configuration.	String	Mandatory
pki_engines: JSON object array containing the list of all PKI engines as JSON objects.
id	Unique identifier of the PKI engine in UUIDv4 format.	String	Mandatory
name	Name of the PKI engine.	String	Mandatory
ra: JSON object containing the registration authority configuration. For more details, see the table below.
ca: JSON object containing the certification authority configuration. For more details, see the table below.

Registration authority (RA) parameters

Parameter	Description	Type	Optional/ mandatory
type	Type of registration autority. The only prescribed value is "est".	String	Mandatory
authentication: JSON object containing the list of API keys.
name	Name of the API key. The character ‘’:’’ is not allowed. See RFC 2617.	String	Mandatory
api_key	Value of the API key.	String	Mandatory

Certification authority (CA) parameters

Parameter	Description	Type	Optional/ mandatory
type	Type of the certification authority. The only prescribed value is "local".	String	Mandatory
key_path	Path to the CA private key in PEM format. See Configuring PKI.	String	Mandatory
full_chain_certificates_path	Path to the CA certificate chain in PEM format. See Configuring PKI.	String	Mandatory
certificate_signature: JSON object containing the metadata for the signature of the certificate signing request (CSR) by the CA.
algorithms	Signature algorithm. It includes the following fields: signature: The only prescribed value is "rsassa_pkcs1_v1_5", hash: The prescribed values are "sha-256" or "sha-384", and "sha-512". See Compatibility of algorithms and CA properties.	String	Mandatory
parameters	Metadata for specific algorithms. It includes the following field: salt_length: RSA-PSS specific signature parameter to improve security (Not used).	Integer	Optional
certificate_profiles: Metadata of the certificate profile.
validity_period	Validity period of issued certificate in seconds. The minimum is 1, and the maximum is 2 147 483 647 seconds (68 years). A typical value is 31 536 000 seconds (1 year).	Integer	Mandatory

EXAMPLE
The content below is provided as an example and must not be used as such in the Stormshield KMaaS PKI configuration of one of your tenants.

Copy

"pki": {
  "enable": true,
  "default": "8e071476-01a2-44e8-90f3-be94d2de46ef",
  "pki_engines": [
    {
      "id": "8e071476-01a2-44e8-90f3-be94d2de46ef",
      "name": "pki_name",
      "ra": {
        "type": "est",
        "authentication": [
          {
            "name": "testApiKey",
            "api_key": "VW0FmFl73leUkYGBCr8DjlFcZBt6en5p"     
          }
        ]
      },
      "ca": {
        "type": "local",
        "key_path": "/etc/stormshield/pki/ca_private_key.pem",
        "full_chain_certificates_path": "/etc/stormshield/pki/ca_certificate.pem",
        "certificate_signature": {
          "algorithms": {
            "hash": "sha-256",
            "signature": "rsassa_pkcs1_v1_5"
          },
          "parameters": {
          }
        },
        "certificate_profiles": {
          "validity_period": 3153600
        }
      }
    }
  ]
}