Registering CT-VL VM with CipherTrust Manager
Complete the following procedure to register CT-VL with the CipherTrust Manager (CM) server.
Create a user and set a password for it.
Besides client certificate authentication, CM servers require user/password authentication for key access.
Optional: Create a user-group on the CM server.
In addition to granting key access to a user, key access can be granted to a group. Users belonging to that group have access to the group keys.
Create symmetric AES keys for CT-VL use on the CM server using the properties below:
Key type: AES
Key size: 256 bits
Exportable: yes
Prevent keys from being deleted: yes
Key properties: Encrypt and Decrypt
Owner: CT-VL user in Step #1 above
Group: Group in Step #2 above
Note
Check for Recommendations for Secure Initialization Vector in encryption requests.
If not already created, create a local CA on the CM server.
This will be used by CT-VL for client certificate authentication.
Create an NAE interface on the CM server using the following properties:
Type: NAE
Port number: 9000
Mode: TLS; user must supply password; verify client certificate
Username Location in Certificate: CN
Local CA: (select)
Network interface: (select)
Set up CT-VL with IP(s), port, and user credentials to the CM server.
Log in to the CT-VL CLI and run the
icapi --set
command:icapi set --IP <CM_ip> --port 9000 --user ctvluser
If the
ctvluser
is under a domain, supply the domain name as shown below. Take note of the double bar (pipe) character separating thedomainname
andctvluser
.icapi set --IP <CM_ip> --port 9000 --user domainname||ctvluser
When prompted, enter the password of the
ctvluser
on the CM server.If the key manager is a cluster of servers, supply all the IP addresses of the servers in the cluster. For example:
icapi set --IP ip1 ip2 ip3 --port 9000 --user <ct-vl-user>
Run the icapi show --properties command to inspect the settings made. For example:
main> icapi show --properties Client_Cert_Authentication yes KEYSTORE_PASSWORD ******** KEYSTORE_USER ctvluser NAE_IP ['10.3.211.79'] NAE_Port 9000 Protocol ssl Version 3.1
Register CT-VL to the CM server with either an automated registration or a manual registration.
To perform automated registration:
Log in to the CT-VL CLI and run the icapi register command. For example:
main> icapi register --host 10.3.211.79 --user <adminuser>
This command requires the user credentials on the CM server that has admin rights to the local CA. It creates a client certificate on the CT-VL that is signed by the CM server. This serves as the client certificate authentication whenever CT-VL connects to the CM server.
This command prompts for the password of the CM admin user and the information to create the certificate.
For example:
main> icapi register --host 10.3.211.79 --user admin password: Running registration will delete any existing CA and client certificates. Do you wish to continue? <y/n> [n] y Country Name (2 letter code) [US]: State or Province Name [California]: Locality Name (e.g., city) [San Francisco]: Organization Name (e.g., company): Organizational Unit Name: Common Name (eg, server's hostname) [ctvl-250-263-202]: Created Private-Key: (2048 bit) CA certificate updated Client certificate updated Registration complete CM signed certificate: id : f22e722f-4135-44c7-9e78-c03b1acc83da ca : kylo:kylo:naboo:localca:8d2889d6-45a4-4981-95e8-d1589238deb8 issuer : /C=US/ST=MD/L=Belcamp/O=Gemalto/CN=CM Root CA notAfter : 2030-02-09T21:05:22Z serialNumber : 195829222921448800841697297203339489128 sha1Fingerprint : 4C5B96B0F0C3D6FCF06C905E49965E4BCF370824 sha256Fingerprint : EB7E39AD001EF9B63F9DF1370569869813869B1D592F0130CF6CADB501E625F1 subject : /C=US/ST=California/L=San Francisco/CN=ctvl-250-263-202
A successful registration will display the client certificate information and its fingerprint.
Log in to the CM server and verify that the certificate information and fingerprint match
Notes:
• If the CM server has more than one Local CA, the automated registration uses the first Local CA found. If the desired Local CA is not the first on the list, use the --caid option to supply the ID of the desired Local CA. You can use the show --LocalCAs command to view the ID of all the local CAs on the CM server:main> icapi show --LocalCAs --user <adminuser>
• By default, the certificate is set to expire in 10 years. Use the --days option to set the desired expiration.
• The registration command can be run in non-interactive mode by supplying all parameters to the command. Run the icapi register --help command for details.
To perform manual CM registration:
Use the following procedure to register CT-VL to a CM server. You can also use this manual procedure if you do not want to automatically register, or for some other reason cannot automatically register.
Some reasons for using manual registration include:
• Network connectivity from CT-VL to CM is not yet in place.
• The user performing auto-registration does not have administration credentials to the CM server. The user credentials to perform registration must include permission to run REST APIs on the server, permission to download the Local CA, and permission to sign a certificate request.
• Access to the REST API (port 443) of the CM server is blocked.
• An imported private key is desired instead of letting CT-VL generate a random key internally.
• A common client certificate is desired for several CT-VL servers, for example, with CT-VL servers in a cluster.
a. Create a certificate private key on the CT-VL:
main> icapi create --client_key
You may import a private key instead of letting CT-VL create one. Use the icapi upload command to import a private key.
b. Create a certificate signing request:
main> icapi create --csr
This command creates a certificate signing request using the private key you have created or imported.
c. Using the CSR you now generated, log in to the CM server and locate the Local CA to sign the CSR.
The signed CSR produces a certificate in PEM format.
d. Import the signed certificate into the CT-VL using the upload command:
main> icapi upload --client_certificate
e. Log in to the CM server and download the Local CA. Import this certificate into the CT-VL using the icapi upload --CA_certificate command:
main> icapi upload --CA_certificate
Enable ICAPI.
Run icapi enable yes command to enable CT-VL access to the CM server. For example:
main> icapi enable yes Restarting vts (via systemctl): [ OK ] ICAPI properies updated
Test connectivity to the CM server.
Use the icapi test --server_connection command to test server connectivity to the CM server. For example:
main> icapi test --server_connection Test server connection using user: vts-user1 10.3.211.79: OK
This command tests the connection and authentication to the CM server. A successful authentication confirms correct CM user credentials and a valid client certificate.
Test access to an AES key.
Use the icapi test --key command to test access to an AES key on the CM server. For example, to test access to a CM key named vts-key:
main> icapi test --key vts-key vts-key: OK
This command tests if the saved user credentials provide proper access to the specified key. This test requires correct user and client certificate authentication to the CM server.
Troubleshooting and Automation Tips
Make sure the icapi test CLI commands pass before setting up CT-VL for tokenization use.
Use the icapi show CLI command to inspect if the icapi agent is enabled or not, if certificates are created or uploaded, and if server settings are correct.
All CLI commands can be run in non-interactive mode. This mode is ideal for automating setup.
Security Tips
Consider the following guidelines when configuring CT-VL to ensure maximum security:
When setting up the NAE interface, it is highly recommended to use the following mode for best security:
TLS, user must supply password, verify client cert.
Although other modes are possible, anything other than the above would be less secure.
When creating a user for CT-VL to use on the CM server, do not use a user with admin privileges or access to any keys that CT-VL will not use. The Keystore user should only have the following:
login access.
key access privileges.
access to the keys that CT-VL will use.
Note
Do not add the Keystore user to the "Key Users" group as this may allow the user access to keys that CT-VL does not use. Preferably, create a group for CT-VL, assign to that group all the keys that CT-VL will use, and then add the Keystore user to that group.