Setting the system clock

This guide covers the following HSMs:

  • nShield 5s

Entrust recommends that you set the HSM system clock before performing any other actions. This is because the HSM clock may have drifted from real time whilst the HSM was running on battery power in storage.

The HSM system clock is set by fetching the current time and date from the host machine in which the HSM is fitted. Therefore it is important to check that the time and date is set correctly on the host machine.
Initial setting of the HSM system clock should be performed with the HSM in maintenance mode. If your HSM is not in maintenance, you must put it into maintenance mode. For instructions, see nShield 5s modes of operation.

Setting the HSM system clock

  1. Make sure that the date and time on the host machine are set correctly according to the documentation for the operating system on the host machine.

  2. Run the following command as a user with root privileges on Linux or the privileges of the built-in local Administrators group on Windows:

/opt/nfast/bin/hsmadmin settime
The settime command uses UTC date and time format.
When you are setting time at the very first time on an nShield 5s HSM, it is recommended to avoid the optional --adjust parameter. This parameter is intended to be used when the HSM is already in operational mode. It can be used on a periodic basis to gradually reconcile any discrepancies between the host’s and the HSM’s clocks. Gradual reconciliation prevents sudden time discrepancies and ensures smooth operation.

The HSM’s date and time are used to validate security certificate expiry dates and to provide accurate timestamps for system and audit logs. Thus ensuring that an HSM’s system clock is closely synchronized with an external time source is critical for maintaining robust security and audit capabilities.

The external time source used is the clock of the host PC in which the HSM is installed.

Make sure that the date and time on the host machine are set correctly according to the documentation for the operating system on the host machine.

The system clock should have been set as part of the installation process, see Setting the system clock but the clocks on the HSM and the host PC can drift apart over time due to hardware and environmental differences and must be periodically adjusted to keep them in synchronization.

The system clock may also be incorrect if the HSM has been running on battery power for some time.

System interaction with the system clock

It is important that the system clock is accurate so that timestamps in the system logs can be correlated across the whole network in which the HSM is operating.

For HSMs running firmware version 13.5 or later, if the system clock is lost, for instance due to the HSM running on battery power for an extended period of time, the following administrator actions will be prohibited until the system clock is restored:

If you cannot communicate with the HSM because the system clock is lost, you must be in Recovery mode to reset the system time. See Setting the system clock for more information on setting the system clock.

Checking the system clock

The system clock can be checked using the command gettime.

If the system clock is incorrect it can be set by using the command settime.

For small errors in the system clock it is recommended to adjust the clock as described in Adjusting the system clock. For larger errors in the system clock it may be necessary to use the procedures described in Setting the system clock since use of the --adjust option would result in the clock being incorrect for the long period of time required to converge the clocks.

Following the procedures in Setting the system clock will require the HSM to be taken out of operational mode.

Adjusting the system clock

The system clock is adjusted by using the settime command with the --adjust command line option. This will gradually reduce any difference in time between the host and the HSM’s clocks, preventing large jumps or discontinuities in time.

Use of the --adjust parameter allows the system time to be adjusted whilst the HSM is in operational mode.

The procedure gradually converges the clocks at the rate of a few seconds per day and thus it may take a long time to correct a large error.

When you execute hsmadmin settime adjust, the command immediately returns HSM system time calibration in progress to acknowledge that the calibration process has started. There is no notification when the calibration is complete.

The frequency at which the hsmadmin settime --adjust command should be used depends on multiple factors, for example the precision of the internal clock of the HSM host PC and the extent of drift between the host’s clock and the HSM’s clock.

The recommended starting point for most systems would be to issue the command once per day. Experimentation is required to find the optimal frequency.

Restrictions on setting the clock

To prevent malicious actors from tampering with the HSM’s system clock by moving it backward, the HSM is designed to prevent the setting of a time and date that is earlier than a previously set time and date. This ensures that the HSM’s system clock remains secure and accurate and helps prevent unauthorized access that could occur if the system clock were tampered with.

When the settime command is issued without the --adjust parameter, the new time is saved within the HSM. Subsequent settime commands are prohibited from setting a time earlier than this saved time.

It is only possible to set the HSM system clock to an earlier time than the saved time by returning the HSM to factory state first, see Return to Factory State. This will erase the saved time within the HSM and allow you to issue the settime command without restriction.

As a security measure it is never possible to set the HSM clock to a time earlier than its manufacturing time. The manufacturing time can be obtained with the command hsmadmin info and is shown as the mfgtime entry.
Setting the system date and time automatically resets the HSM.