Plan Configuration Settings for Cloud Init

With a user-data file, you can set the initial password for the initial user, the default CA and server certificates, IPv6 network settings, a static IP, disk encryption, and HSM integration.

Cloud-init configuration (user-data) files uses YAML syntax; indentation is important and tabs can not be used.

Configuring Initial Password for the Initial User

The initial password for the initial Application Administrator can be auto-generated using a cloud-init configuration file containing the following setting:

  #cloud-config
  keysecure:
      initial-user:
        generate-password: true

Configuring Default CA and Server Certificates

Two certificates are created by default during initial boot-strapping of the CipherTrust Manager, one Self-signed Root CA Certificate and one Server Certificate that is signed by the Root CA.

CipherTrust Manager does not support dns/ip atm; only the emails field is supported, regardless of the oid setting.

Configuring Initial Default Certificates

Before the first boot of the system, the content of these certificates can be overwritten with the help of a cloud-init configuration as follows:

#cloud-config
keysecure:
    default-ca:
        CN: <Common Name of Root CA Certificate, for example "Cloud-init test CA">
        emails:
          - <Subject Alternate Name E-Mail, for example "foo@example.com">
          - ...
        names:
          - C: <Country, for example "US">
            ST: <State/province, for example "TX">
            L: <Location, for example "Austin">
            O: <Organization, for example "Gemalto Inc.">
            OU: <Organizational Unit, for example "Gemalto">
          - ...
        dns-names:
            - <Subject Alternate Name DNS-Name, for example "web.keysecure.local">
            - ...
        ip-addresses:
            - <Subject Alternate Name IP-Address, for example "13.32.240.3">
            - ...
    default-server-cert:
        CN: <Common Name of Server Certificate, for example "Cloud-init test server cert">
        emails:
          - <Subject Alternate Name E-Mail, for example "foo@example.com">
          - ...
        names:
          - C: <Country, for example "US">
            ST: <State/province, for example "TX">
            L: <Location, for example "Austin">
            O: <Organization, for example "Gemalto Inc.">
            OU: <Organizational Unit, for example "Gemalto">
          - ...
        dns-names:
            - <Subject Alternate Name DNS-Name, for example "web.keysecure.local">
            - ...
        ip-addresses:
            - <Subject Alternate Name IP-Address, for example "13.32.240.3">
            - ...

A working cloud-init configuration looks as follows:

#cloud-config
keysecure:
  default-ca:
    CN: Cloud-init test CA
    emails:
      - certadmin1@example.com
      - support1@example.com
    names:
      - C: US
        ST: TX
        L: Austin
        O: Gemalto Inc.
        OU: Gemalto
      - C: Sweden
        L: Gothenburg
        O: Gemalto AB
    dns-names:
      - web.keysecure.local
      - web.ciphertrustmanager.local
    ip-addresses:
      - 13.32.240.3
      - 93.184.216.34
  default-server-cert:
    CN: Cloud-init test server cert
    emails:
      - certadmin2@example.com
      - support2@example.com
    names:
      - C: US
        ST: MD
        L: Belcamp
        O: Gemalto Inc.
        OU: Gemalto
      - C: Sweden
        L: Stockholm
        O: Gemalto AB
    dns-names:
      - web.keysecure.local
      - web.ciphertrustmanager.local
    ip-addresses:
      - 13.32.240.3
      - 93.184.216.34

The only required field is 'CN'. If it is missing the rest are ignored. If any of the remaining are missing, they will be empty when the certificate is created. If there is no default-ca or default-server-cert section, the defaults will be used for the missing section.

Configuring IPv6

There are two formats for IPv6 configuration, 'auto' and 'dhcp'. All systems come configured to use 'auto' as the default.

To set 'dhcp' as the default, add the following cloud-init directive to the user-data:

#cloud-config
keysecure:
    netcfg:
        config_ipv6: dhcp

This parameter must be set before the first boot of the system since it is ignored after the first boot.

Do not use 'dhcp' on AWS if there are no IPv6 interfaces defined. This will result in a five-minute delay during each boot of your firmware

Configuring the CipherTrust Manager with a Static IP

The CipherTrust Manager OVA and Qcow2 disk images can be configured with a Static IP using cloud-init. The configuration format is as follows:

Static IP is only supported via cloud-init, and must be done on initial boot of a service.

#cloud-config
keysecure:
    netcfg:
        iface:
            name: <interface name>
            type: <static>
            address: <ip address to be assigned>
            netmask: <net mask in x.x.x.x format>
            gateway: <gateway ip address>
            dns1: <dns server's ip address, optional>
            dns2: <alternate dns server's ip address, optional>

The interface names vary between cloud providers. The current name for the first network interface for various clouds is listed in the table below. These names might change in the future depending on how a cloud provider presents the virtual network interface to the operating system.

Configuring Disk Encryption

For added security, the disk of CipherTrust Manager can be fully encrypted with the public SSH key. For public cloud deployments on Amazon Web Services, Google Cloud, Microsoft Azure, or Oracle Cloud, this SSH key was provided during first launch. For private cloud deployments or physical appliance, the SSH key is provided after first deployment.

Encryption can either be initiated when an instance is first launched with cloud-init or on an already deployed instance with CipherTrust Manager CLI commands. Because installation specific secrets are generated the first time a CipherTrust Manager instance is run, it is recommended that all Virtual CipherTrust Manager instances be encrypted at launch time to ensure these secrets are never exposed. Cloud-init is best suited to configuring disk encryption at first launch.

After encrypting the disk, you need to unlock the encrypted instance on every boot using the 'ksctl diskenc secureboot' command and the private SSH key associated with the instance. See To unlock an encrypted instance. Disk encryption is always applied on reboot, and this behavior cannot be disabled. If you wish to store your keys on an unencrypted CipherTrust Manager, you can deploy a new CipherTrust Manager and then use backup and restore to transfer keys and other data.

Encrypting an Instance at First Launch

To configure the instance to encrypt at launch, use the cloud-init settings below for private cloud deployments. You must provide the public SSH key you will associate with the CipherTrust Manager instance in OpenSSH format. The corresponding private key to unlock can be in OpenSSH, PKCS1, or PKCS8 format. The supported key algorithm is RSA. We recommend RSA 4096, with RSA 2048 as a minimum size for adequate security.

ssh-keygen produces OpenSSH format public keys by default. You can also use ssh-keygen to convert an existing PEM public key to OpenSSH with ssh-keygen -y -f public_key.pem > public_key.pub

#cloud-config
diskenc:
    encrypt: true
ssh_authorized_keys:
    - <replace with user's ssh public key>

For public cloud deployments on Amazon Web Services, Google Cloud, Microsoft Azure or Oracle Cloud, the SSH key is already provided during virtual image configuration, so you don't have to specify the SSH key in the user-data file.

#cloud-config
diskenc:
    encrypt: true

This file must be passed to the CipherTrust Manager instances, which uses cloud-init to enable the encryption. How this file is passed to the CipherTrust Manager appliance depends on the environment in which it is run. For other examples of passing cloud-init config.dat file in supported environments, go to Deploying with Cloud Init.

Checking Encryption Status

To check the encryption progress, you can run following CLI command:

ksctl diskenc status -p

This returns a response similar to:

Encrypting...

14.81 GiB / 15.52 GiB [====================================>-----] 95.44% 11s

This command might time out during system restart or due to a slow connection. As an alternative, you can view the Console for the instance to see disk encryption progress.

Unlocking an Encrypted Instance

The instance will start up after the encryption has finished. To unlock the instance, you must run following CLI command and provide the SSH private key in PEM format. OpenSSH format private keys are not supported.

ksctl diskenc secureboot -i <ssh key used to launch the instance> -u https://<instance dns name>

Every time an encrypted instance boots, the above CLI command must be executed to unlock the instance and allow admins and users to login and configure the Virtual CipherTrust Manager or access their keys.

Configuring HSM Integration

The CipherTrust Manager can be configured to use an HSM as a root of trust. This can be done using cloud-init.

HSM configuration is now performed through the API. Using the cloud-init method is not recommended because it exposes sensitive information, such as the partition password, that can be viewed by anyone with access to the associated AWS console. For more information refer to Hardware Security Module.

Before connecting an HSM to the CipherTrust Manager, the HSM must be set up and configured by an HSM Administrator. This includes creating a partition and partition password, and generating a client certificate for the CipherTrust Manager.

To enable HSM integration using cloud-init, user-data is supplied to cloud-init. This file must be passed to the CipherTrust Manager instances that uses cloud-init to enable the encryption. How this file is passed to the CipherTrust Manager appliance depends on the environment in which it is run. For a list of supported environments, see Overview.

Cloud-init configuration (user-data) files uses YAML syntax; indentation is important and tabs can not be used.

Example - Configuring CipherTrust Manager to use SafeNet Luna Network HSM

#cloud-config
keysecure:
    hsm:
        type: luna
        # Replace dummy partition name and password values below with your existing Luna HSM settings.
        conninfo: '{"partition_name": "kylo-partition","partition_password": "sOmeP@ssword"}'
        config:
            # luna host name or ip address
            host: 172.20.32.11
            # luna server PEM encoded cert
            server-cert: |
                    -----BEGIN CERTIFICATE-----
                    ...
                    -----END CERTIFICATE-----
            # luna client PEM encoded cert
            client-cert: |
                    -----BEGIN CERTIFICATE-----
                    ...
                    -----END CERTIFICATE-----
            # luna client PEM encoded cert private key
            client-cert-key: |
                    -----BEGIN RSA PRIVATE KEY-----
                    Proc-Type: 4,ENCRYPTED
                    DEK-Info: DES-EDE3-CBC,92852AD5AFE768B8
                    ...
                    -----END RSA PRIVATE KEY-----

Example - Configuring CipherTrust Manager to use AWS CloudHSM (cavium)

#cloud-config
keysecure:
    hsm:
        type: aws
        # Replace dummy crypto user credentials below with your actual CloudHSM CU credentials.
        conninfo: '{"partition_name": "cavium","partition_password": "hsmuser:password"}'
        config:
            # CloudHSM Cluster ENI IP Address
            host: 172.20.32.11
            # CloudHSM Cluster certificate
            server-cert: |
                    ----BEGIN CERTIFICATE----
                    ...
                    ----END CERTIFICATE----

Example - Configuring CipherTrust Manager to DPoD Luna Cloud HSM service

DPoD cloud configurations are sometimes above the AWS size limit for user data. Verify the user data is 16KB or less, otherwise it will be ignored by AWS. If it is larger then remove unnecessary whitespace (e.g. ident lines with a single space) and comments.

#cloud-config
keysecure:
    hsm:
        # type: Specifies HSM type as dpod.
        type: dpod

        # conninfo: "partition_name" and "partition_password"
        # {
        #     "partition_name': '',  # HSM partition name provided during partition provisioning
        #     'partition_password': '',  # HSM Crypto Officer password
        #  }
        conninfo: '{"partition_name": "kylo-partition","partition_password": "sOmeP@ssword"}'

        # config: include the following attributes:
        # {
        #     'server_cert': '',  # Server certificate in PEM format from server-certificate.pem file.
        #     'partition_cert': '',  # Partition certificate in PEM format from partition-certificate.pem file
        #     'partition_ca_cert': '',  # Partition CA certificate in PEM format from partition-ca-certificate.pem file
        #     'cv_app_specific_data': '',  # CVAppSpecificData value from Chrystoki.conf file
        #     'cv_partition_data': '',  # PartitionData00 value from Chrystoki.conf file
        #  }
        #
        config:
            server_cert: |
                -----BEGIN CERTIFICATE-----
                ...
                -----END CERTIFICATE-----
            partition_cert: |
                -----BEGIN CERTIFICATE-----
                ...
                -----END CERTIFICATE-----
            partition_ca_cert: |
                -----BEGIN CERTIFICATE-----
                ...
                -----END CERTIFICATE-----
            cv_app_specific_data: <CVAppSpecificData>
            cv_partition_data: <PartitionData00>