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.
Note
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.
Note
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 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">
- ...
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">
- ...
A working cloud-init configuration could look as follows:
#cloud-config
keysecure:
default-ca:
CN: Cloud-init test CA
emails:
- certadmin@example.com
- support@example.com
names:
- C: US
ST: TX
L: Austin
O: Gemalto Inc.
OU: Gemalto
- C: Sweden
L: Gothenburg
O: Gemalto AB
default-server-cert:
CN: Cloud-init test server cert
emails:
- certadmin@example.com
- support@example.com
names:
- C: US
ST: MD
L: Belcamp
O: Gemalto Inc.
OU: Gemalto
- C: Sweden
L: Stockholm
O: Gemalto AB
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
Note
This parameter must be set before the first boot of the system since it is ignored after the first boot.
Note
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:
Note
Static IP is only supported via cloud-init, and must be done on initial boot of a service.
!yaml
cloud-config
keysecure: netcfg: iface: name:
Configuring Disk Encryption
For added security, the disk of Virtual CipherTrust Manager can be fully encrypted with the public SSH key associated with the instance. 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, the SSH key is provided after first launch.
Warning
Disk encryption is not supported for physical appliances. Attempting to encrypt the disk of a physical appliance might result in losing all access to the device and its data.
Encryption can either be initiated when an instance is first launched with cloud-init or on an already launched instance with CipherTrust Manager CLI commands. Because installation specific secrets are generated the first time a Virtual CipherTrust Manager instance is run, it is recommended that the instance be encrypted at launch time to ensure these secrets are never exposed. Cloud-init is best suited to configuring disk encryption at first launch.
Warning
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.
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
#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.
To check 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.
To unlock 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.
Note
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.
Note
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.
Note
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
Note
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.
!yaml
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>
