Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

CipherTrust Manager Administration

Interfaces

search

Please Note:

Interfaces

Interfaces are services the CipherTrust Manager hosts. Most interfaces are listening on a particular port, but may also represent other input channels, like local shell access or serial port access. To view the Interfaces page in the UI, go to Admin Settings > Interfaces.

The CipherTrust Manager currently supports five interfaces:

  • web: The HTTP server on port 80 and 443. This interface serves both the GUI and the REST API

  • ssh: The SSH server on port 22.

  • nae: The NAE-XML server on port 9000.

  • kmip: The KMIP server on port 5696.

  • SNMP: The SNMP Agent on port 161. For details on the SNMP interface, go to: SNMP

To view the initial set of interfaces using ksctl

$ ./ksctl interfaces list

Response


{
  "skip": 0,
  "limit": 10,
  "total": 4,
  "resources": [
    {
      "id": "ee242373-2555-48c7-923b-86ed3e785504",
      "name": "kmip",
      "mode": "tls-cert-pw-opt",
      "cert_user_field": "CN",
      "auto_gen_ca_id": "kylo:kylo:naboo:localca:9d13d43a-381e-481a-80a1-9463acfff84a",
      "trusted_cas": {
        "local": [
          "kylo:kylo:naboo:localca:9d13d43a-381e-481a-80a1-9463acfff84a"
          ]
        },
      "createdAt": "2020-07-20T12:59:14.776939Z",
      "updatedAt": "2020-07-20T12:59:24.703806Z",
      "default_connection": "local_account",
      "port": 5696,
      "network_interface": "all",
      "interface_type": "kmip",
      "local_auto_gen_attributes": {
        "cn": "kmip.keysecure.local",
        "email_addresses": [
          "support@gemalto.com"
        ],
        "names": [
          {
            "C": "US",
            "ST": "MD",
            "L": "Belcamp",
            "O": "Gemalto",
            "OU": ""
          }
        ],
        "generated": false
      },
      "enabled": true
    },
    {
      "id": "a4db15b4-64fc-40d3-8465-9935866bbe09",
      "name": "nae",
      "mode": "no-tls-pw-req",
      "cert_user_field": "CN",
      "auto_gen_ca_id": "kylo:kylo:naboo:localca:9d13d43a-381e-481a-80a1-9463acfff84a",
      "trusted_cas": {
        "local": [
          "kylo:kylo:naboo:localca:9d13d43a-381e-481a-80a1-9463acfff84a"
        ]
      },
      "createdAt": "2020-07-20T12:59:14.770938Z",
      "updatedAt": "2020-07-20T16:21:43.427252Z",
      "default_connection": "local_account",
      "port": 9000,
      "network_interface": "all",
      "interface_type": "nae",
      "local_auto_gen_attributes": {
        "cn": "nae.keysecure.local",
        "email_addresses": [
          "support@gemalto.com"
        ],
        "names": [
          {
            "C": "US",
            "ST": "MD",
            "L": "Belcamp",
            "O": "Gemalto",
            "OU": ""
          }
        ],
        "generated": false
      },
      "enabled": true
    },
    {
      "id": "c8c6e4c1-30d7-4317-9d37-a9ec217ffb17",
      "name": "ssh",
      "trusted_cas": {},
      "createdAt": "2020-07-20T12:59:14.7787Z",
      "updatedAt": "2020-07-20T12:59:14.7787Z",
      "port": 22,
      "network_interface": "all",
      "interface_type": "ssh",
      "local_auto_gen_attributes": {
        "cn": "ssh.keysecure.local",
        "email_addresses": [
          "support@gemalto.com"
        ],
        "names": [
          {
            "C": "US",
            "ST": "MD",
            "L": "Belcamp",
            "O": "Gemalto",
            "OU": ""
          }
        ],
        "generated": false
      },
      "enabled": true
    },
    {
      "id": "e64d84b0-e952-4fa3-83c9-e1d1bc52a996",
      "name": "web",
      "mode": "unauth-tls-pw-req",
      "cert_user_field": "CN",
      "auto_gen_ca_id": "kylo:kylo:naboo:localca:9d13d43a-381e-481a-80a1-9463acfff84a",
      "trusted_cas": {
        "local": [
          "kylo:kylo:naboo:localca:9d13d43a-381e-481a-80a1-9463acfff84a"
        ]
      },
      "createdAt": "2020-07-20T12:59:14.774618Z",
      "updatedAt": "2020-07-20T12:59:23.37516Z",
      "port": 443,
      "network_interface": "all",
      "interface_type": "web",
      "local_auto_gen_attributes": {
        "cn": "web.keysecure.local",
        "email_addresses": [
          "support@gemalto.com"
        ],
        "names": [
          {
            "C": "US",
            "ST": "MD",
            "L": "Belcamp",
            "O": "Gemalto",
            "OU": ""
          }
        ],
        "generated": false
      },
      "enabled": true
    }
  ]
}

Before interface changes can take effect, you must issue a Services Restart; see Services Restart.

Updating Interface Ports

You can change ports for the following interfaces:

  • WEB

  • NAE

  • KMIP

If you change the port of the default interfaces (WEB, NAE, KMIP), all the CM services will be restarted to reflect the change.

Changing the port of a default interface causes downtime of a few minutes, therefore plan this activity accordingly.
Port change remains persistent even after restarting the device and will get replicated if the device is part of a cluster.
If CM is deployed in a cluster mode, it will restart services on all the nodes, and therefore it should be a planned activity.

Changing the port of an interface using ksctl

ksctl interfaces modify --name  --port 

You can find <Interface-Name> using the command ksctl interfaces list.

Example 1: Changing the default WEB interface port to 8443

Command


ksctl interfaces modify --name web --port 8443

Response


{
    "id": "f1af6f94-43af-4350-84d0-ec6b08639e5b",
    "name": "web",
    "mode": "unauth-tls-pw-req",
    "cert_user_field": "CN",
    "auto_gen_ca_id": "kylo:kylo:naboo:localca:a9319f59-5914-41a2-886e-32b8930d082c",
    "trusted_cas": {
        "local": [
            "kylo:kylo:naboo:localca:a9319f59-5914-41a2-886e-32b8930d082c"
        ]
    },
    "createdAt": "2020-12-09T14:25:14.596482Z",
    "updatedAt": "2020-12-09T14:29:50.246509Z",
    "port": 8443,
    "network_interface": "all",
    "interface_type": "web",
    "local_auto_gen_attributes": {
        "cn": "web.keysecure.local",
        "email_addresses": [
            "support@gemalto.com"
        ],
        "names": [
            {
                "C": "US",
                "ST": "MD",
                "L": "Belcamp",
                "O": "Gemalto",
                "OU": ""
            }
        ],
        "generated": false
    },
    "enabled": true
}

Example 2: Changing the default NAE interface port to 443

Command


ksctl interfaces modify --name nae --port 443

Response


{
    "id": "2228f2aa-f973-4fda-b633-ead376db3e19",
    "name": "nae",
    "mode": "unauth-tls-pw-opt",
    "cert_user_field": "CN",
    "auto_gen_ca_id": "kylo:kylo:naboo:localca:a9319f59-5914-41a2-886e-32b8930d082c",
    "trusted_cas": {
        "local": [
            "kylo:kylo:naboo:localca:a9319f59-5914-41a2-886e-32b8930d082c"
        ]
    },
    "createdAt": "2020-12-09T14:25:14.594319Z",
    "updatedAt": "2020-12-09T14:35:22.75339Z",
    "default_connection": "local_account",
    "port": 443,
    "network_interface": "all",
    "interface_type": "nae",
    "minimum_tls_version": "tls_1_2",
    "local_auto_gen_attributes": {
        "cn": "nae.keysecure.local",
        "email_addresses": [
            "support@gemalto.com"
        ],
        "names": [
            {
                "C": "US",
                "ST": "MD",
                "L": "Belcamp",
                "O": "Gemalto",
                "OU": ""
            }
        ],
        "generated": false
    },
    "enabled": true
}

Enabling/Disabling Interfaces

You can enable or disable the following interfaces:

  • SSH

  • NAE

  • KMIP

To enable/disable an interface using the GUI, click Action Button > Enable/Disable.

After the user has enabled/disabled an interface, it remains in same state even after restarting the device and it will get replicated if the device is part of a cluster.
After an interface has been disabled, the CipherTrust Manager drops all incoming and existing connections on that interface.

Enable or Disable an interface using ksctl

When using ksctl:

  • To enable an interface: ./ksctl interfaces enable --name <interface-name>

  • To disable an interface: ./ksctl interfaces disable --name <interface-name>

    Only the SSH, KMIP, and NAE interfaces can be enabled or disabled. Replace <interface-name> in the above commands with ssh, kmip, or nae for these interfaces.

Example: Disabling the SSH interface

Command


$ ./ksctl interfaces disable --name ssh

Response


{
  "id": "2e8d2344-c40b-466c-8202-d05d2cb6738a",
  "name": "ssh",
  "trusted_cas": {},
  "createdAt": "2020-08-13T10:22:32.792266Z",
  "updatedAt": "2020-08-14T11:11:28.564276Z",
  "port": 22,
  "network_interface": "all",
  "interface_type": "ssh",
  "local_auto_gen_attributes": {
    "cn": "ssh.keysecure.local",
    "email_addresses": [
      "support@gemalto.com"
    ],
    "names": [
      {
        "C": "US",
        "ST": "MD",
        "L": "Belcamp",
        "O": "Gemalto",
        "OU": ""
      }
    ],
    "generated": false
  },
  "enabled": false
}

SSL/TLS Supported Protocols and Cipher Suites

CipherTrust Manager allows the customers to customize the cipher suites for TLS handshake for the following interfaces:

  • NAE

  • KMIP

  • Web

A cipher suite is a set of algorithms that help secure a network connection that uses Transport Layer Security (TLS). The set of algorithms that cipher suites usually contain include: a key exchange algorithm, an authentication algorithm, a bulk encryption algorithm, and a message authentication code (MAC) algorithm.

When you add an Interface, it is added with the default recommended list of cipher suites. You can customize them by updating an interface.

The protocol has a higher priority than the cipher suites. In other words, if certain protocol is disabled and its respective cipher suites are enabled, then the cipher suites will not be used for communication.

You can not add/remove any cipher suite, however, they can be enabled/disabled from the given list of cipher suites.

Following table details the priority list of cipher suites for the respective Interfaces in the descending order.

InterfaceCipher Suites Priority List
NAE/KMIP• TLS_AES_256_GCM_SHA384 (TLSv1.3)
• TLS_CHACHA20_POLY1305_SHA256 (TLSv1.3)
• TLS_AES_128_GCM_SHA256 (TLSv1.3)
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384)
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 (disabled)
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (disabled)
• TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA (disabled)
• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA (disabled)
• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (disabled)
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (disabled)
• TLS_RSA_WITH_AES_128_CBC_SHA256 (disabled)
• TLS_RSA_WITH_AES_256_CBC_SHA (disabled)
• TLS_RSA_WITH_AES_128_CBC_SHA (disabled)
Web• TLS_AES_256_GCM_SHA384 (TLSv1.3)
• TLS_CHACHA20_POLY1305_SHA256 (TLSv1.3)
• TLS_AES_128_GCM_SHA256 (TLSv1.3)
• ECDHE-ECDSA-AES256-GCM-SHA384
• ECDHE-RSA-AES256-GCM-SHA384
• ECDHE-ECDSA-AES128-GCM-SHA256
• ECDHE-RSA-AES128-GCM-SHA256
• ECDHE-ECDSA-AES256-SHA384 (disabled)
• ECDHE-ECDSA-AES128-SHA256 (disabled)
• ECDHE-RSA-AES256-SHA384 (disabled)
• ECDHE-RSA-AES128-SHA256 (disabled)
• ECDHE-ECDSA-AES256-SHA (disabled)
• ECDHE-ECDSA-AES128-SHA (disabled)
• ECDHE-RSA-AES256-SHA (disabled)
• ECDHE-RSA-AES128-SHA (disabled)

TLS 1.3 ciphers suites are not configurable, however, you can disable the TLS protocol as a whole.

The cipher suites marked as disabled remain disabled by default as they are considered weak. If required, user can explicitly enable them for use.

Following table details the recommended and supported versions of the TLS protocol for the respective Interfaces. The recommended versions are enabled by default.

InterfaceRecommended VersionSupported Version
NAE/KMIP• TLSv1.2
• TLSv1.3
• TLSv1.1
• TLSv1.2
• TLSv1.3
Web• TLSv1.2
• TLSv1.3
• TLSv1.2
• TLSv1.3

Updating Cipher Suites using ksctl

To update cipher suite list in an Interface, run:

For Web interface-Syntax


ksctl interfaces modify --name web --tls-ciphers-file <json-file>

Example Request


ksctl interfaces modify --name web --tls-ciphers-file tls-ciphers.json

For NAE interface-Syntax


ksctl interfaces modify --name nae --tls-ciphers-file <json-file>

Example Request


ksctl interfaces modify --name nae --tls-ciphers-file tls-ciphers.json

For KMIP interface-Syntax


ksctl interfaces modify --name kmip --tls-ciphers-file <json-file>

Example Request


ksctl interfaces modify --name kmip --tls-ciphers-file tls-ciphers.json

Format of the JSON File


{
    "tls_ciphers": [
        {
            "cipher_suite": "TLS_AES_256_GCM_SHA384",
            "enabled": true
        },
        {
            "cipher_suite": "TLS_CHACHA20_POLY1305_SHA256",
            "enabled": true
        },
        {
            "cipher_suite": "TLS_AES_128_GCM_SHA256",
            "enabled": true
        },
        {
            "cipher_suite": "ECDHE-ECDSA-AES256-GCM-SHA384",
            "enabled": true
        },
        {
            "cipher_suite": "ECDHE-RSA-AES256-GCM-SHA384",
            "enabled": true
        },
        {
            "cipher_suite": "ECDHE-ECDSA-AES128-GCM-SHA256",
            "enabled": true
        },
        {
            "cipher_suite": "ECDHE-RSA-AES128-GCM-SHA256",
            "enabled": true
        }
        {
            "cipher_suite": "ECDHE-ECDSA-AES256-SHA384",
            "enabled": false
        },
        {
            "cipher_suite": "ECDHE-ECDSA-AES128-SHA256",
            "enabled": false
        },
        {
            "cipher_suite": "ECDHE-RSA-AES256-SHA384",
            "enabled": false
        },
        {
            "cipher_suite": "ECDHE-RSA-AES128-SHA256",
        "enabled": false
        },
        {
            "cipher_suite": "ECDHE-ECDSA-AES256-SHA",
            "enabled": false
        },
        {
            "cipher_suite": "ECDHE-ECDSA-AES128-SHA",
            "enabled": false
        },
        {
            "cipher_suite": "ECDHE-RSA-AES256-SHA",
            "enabled": false
        },
        {
            "cipher_suite": "ECDHE-RSA-AES128-SHA",
            "enabled": false
        }
    ]
}

Restoring to Default TLS Cipher Suite using ksctl

To restore to the default TLS Cipher suite of an Interface, run:

Example Request


ksctl interfaces restore-default-tls-ciphers --name nae_all_9009

Interface Default Connection (NAE and KMIP)

NAE and KMIP interfaces may be configured to use a default connection other than local_account for username/password authentication and client certificate authentication. Typically this setting is modified to simplify authentication because the username does not need to provide the connection name. For example, when a user presents their username for authentication without a connection, e.g. jdoe, then the CipherTrust Manager uses the default connection of the interface to authenticate the user. If the default connection is configured as local_account then the user is authenticated as if local_account|jdoe was presented. However, if configured as myldapdomain then the user is authenticated as if myldapdomain|jdoe was presented.

Example - Interface configuration update for KMIP to use a new default connection:

Command


$ ksctl interfaces modify -n kmip -d myldapdomain

Response


{
  "id": "476618b4-7310-4783-819f-517c387d2281",
  "name": "kmip",
  "mode": "tls-cert-pw-opt",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "kylo:kylo:naboo:localca:0d29d15d-0ddd-444d-8cc5-ffcc85d0928a",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:0d29d15d-0ddd-444d-8cc5-ffcc85d0928a"
    ],
    "external": []
  },
  "createdAt": "2018-07-09T14:49:43.316319Z",
  "updatedAt": "2018-07-09T14:49:50.136975Z",
  "default_connection": "myldapdomain"
}

SSL/TLS Server Certificate (NAE, KMIP, and WEB)

During initial bootstrapping of a new CipherTrust Manager, a new local KeySecure Root CA is automatically generated. This CA is later used to issue a server certificate for the interfaces available in the system. All interfaces and services trust this CA by default, meaning that a client certificate issued from this initial KeySecure Root CA is automatically trusted by the system.

Trusting the Default Server Certificate

Clients connecting to an interface examine the presented server certificate and match the signing CA against their trust stores. If the server certificate doesn't match, the client might present an error or close the connection. To avoid this mismatch, you can either add the KeySecure Root CA to the client truststore, so that the default server certificate is trusted, or you can upload an external, already trusted server certificate to the CipherTrust Manager interface.

Using an Externally Generated Server Certificate for an Interface

The CLI tool (ksctl) can be used to upload an external server certificate for a given interface. You can upload a certificate and private key or regenerate a self-signed certificate. Certificates (and the private key) can be uploaded in PEM or PKCS12 format. PKCS12 files are encrypted and require the use of --private-key-password.

The common name (CN) in the certificate must have a valid value.

We do not currently support encrypted PKCS8 keys embedded within a PEM file.

To use an externally generated server certificate for an interface
  1. Create the necessary external certificate chain, and combine them into a single PEM or PKCS12 file. The file should include the following certificates and key in the indicated order:

    1. The server certificate.

    2. Any intermediate certificate authorities that sign the server certificate. Start with the intermediate CA that issued the server certificate. Next, add the issuer of the intermediate CA, if any. Continue adding any intermediate CAs higher up the hierarchy, each time adding the issuer of the last certificate you uploaded.

    3. The external root CA that signs any intermediate CAs. If there are no intermediate CAs, add the root CA that issued the server certificate.

    4. The server certificate's private key.

  2. Add the PEM file for the server certificate's issuer to CipherTrust Manager's list of external CAs.

    $ ksctl ca externals upload –-cert-infile mycert.pem
    
  3. View the identifier for the uploaded external CA.

    $ ksctl ca externals list --cert-infile <ca-file-name>
    
  4. Look for the id field and copy this value. It is the <external-CA-identifier> in the next step.

  5. Change the Trusted CA for the desired CipherTrust Manager interface (nae in this example).

    $ ksctl interfaces modify --name nae --trusted-external-cas <external-CA-identifier>
    
  6. Disable auto-generation of the server certificate for the desired CipherTrust Manager interface (nae in this example). This command sets the auto-generation local CA to an empty string, indicating no autogeneration.

    ksctl interfaces modify --name nae --auto-gen-ca-id ""
    
  7. Upload the certificate chain file to the desired interface (nae interface is shown in the example)

    $ ksctl interfaces certificate modify --name=nae --format=pem --file=certchainfile.pem --private-key-password password
    
  8. Restart the CipherTrust Manager services for the change to take effect.

    ksctl services restart
    

Interface Mode (NAE, KMIP, and WEB)

The "mode interface" configuration parameter specifies the Interface mode, and must be one of the following:

  • no-tls-pw-opt: No TLS, allow anonymous logins.

  • no-tls-pw-req: No TLS, user must supply password.

  • unauth-tls-pw-opt: TLS, allow anonymous logins, ignore client cert.

  • unauth-tls-pw-req: TLS, user must supply password, ignore client cert.

  • tls-pw-opt: TLS, allow anonymous logins, verify client cert.

  • tls-pw-req: TLS, user must supply password, verify client cert.

  • tls-cert-pw-opt: Verify client cert, user name taken from client cert, auth request is optional.

  • tls-cert-and-pw: Verify client cert, password is needed, user name in cert must match user name in authentication request.

The following interface modes verify that the TLS client certificate is signed by one of the trusted CAs:

  • tls-pw-opt

  • tls-pw-req

  • tls-cert-pw-opt

  • tls-cert-and-pw-req

These interface modes extract the user name from the certificate:

  • tls-cert-pw-opt

  • tls-cert-and-pw-req

The interface mode can be changed using the API or the CLI "ksctl interfaces modify" command.

Interface restrictions on the interface mode

Each interface has the following restrictions on the interface mode:

  • nae: All modes are allowed. Default is unauth-tls-pw-opt.

  • web: The only allowed mode is unauth-tls-pw-req.

  • kmip: Only following modes are allowed:

    • tls-cert-pw-opt

    • tls-cert-and-pw

    • tls-pw-opt

certUserField Interface (NAE, KMIP, and WEB)

The certUserField Interface configuration parameter specifies how the user name is extracted from the client certificate. The default value is CN. This parameter must be one of the following:

  • CN: common name

  • OU: organizational unit

  • SN: surname

  • E: Email address

  • E_ND: email without domain; the data to the left of the @ sign in the email address is taken as the user name.

For KMIP, only CN is supported.

Certificate Signing Requests (CSR for NAE, KMIP, and WEB)

CSR provides you the ability to not expose private key for certificates created on the CipherTrust Manager for the Interfaces.

Adding a CSR

To add a CSR, run:

Syntax


ksctl interfaces csr add --name <interface-name> --common-name <common-name> --dns-name <dns-names-comma-separated> --email-address <email-addresses-comma-separated> --ip-address <ip-addresses-comma-separated> --csr-name <names-comma-separated> --csr-out-file <csr-file>

Example Request


ksctl interfaces csr add --name kmip --common-name admin 

Example Response


{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIEVTCCAj0CAQAwEDEOMAwGA1UEAxMFYWRtaW4wggIiMA0GCSqGSIb3DQEBAQUA\nA4ICDwAwggIKAoICAQDMo2aufRd1vB3F1tiGnQdRokmsXGc4nTMYVkYrNn1zqTqK\nJxLy1KY0/I07V+yWsZnbkXoieggBEo48FjqD2HDsr3K4BCSJOLkfW6velFGU+7+8\n6ei8eXZNJcBND6/RGRpe2Dz3xr17I4dbW4uoJhoPZeai3It2yPhWlvIDc7sah59l\nXTzKzuaAH24d6sJSD1OU0PN5SvGNw/v1D7VJoqsRrcytnhgCVav160ZWH24Pu4ty\nhBK2wi+ElhRlQSScA7h8s2BTFD/EG+TR2IinjAqNgCo4UspVJnADOGYkMJnSQlzl\nJFf1VIMEAJQ2lnRYzpDOdbit/6jSZgqlXUmt1PZE5LOxWCQ0yXNEUJtP/++K6CSl\nspVHGVwhWpD81tTwSYHq3Sx/aVvA/LSkfuOKgDFyclmxSM4o6qmKMYfanYyqaD9k\nTI/Xuf2aWrDWBRB3KqeKuVYj99tcTdcYbeYl4BeseAA8RJj5DOjLhnEAkgQWZN5O\nulT+uvBhCgVJaXPOJfIeGDnJkCeeAx1oa9RXztZItncUAvEWvS9Lvfl0YXnH9axf\n7ofqHhdocMX6w0yE42dGaqQQFWZCKsb+vUb2DaJrZCLQqoMitmHdMY+eOQacnxhN\niGzN43oEspGBaIxKFRFm/ZTvZc6hHCfhe6Uk6xqGUPgsIyzofoVsdarOq563MwID\nAQABoAAwDQYJKoZIhvcNAQENBQADggIBAGWhiUGy1TywCnScen8P1AkS+qUVKksR\niWP313J+3YW26aNfCtdsHdEzRCD/p/um8K6q5gEStdQRwMb0KaMdDYJTRR+1Wfi9\nT3xio6rVQbkBSgl6amCF36yuCX2QiHI2PfpBhTnV5Q16YOtjqLg+M2rxYMIKUpuB\nCsAmBbV2lRkl4M2vdP6GIjUuY/mAIRCh23cPeKaMi6vQthoMDRvBnybuZoh8YbEn\nbQ7tJbj0R/33zHRBUAUvNuN4qFSdOTB0icOnomFvOHGTe1ebDoR+jABCeS+ndePn\nIqf9hDi59NJQeR5huvbQa5gJMu1KMz1Hx4gQ2zTvHxS4K8VYFE4SMfpd8gNNKbJF\nVh2j+Mv3m5HPvwiGawEZAxZyRipyQ4GHc9pTCDdpfdyAfqOd3ogwEElnf2DfBb5x\n7mfiruOrcqQ9Kz6xYx2Xb0B3pSxTo5UamtL+ct5cabd+xQrhM7y2m5n8vvOkSne3\n+JH9wh7oMx3qRGzxS/aO9Fm6lGkE24f4QyO5KUHniD6Cl0E+mloMSIwb0hpX+zZf\nXs5v9JUAyaoiEeNsFsf01MDeIXuYYeY7x52qBNj8XsKbDeEnS9Fzf+qIX5Z2Lldb\ng0M6p/vXTZ+7YCFqphVnnx10E1BXnWBKDcOCDFXDxZ9clV+uxkVVJHgZFl1rNvyI\n1ATjjOZSmouN\n-----END CERTIFICATE REQUEST-----\n"
}

If CSR parameters are not provided, it will use the default values.

Getting CSRs of an Interface

To get the CSR of an Interface, run:

Syntax


ksctl interfaces csr get --name <interface-name> --csr-infile <csr-file>

Example Request


ksctl interfaces csr get --name kmip 

Example Response


{
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIEVTCCAj0CAQAwEDEOMAwGA1UEAxMFYWRtaW4wggIiMA0GCSqGSIb3DQEBAQUA\nA4ICDwAwggIKAoICAQDMo2aufRd1vB3F1tiGnQdRokmsXGc4nTMYVkYrNn1zqTqK\nJxLy1KY0/I07V+yWsZnbkXoieggBEo48FjqD2HDsr3K4BCSJOLkfW6velFGU+7+8\n6ei8eXZNJcBND6/RGRpe2Dz3xr17I4dbW4uoJhoPZeai3It2yPhWlvIDc7sah59l\nXTzKzuaAH24d6sJSD1OU0PN5SvGNw/v1D7VJoqsRrcytnhgCVav160ZWH24Pu4ty\nhBK2wi+ElhRlQSScA7h8s2BTFD/EG+TR2IinjAqNgCo4UspVJnADOGYkMJnSQlzl\nJFf1VIMEAJQ2lnRYzpDOdbit/6jSZgqlXUmt1PZE5LOxWCQ0yXNEUJtP/++K6CSl\nspVHGVwhWpD81tTwSYHq3Sx/aVvA/LSkfuOKgDFyclmxSM4o6qmKMYfanYyqaD9k\nTI/Xuf2aWrDWBRB3KqeKuVYj99tcTdcYbeYl4BeseAA8RJj5DOjLhnEAkgQWZN5O\nulT+uvBhCgVJaXPOJfIeGDnJkCeeAx1oa9RXztZItncUAvEWvS9Lvfl0YXnH9axf\n7ofqHhdocMX6w0yE42dGaqQQFWZCKsb+vUb2DaJrZCLQqoMitmHdMY+eOQacnxhN\niGzN43oEspGBaIxKFRFm/ZTvZc6hHCfhe6Uk6xqGUPgsIyzofoVsdarOq563MwID\nAQABoAAwDQYJKoZIhvcNAQENBQADggIBAGWhiUGy1TywCnScen8P1AkS+qUVKksR\niWP313J+3YW26aNfCtdsHdEzRCD/p/um8K6q5gEStdQRwMb0KaMdDYJTRR+1Wfi9\nT3xio6rVQbkBSgl6amCF36yuCX2QiHI2PfpBhTnV5Q16YOtjqLg+M2rxYMIKUpuB\nCsAmBbV2lRkl4M2vdP6GIjUuY/mAIRCh23cPeKaMi6vQthoMDRvBnybuZoh8YbEn\nbQ7tJbj0R/33zHRBUAUvNuN4qFSdOTB0icOnomFvOHGTe1ebDoR+jABCeS+ndePn\nIqf9hDi59NJQeR5huvbQa5gJMu1KMz1Hx4gQ2zTvHxS4K8VYFE4SMfpd8gNNKbJF\nVh2j+Mv3m5HPvwiGawEZAxZyRipyQ4GHc9pTCDdpfdyAfqOd3ogwEElnf2DfBb5x\n7mfiruOrcqQ9Kz6xYx2Xb0B3pSxTo5UamtL+ct5cabd+xQrhM7y2m5n8vvOkSne3\n+JH9wh7oMx3qRGzxS/aO9Fm6lGkE24f4QyO5KUHniD6Cl0E+mloMSIwb0hpX+zZf\nXs5v9JUAyaoiEeNsFsf01MDeIXuYYeY7x52qBNj8XsKbDeEnS9Fzf+qIX5Z2Lldb\ng0M6p/vXTZ+7YCFqphVnnx10E1BXnWBKDcOCDFXDxZ9clV+uxkVVJHgZFl1rNvyI\n1ATjjOZSmouN\n-----END CERTIFICATE REQUEST-----\n"
}

Auto-generation of Server Certificate (NAE, KMIP, and WEB)

By default, the CipherTrust Manager is configured to auto-generate a server certificate for each interface by using the initial Local CA. If the current certificate is issued by a different CA (other than the selected Local CA), auto-generation of the certificate is triggered every time the CipherTrust Manager service restarts. The current certificate becomes the certificate issued by the Local CA. As a result, this point onward, certificate auto-generation does not happen most of the times.

This feature is, especially, useful when a new node joins the cluster. The new node's existing Local CA is overwritten by the Local CAs from the cluster. In this case, the new node’s current certificate becomes issued by a Local CA unknown to the cluster. As a result, auto-generation happens on the first restart of the new node after it joins the cluster.

Changing the Local CA Used for Auto-generation

If needed, the Local CA used for auto-generation of the server certificate can be changed. Run the following command:

Example


$ ./ksctl interfaces modify --name web --auto-gen-ca-id kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a

Response


{
  "id": "3b85c5cf-6075-4555-a17c-2a12479081d4",
  "name": "web",
  "mode": "unauth-tls-pw-req",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a"
    ],
    "external": []
  },
  "createdAt": "2018-07-06T16:10:23.705291Z",
  "updatedAt": "2018-07-06T17:15:38.285859Z"
}

Disabling Auto-generation of Server Certificate

To disable the auto-generation feature, run the following command:


$ ./ksctl interfaces modify --name web --auto-gen-ca-id ""

Response


{
  "id": "3b85c5cf-6075-4555-a17c-2a12479081d4",
  "name": "web",
  "mode": "unauth-tls-pw-req",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a"
    ],
    "external": []
  },
  "createdAt": "2018-07-06T16:10:23.705291Z",
  "updatedAt": "2018-07-06T17:16:41.119686Z"
}

The auto-generation feature is automatically disabled if an external CA chain and server certificate are uploaded to the interface.

Customizing Auto-generation of Interface Certificate

To supply custom fields for auto-generation of an interface certificate, specify --local-auto-gen-attributes-file in the ksctl interfaces modify command. For example, run:


$ ./ksctl interfaces modify --local-auto-gen-attributes-file .json

The --local-auto-gen-attributes-file option specifies a file that contains attributes for auto-generation of a given interface. This provides an option to supply custom fields for automatic interface certification generation.

These parameters are for the local node only and have no effect on other nodes in a cluster. Without customization, the system default values are used, or taken from cloud-init, if applicable.

Content of a sample local auto-generation attributes file is:


{
  "cn": "KeySecure Server on ks.eng.thalesgroup.com",
  "dns_names": [
    "ks.eng.thalesgroup.com",
    "ks-ha.eng.thalesgroup.com"
  ],
  "email_addresses": [
    "admin1@eng.thalesgroup.com",
    "admin2@eng.thalesgroup.com"
  ],
  "ip_addresses": [
    "10.3.111.11",
    "10.3.111.22"
  ],
  "names": [
    {
      "C": "US",
      "ST": "CA",
      "L": "San Jose",
      "O": "Thales CPL",
      "OU": "Engineering"
    }
  ]
}

Trusted CAs (NAE, KMIP, and WEB)

Each interface can have a set of either local and/or external trusted CAs for client authentication. By default each interface trusts the initial Local CA for client authentication but it can be modified by updating the interface. Please note that the concept of trusted CAs is only relevant when client authentication is used by updating the interface mode.

Example - configuration update for web interface to trust the set of two Local CAs

Example


$ ./ksctl interfaces modify --name web --trusted-local-cas kylo:kylo:naboo:localca:d21584bd-7d8e-44a0-9eac-693f2fa32504,kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a

Response


{
  "id": "3b85c5cf-6075-4555-a17c-2a12479081d4",
  "name": "web",
  "mode": "unauth-tls-pw-req",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:d21584bd-7d8e-44a0-9eac-693f2fa32504",
      "kylo:kylo:naboo:localca:cf648c6d-2a0b-4427-a0b6-8f0e9157d15a"
    ],
    "external": []
  },
  "createdAt": "2018-07-06T16:10:23.705291Z",
  "updatedAt": "2018-07-06T17:35:29.053809Z"
}

Adding, Removing, and Modifying Interfaces (NAE and KMIP)

You can add and remove interfaces other than default interfaces (NAE, KMIP, and WEB). Currently, the Create and Delete commands are supported only for the NAE and KMIP interfaces.

To create a new NAE interface:

Example


$ ksctl interfaces create -o 9009 -y nae

Response


{
  "id": "456eb374-ec5c-40e8-bc89-4ab485c20c6c",
  "name": "nae_all_9009",
  "mode": "unauth-tls-pw-opt",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "kylo:kylo:naboo:localca:61476734-4778-40ec-a3be-06654d123513",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:61476734-4778-40ec-a3be-06654d123513"
    ],
    "external": []
  },
  "createdAt": "2019-01-21T05:52:57.657447Z",
  "updatedAt": "2019-01-21T05:52:57.657447Z",
  "default_connection": "local_account",
  "custom_uid_size": 0,
  "port": 9009,
  "network_interface": "all",
  "interface_type": "nae"
}
To create a new KMIP interface

Example


$ ksctl interfaces create -o 5697 -y kmip

Response


{
  "id": "90b3b131-d6d8-4985-abdd-539162c136c3",
  "name": "kmip_all_5697",
  "mode": "tls-cert-pw-opt",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "kylo:kylo:naboo:localca:c729ffe0-f6ad-49ad-8558-2db435b112c7",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:c729ffe0-f6ad-49ad-8558-2db435b112c7"
    ]
  },
  "createdAt": "2019-08-22T10:10:28.05794Z",
  "updatedAt": "2019-08-22T10:10:28.05794Z",
  "default_connection": "local_account",
  "port": 5697,
  "network_interface": "all",
  "interface_type": "kmip"
}
To modify TLS version of an interface

• The CipherTrust Manager supports TLS 1.1, TLS 1.2, and TLS 1.3.
• TLS 1.1 is deprecated and will be discontinued in a future release.
• Support for TLS 1.0 is discontinued. The existing Interfaces using TLS 1.0 will be migrated to TLS 1.2.

The TLS 1.3 version is supported from CipherTrust Manager 2.3 onward.


$ ksctl interfaces modify -n <interface name> -e <minimum tls version>

Here:

  • <interface name> can be NAE or KMIP interface name.

  • <minimum tls version> can be tls_1_1, tls_1_2, or tls_1_3. Support for tls_1_1 will be discontinued in a future release.

Example


$ ksctl interfaces modify -n kmip_all_5697 -e tls_1_2

Response


{
  "id": "6199c8d1-f59a-4bd1-8dfd-cf4d43900264",
  "name": "kmip_all_5697",
  "mode": "tls-cert-and-pw",
  "cert_user_field": "CN",
  "auto_gen_ca_id": "kylo:kylo:naboo:localca:afdebde8-a5ff-4cbd-9bb2-6dc5186e4c03",
  "trusted_cas": {
    "local": [
      "kylo:kylo:naboo:localca:0a4bf97b-1294-41d2-93cd-d19e6290cfa3",
      "kylo:kylo:naboo:localca:b7860db1-b7d1-4163-996e-22b14090d55a",
      "kylo:kylo:naboo:localca:afdebde8-a5ff-4cbd-9bb2-6dc5186e4c03"
    ]
  },
  "createdAt": "2019-08-28T05:21:05.36768Z",
  "updatedAt": "2019-08-28T07:41:38.62511Z",
  "default_connection": "local_account",
  "port": 5697,
  "network_interface": "all",
  "interface_type": "kmip",
  "kmip_enable_hard_delete": 0,
  "minimum_tls_version": "tls_1_2"
}
To delete an NAE interface:

Example


$ ksctl interfaces delete -n nae_all_9009
To create/modify the NAE interface to mask system groups from NAE requests

Command


$ ksctl interfaces create --type nae --port <port number> --mask-system-groups <bool>
$ ksctl interfaces modify -n <interface-name> --mask-system-groups <bool>

Here:

  • <interface name> : It is the name of the interface.

  • <bool> : It can be either true or false.

  • <port number> : It can be any postive number for which port is not allocated.

System-defined groups can be masked if the mask_system_groups flag is set to true for the NAE interface. The groups will be masked for:
• UserInfoRequest
• UserQueryRequest
• UserGroupInfoRequest
• UserGroupQueryRequest

Example


$ ksctl interfaces modify -n nae_all_9001 --mask-system-groups true

Response


{
  "id": "513abafa-c22c-471f-a6b9-42762efab3dd",
  "name": "nae_all_9001",
  "mode": "no-tls-pw-opt",
  "cert_user_field": "CN",
  "default_connection": "local_account",
  "port": 9001,
  "network_interface": "all",
  "interface_type": "nae",
  "minimum_tls_version": "tls_1_2",
  "enabled": true,
  "meta": {
    "nae": {
      "mask_system_groups": true
    }
  }
}