5c 10G Agent Initial Configuration Service
The Agent Initial Configuration Service is a REST API that runs on a factory-stated nShield Connect 5c 10G HSM. It provides the capability to initially configure the Platform KeySafe 5 Agent so that it can connect to a KeySafe 5 instance.
The recommended way to use this service is through the KeySafe 5 WebUI or HSM Management REST API interface. When you perform a Platform HSM Enrollment operation in KeySafe 5, the HSM Management Service communicates with the Agent Initial Configuration Service to:
-
Synchronize the HSM time with the time on the KeySafe 5 instance.
-
Verify that the HSM being enrolled is a genuine Entrust HSM.
-
Confirm that the HSM being enrolled has not been tampered with.
-
Configure the Platform KeySafe 5 Agent to connect to a KeySafe 5 instance.
See the KeySafe 5 User Guide for more details on this enrollment workflow.
The Agent Initial Configuration Service remains active until the platform KeySafe 5 Agent is configured and has successfully connected to a KeySafe 5 central platform. Once the agent is successfully connected, the only way to restart the Agent Initial Configuration Service is to factory state the HSM.
Direct use of the Initial Configuration REST API
The 5c 10G Agent Initial Configuration Service runs as an HTTPS service on port 18075 that you can use directly.
Obtain the IP address of your nShield 5c 10G HSM from the HSM front panel or the Serial Console. You can change this IP address using one of the following options:
-
The Agent Initial Configuration Service.
-
The HSM front panel (this functionality is only available when the platform KeySafe 5 Agent on the HSM is not connected to a KeySafe 5 instance).
-
The Serial Console.
HTTPS Server Certificate
The server certificate for the Agent Initial Configuration Service uniquely identifies the HSM. The subject of the leaf certificate contains the ESN and serial number of the HSM. You should confirm that these serial numbers match the expected serial numbers for your HSM before you proceed with configuring the KeySafe 5 Agent.
To verify that this is a genuine Entrust HSM, the server certificate contains a certificate chain that can be verified against the following PEM-encoded root certificate.
-----BEGIN CERTIFICATE-----
MIICKDCCAYqgAwIBAgIUIQEg8gHWTc8OrvtuMUpmmuEfp5EwCgYIKoZIzj0EAwQw
JTEjMCEGA1UEAwwaRW50cnVzdC1LTFItQ2VydGlmaWVyLVJvb3QwIBcNMjUwOTE2
MTE0NTAwWhgPMjEyNTA5MTYxMTQ1MDBaMCUxIzAhBgNVBAMMGkVudHJ1c3QtS0xS
LUNlcnRpZmllci1Sb290MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAnju3JTex
aLflQHEF4ZtkvSCSEsKf5T1dqMELUl5tbi6XqTBFRGUqsSNM+PBA/fx/yodqZh6d
LLdcJRA7C4oNDr0BMVh+FKzUcA8TxenY9xWZL9wCNvWyDCFSJGrh2n+FWc9ex6Rk
hlfJV1gKqAqTXklwlyhuPm/3yIAMQiBSbtKDedyjUzBRMB0GA1UdDgQWBBTaQVd2
HKxmRbZDtePAZjx1qYRgBjAfBgNVHSMEGDAWgBTaQVd2HKxmRbZDtePAZjx1qYRg
BjAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMEA4GLADCBhwJBGHDZSNdO2tHz
ypdy5uCITQenHK51jz9qXYSyxrdrYXoTbU9st1xdi1bW6FWYxa9mP0tr8XlFXvyh
+5BZir2/1A0CQgDxgqDuw+T4a4yzuY6QmdW66xZE8F1DMM7xPj1RmHRUZMQ2BCxK
y1fQO+evlQ8lgjQI8rtOaAzcOdzXfzK7XS7Krw==
-----END CERTIFICATE-----
For example, to verify the server certificate chain of the Agent Initial Configuration Service running on a 5c 10G HSM at 169.254.10.20, use openssl with the above certificate saved locally as ca.crt:
$ openssl s_client -CAfile ca.crt -connect 169.254.10.20:18075 </dev/null | openssl x509 -verify -noout
depth=3 CN = Entrust-KLR-Certifier-Root
verify return:1
depth=2 CN = Entrust-KLR-Certifier, C = UK, L = Cambridge, ST = England, O = Entrust, emailAddress = nshield.support@entrust.com
verify return:1
depth=1 CN = Entrust-KLR, serialNumber = AAAA-AAAA-AAAA, UID = 46-RC0001, C = UK, L = Cambridge, ST = England, O = Entrust, emailAddress = nshield.support@entrust.com
verify return:1
depth=0 CN = Entrust-KIC, serialNumber = AAAA-AAAA-AAAA, UID = 46-RC0001, C = UK, L = Cambridge, ST = England, O = Entrust, emailAddress = nshield.support@entrust.com
verify return:1
DONE
Initial HSM Configuration
To support the configuration of the KeySafe 5 Agent to connect to a KeySafe 5 instance, the Agent Initial Configuration Service provides a minimal subset of HSM Management operations.
HSM Information
A GET request to the /init/v1/hsm API endpoint retrieves information about the HSM, including the module and platform versions.
Network
Use the /init/v1/network API endpoint for basic network configuration. A PATCH request sets a single-port static IP address and gateway for the management network interface. A GET request to the API endpoint returns the current management network state, including any configured or dynamically assigned addresses and gateways.
Enroll a 5c 10G Platform HSM to KeySafe 5
Before enrolling the HSM, you should check the HSM Tamper State.
To configure the KeySafe 5 Agent to connect to KeySafe 5:
-
Download a Certificate Signing Request (CSR) for the KeySafe 5 Agent.
This is a GET request to the /init/v1/agent/csr API endpoint and returns the Base64URL encoded CSR PEM file in the data.csr field of the JSON response body. -
Sign the CSR using the CA for your KeySafe 5 instance.
-
Upload the agent’s TLS certificate and CA certificate and configure the IP address of the KeySafe 5 instance that this agent will connect to.
This is a PUT request to the /init/v1/agent API endpoint with a JSON request body containing:-
centralConnection.url: The IP address and port of the KeySafe 5 instance being connected to
-
certificate: The Base64URL encoded agent TLS certificate
-
ca: The Base64URL encoded CA certificate
-
HSM Tamper Check
Use the /init/v1/tamper-evident-certificate API endpoint to check the tamper state of the HSM.
The tamper check is a cryptographic challenge/response. To perform the tamper check:
-
Generate a sequence of random challenge bytes.
-
Generate an X25519 key which will be used to verify the challenge response.
-
Send a GET request to the API endpoint with the following query parameters:
-
challenge: The Base64URL encoded challenge bytes.
-
public: The Base64URL encoded public key (generated in Step 2).
The HSM platform uses it to generate a shared secret, which is then used with the challenge bytes to generate the challenge response
-
The JSON response body will contain the following fields:
-
data.certificate: The HSM platform’s Base64URL encoded TLS certificate and can be verified to ensure the challenge response came from a legitimate untampered Entrust HSM.
-
data.response: The HSM platform’s Base64URL encoded response to the tamper challenge which can be verified using a shared secret derived from your public key and the public key in certificate.
The certificate can be verified against the following PEM-encoded root certificate.
-----BEGIN CERTIFICATE-----
MIICLjCCAZCgAwIBAgIUeVIPcgcTmMLBioWte4gFfdmXnDUwCgYIKoZIzj0EAwQw
KDEmMCQGA1UEAwwdRW50cnVzdC1LQ09TTU8tQ2VydGlmaWVyLVJvb3QwIBcNMjUw
OTE2MTEzNDE3WhgPMjEyNTA5MTYxMTM0MTdaMCgxJjAkBgNVBAMMHUVudHJ1c3Qt
S0NPU01PLUNlcnRpZmllci1Sb290MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQA
90VdwScUaDwmwCgYoR459v9N0koclEACwF3/PuLw6/jgVWPpnzKmOjwYM1KoF1/V
IIXwQz5Io+BhuDkVEJktYZMB5yvH68NYAQX701ddCDYXhvrwNojec2n/sHXgOCqj
c8a0PG5kXfu+Dt5vFqXSOJ4o6OZ4AxLM6xZLCX6Ag6USUZijUzBRMB0GA1UdDgQW
BBQL6X8FqqBXJgXDIWa2OiBPPv7e/jAfBgNVHSMEGDAWgBQL6X8FqqBXJgXDIWa2
OiBPPv7e/jAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMEA4GLADCBhwJBPgDk
t2meZHaSex2wE6w3BPm6XsaGHvX1aFfntxyT8nEFm77IqRplThzjwuR0Z1RyGFqI
dDHysxb1YYne47Bzmb4CQgFXzPfZcKnpU+Am1TF25g5CJMxjb3rg5nEvoYOlIawi
qwD5TKscpfqJh2uOSopjOJdh8oFY3h7DRoK+WCJ+Y8Ty1w==
-----END CERTIFICATE-----
To verify the challenge response:
-
Extract the public key from the certificate.
-
Perform an ECDH key exchange using the extracted public key and your private X25519 key to generate a shared secret.
-
Calculate the expected challenge response using the single-step key derivation function (KDF) defined in NIST SP800-56C Revision 2 with SHA512 hash algorithm.
|
For the key derivation method defined in NIST SP800-56C as KDM(Z, OtherInput): Z is the shared secret calculated from the ECDH key exchange. OtherInput is the original random challenge bytes. The length of the secret keying material to be derived (the length of the challenge response) is 64 bits. |
If the calculated challenge response is equal to the challenge response returned by the HSM, then the HSM has not been tampered with.