Deploying a Service
After you have initialized a service using CCC, you need to register your CCC client with the HSM used to host the service before you can begin to use the service. When you run ccc_client.jar, it automatically creates an NTLS or STC connection between your crypto application server and the device(s) associated with the service. The connection is NTLS unless the service configuration indicates that the STC should be enabled on the device partition(s).
Deploying NTLS Service
After downloading the CCC client, you'll be able to utilize it for the deployment of NTLS service. To initiate the deployment of NTLS service:
Open the ccc_config.env file and enable the SUBJECT_ALT_NAME flag by setting it to Y. Depending on your preference, set the SUBJECT_ALT_NAME_IP value to either your domain name (if accessing CCC via a domain) or your IP address (if accessing CCC via an IP address).
Restart the CCC container, based on your environment.
Create an application owner account and ensure that the application owner logs in to CCC and changes the password.
Go to the directory where you've stored the CCC client.
Launch the CCC client using the following command:
java -jar -DKEYCLOAK_PORT=keycloak_port ccc_client.jar -user username [-password password] [-otp otp_code] -host CCC_server_hostname_or_ipaddress [-port CCC_server_port]
Replace keycloak_port in the command with the port Keycloak is using in your setup. By default, the Keycloak port is 8180 for Podman, and 30037 for Kubernetes, Helm, and Azure environments. If you have configured a different Keycloak port, use that updated port value instead.
To ensure that CCC operates smoothly, it's necessary to have Java 21 installed on the computer where the ccc_client.jar file is stored.
When connecting to ccc-client.jar for the first time, informational logs may appear, such as retry attempts due to a "broken pipe" or "SocketException." These are normal and do not affect the client's functionality. No action is required.
If you enter a password, use single quotes (Linux) or double quotes (Windows).
For OTP, use the -otp parameter or provide the code when prompted.
The -port parameter is optional; default is 8181.
If the CCC server certificate isn't imported, you'll be asked to accept it.
If absent, a client certificate for NTLS connections is generated. Enter an IP or hostname for partition registration.
If you decide to trust the certificate permanently, set a trusted keystore password.
Choose from a list of available services for your organization.
Select option 1 to authorize access. This grants access to the chosen service.
In cases where a partition is added or removed from an existing service, the CCC application owner has the option to utilize the "Repair Access" feature. This feature establishes an NTLS link with the new service partition, which is then incorporated into the client's high-availability (HA) group.
When prompted with the message "Would you like to authorize access to the service 'Service_with_a_smile'? (Y/N):", respond with 'y'. After confirmation, a success message will indicate that access to the 'Service_with_a_smile' service has been granted.
To authorize a service for either a PPSO-enabled PED-authenticated HA Group or a Non-PPSO-enabled PED-authenticated HA Group, follow the steps detailed below. In both scenarios, access to the service will be provided upon completion of the authorization process.
Authorizing NTLS service for PPSO-enabled PED-authenticated HA group
To authorize an NTLS service for PPSO-enabled PED-authenticated HA Group:
Prepare for Access Authorization: Prior to proceeding with authorization, ensure that every partition within the HA group has been assigned an identical challenge password and has undergone activation.
Activate Service: Activate the service through the CCC user interface.
Initiate Authorization Process: To initiate the authorization process, run the ccc_client.jar tool. When prompted with "Would you like to authorize access to service 'Self_service'? (Y/N):", respond with 'y'.
Ensure Challenge Password Alignment: If you are certain that each partition within the HA group shares the same challenge password, input 'y'. You will then be prompted to enter the challenge password. Upon successful password entry, a confirmation will confirm that access to the service has been granted.
If challenge passwords are not aligned across all partitions in the HA group, input 'n'. The following prompt will be displayed: "Process paused. If you wish to align the CO challenges and activate the CO roles now, open a new console and run LunaCM to perform these operations. Once you have done so, select 'Continue' below to proceed with this HA Group configuration." Set the challenge password for each listed member as necessary.
The option to support the "Repair Client" feature for partially initialized PPSO-STC services is not available.
Authorizing NTLS service for Non-PPSO-enabled PED-authenticated HA group
To authorize an NTLS service for Non-PPSO-enabled PED-authenticated HA group:
Verify Challenge Password and Key: Prepare the 16-digit challenge password generated by the PED during service initialization, along with the partition owner/crypto officer (black) PED key.
If an incorrect challenge password is entered while deploying a PED-authenticated HSM Partition HA Group service using ccc_client, the service will be deployed but non-operational. To rectify this, redeploy the service by relaunching ccc_client, selecting the service, and revoking access.
Run ccc_client.jar: Execute the ccc_client.jar command, and continue until you encounter the prompt to input the group challenge. Each member of the HSM Partition HA Group service will be accessible as a slot in LunaCM.
Start Luna HSM Client Session: Launch a Thales Luna HSM client session by opening a command prompt or terminal window, then initiating LunaCM:
Windows: C:\Program Files\SafeNet\LunaClient\bin\lunacm
Linux: /usr/safenet/lunaclient/data/bin/lunacm
Check Firmware Versions: Review the list of available slots and take note of the firmware versions. If the partitions have firmware 6.22 or higher (released alongside software version 6.0), role commands are required in LunaCM for the subsequent steps. Firmware below 6.22 necessitates partition commands.
lunacm:> slot list
Select a Slot: Set the current slot to a slot containing one of the HSM Partition HA Group members:
lunacm:> slot set -slot [slot_number]
Connect the PED: Establish a connection with your remote PED server:
ped connect -ip [PED_IP]
Handle Firmware: Follow the appropriate steps based on your device's firmware version (below 6.22 or above 6.22):
Firmware Version Below 6.22
If using devices with firmware below 6.22, perform the following actions:
i. Log in to the partition and attend to the PED for orange (remote PED) and black (Partition Owner/Crypto Officer) PED keys:
lunacm:> partition login
ii. Set the challenge password for the partition:
lunacm:> partition changepw -p [new_challenge_password]
iii. Log out of the partition:
lunacm:> partition logout
iv. Log in to the partition. Attend to the PED:
lunacm:> partition login
v. Activate the partition:
lunacm:> partition activate
Firmware Version Above 6.22
If using devices with firmware above 6.22, perform the following actions:
i. Activate the Crypto Officer role by logging in. The PED prompts you for the black PED key:
lunacm: role login -name "Crypto Officer"
ii. Change the role's challenge password:
lunacm: role changePW -name "Crypto Officer" -old [old_challenge_password] -new [new_challenge_password]
iii. If the Crypto User regularly utilizes the service, log in to that role and change its challenge password. You will be prompted for the Crypto User PED key:
lunacm: role login -name "Crypto User"
role changePW -name "Crypto User" -old [old_password] -new [new_password]
iv. Log out from the Crypto User role. Repeat these steps for every partition in the HSM HA Group:
lunacm: role logout
Disconnect the Remote PED: lunacm: ped disconnect
Resume ccc_client.jar Session: Return to the ccc_client.jar session, input the group challenge, and continue to complete the service deployment.
Deploying STC Service
STC services are deployed in a slightly different manner than NTLS services due to the necessity of exchanging both client identity and partition identity public keys. If you have imported a service into CCC and activated both the STC and Per-Partition Security Officer (SO) policies before the import, please note that deploying the service will not be possible. This limitation arises because the Partition SO is only able to access and modify the partition through the existing STC client that was established before the import took place.
To deploy an STC service:
Initiate Terminal or Command Prompt: Begin by launching the Terminal on Linux or opening an Administrator command prompt on Windows. This should be done on the server where the Luna HSM client has been installed.
If you are utilizing a hard token, proceed to initialize it on a Windows computer following the guidelines provided in the Thales Luna HSM documentation.
Navigate to CCC Client Directory: Navigate to the directory where you've stored the CCC client.
Execute CCC Client: Run the CCC client (ccc_client.jar) using the following command:
java -jar ccc_client.jar -user <username> [-password <password>] [-otp <otp code>] -host <CCC_server_hostname_or_IP> [-port <CCC_server_port>]
To ensure that CCC operates smoothly, it's necessary to have Java 21 installed on the computer where the ccc_client.jar file is stored.
Enclose the password in single quotation marks (for Linux) or double quotation marks (for Windows), if included in the command.
Include the -otp parameter or respond when prompted for OTP-enabled accounts.
The -port parameter is optional; default port 8181 is used if not specified.
Confirm CCC Server Certificate: When prompted, verify and confirm the CCC server certificate. This message appears only if the certificate hasn't been imported on this client.
Create NTLS Client Certificate: If not already present, the client certificate for NTLS connections to service partitions is generated. Provide an IP or hostname for registration with partitions.
Enter Trusted Keystore Password (Optional): Choose to trust the certificate permanently if prompted, and input the trusted keystore password for the Java JDK on the Luna HSM client workstation. The default password is changeit.
Select Service for Authorization: A list of available services for your organization that can be deployed will be displayed. Choose the service you want to authorize for your client.
Authorize Service Access: Authorize access to the selected service by choosing option 1.
When employing both STC and Per-Partition SO for your service, please be aware that CCC lacks the capability to revoke STC access. This design choice has been made to mitigate the potential risk of rendering the partition(s) devoid of client connections, thus preventing any possibility of recovering partition access.
Create STC Client ID: If no STC client ID exists on the application server, create one by entering 'Y' and specifying a Client Name for registration on the partition(s).
Enter Partition SO Credentials (PPSO Enabled): For devices with the Per-Partition Security Officer (PPSO) feature enabled, provide Partition SO credentials to establish the connection.
For password-authenticated devices, you are prompted for the PSO password.
For PED-authenticated devices, provide the Remote PED IP and port. The remote PED will prompt for the orange Remote PED key and the blue Partition Security Officer key.
Change STC Client ID: The STC client ID label is displayed. You can change the label registered on the partition(s) if desired.
The deployment process for an STC service is now concluded. However, if you are in the process of authorizing a PED-authenticated HSM Partition HA Group service, please refer to the following procedure to successfully finalize the service deployment.
Authorizing STC service for PED-authenticated HA group
To authorize an STC service for PED-authenticated HA group:
Check Authorization Prerequisites: Before authorizing, ensure each partition in the HA group has the same challenge password and is activated. If PPSO is enabled, activate through the CCC UI. Otherwise, continue in this section.
Provide the Challenge Password: If challenge passwords match and partitions are activated, proceed with 'y' and provide the challenge password. Upon success, a confirmation message is displayed. If not successful, an error indicating mismatched challenge passwords will appear. In this case, re-run ccc_client.jar, answer 'n' to the challenge passwords prompt, and complete the procedure.
If you haven't set the same challenge password for all partitions in the HA group, type 'n'. This will pause the process and prompt you to align the CO challenges and activate the CO roles by opening a new console and running LunaCM. Once you've completed those actions, select 'Continue' to proceed with configuring this HA Group. Remember to set the challenge password for each member listed.
Accessing the Service
Once you have granted authorization to your client for accessing a service, you gain the ability to utilize the service for running client applications, including ckdemo, multitoken, or your custom applications. If the service is offered by a PED-authenticated device certified with FIPS Level 3 security, you must log into the device using a PED and a designated black PED key. This step is necessary before you can initiate the service's use. Every time you employ a client application through the service, you'll be required to present the black PED key—unless you opt to activate the partition that provides the service. By activating the partition, the need to present the black PED key for each use is eliminated. Activation enables you to log into the activated partition with a password. Remember, you can activate a partition using the LunaCM utility only if the partition's activation policy is set to "on." For detailed instructions, consult Thales Luna HSM Documentation.
Please be aware that on devices without the REST API enabled, CCC cannot be used to log in, modify partition policies, or activate partitions. To perform these tasks, employ the Thales Luna HSM Client utilities.
