Real-Time Clock

The HSMAdmin API allows applications to access and adjust the real-time clock (RTC). Information about the RTC status, and how many times it has been adjusted, is also available.

The ctconf utility allows an administrator to configure adjustment access control for the RTC. The administrator can control the delta amount and the number of times the RTC can be adjusted within a configurable period of time. ctconf has two applicable command line options: one that sets the rule for adjustment access control and one that enables/disables adjustment access control. See ctconf for details regarding the use of these command line options.

Setting the Rule for RTC Adjustment Access Control

The RTC Adjustment Access Control Rule specifies the guard parameters which control modification of the RTC. If modification of the RTC is attempted outside of these guard parameters, it will fail.

The table below describes the guard parameters:

Parameter	Meaning
secs	Total amount of deviation (in seconds) within a guard duration. Range: 1-120
count	Total number of adjustments that can be made within the guard duration. Range: any integer. Setting this variable to 0 allows an unlimited number of adjustments
days	The guard duration in days. Range: 1-12

To set guard parameters:

If applications accessing the RTC do not need to alter the RTC by more than 12 seconds, but can make as many adjustments as needed within a period of 1 day, the following command would set the rule for RTC Adjustment Access Control.

ctconf --rtc-adj-access-control-rule=12:0:1

If the guard duration is extended to 4 days, the following command would ensure the other access control rule parameters are not modified:

ctconf --rtc-adj-access-control-rule=::4

The current settings for the access control rule are displayed via the ctconf -v command.

Enabling/Disabling RTC Adjustment Access Control

Once the RTC Adjustment Access Control Rule has been set, RTC Adjustment Access Control can be enabled. When RTC Adjustment Access Control is enabled, the functions provided by the HSMAdmin API (refer to the ProtectToolkit-C Programmers Guide) are governed by the RTC Adjustment Access Control Rule. By disabling RTC Adjustment Access Control, unlimited adjustments to the RTC may be performed.

To enable RTC access control

ctconf --rtc-adj-access-control=1

When access control is disabled, the parameters passed via the HSMADM_GetRtcAdjustAmount and HSMADM_GetRtcAdjustCount function calls are not valid. ctconf may be specified with both the --rtc-adj-access-control-rule and --rtc-adj-access-control command line parameters simultaneously. The RTC Adjustment Access Control Rule is given precedence over the RTC Access Control command.