ctconf

ctconf is configuration utility for the ProtectToolkit-C environment, which is used to configure the operating parameters for ProtectToolkit-C.

By default, ctconf will report configurable settings for the first device found. Some options are only applicable to either the hardware or software implementation of ProtectToolkit-C.

Syntax

The following ctconf syntax can can be used.

ctconf [-a<device>] [-b<name>] [-c<slots>] [-d<slot>] [-e] [-f<flags>] [--factory-reset][-g<file>] [-h] [-j<file>] [-k<file>] [-l] [-m<mode>] [-n<slot>] [-p] [--PST-control=start] [-q] [-r<slot>] [-s] [-t] [-v] [-x] [--rtc-adj-access-control-rule=<secs>:<count>:<days>] [--rtc-adj-access-control=<0 | 1>]

Options

The options shown below are available for ctconf.

-a<device>, --device-number=<device>

Use the admin token on the specified device

-b<name>, --fm-cert=<name>

Specifies the certificate used to validate an FM specified with -k<FM_file>.

-c<slots>, --create-slots=<slots>

Create slots new User slots

-d<slot>, --delete-slot=<slot>

Delete and remove User slot with ID slot (You cannot delete the admin slot).

-e, --event-log

Prints the event log on stdout

--factory-reset

Reset the HSM to factory settings. Resetting the HSM to factory settings does the following:

• Erases all cryptographic material on the HSM.

• Erases all ProtectServer Identity Certificates (PICs), ProtectServer Identity Keys (PIKs), ProtectServer Owner Certificates (POCs), and Protectserver Owner Keys (POKs) on the HSM.

• Erases all functionality modules (FMs) installed on the HSM.

Note

This option is only available if you are using ProtectToolkit 7.3.0 or newer with ProtectServer 3 HSM Firmware 7.03.00 or newer.

-f<flags>

Configures security flags.

Security flags are used to implement security policies. Multiple flags can be set simultaneously. For example the command: ctconf -ftu would set both the t and the u flags. When flags are set, any flags set previously are cleared. Setting ctconf -f0 clears all the flags and places the device in SafeNet Default Mode (no flags set). For more information about this mode, refer to Default Mode.

Use other flags values to set flags as follows:

Flag	Flag Value
Auth Protection	u
DES Keys Even Parity Allowed	d
Enable PCI Audit Logs	b
Entrust Ready	e
FIPS Algorithms Only	a
FIPS Mode	F
Full Secure Messaging Encryption	N
Full Secure Messaging Signing	U
Increased Security Level	i
Mode Locked	l
No Clear PINs	n
No Public Crypto	c
Pure PKCS11 (PKCS#11 Compatibility Mode)	p
Tamper Before Upgrade	t
User Specified ECC DomainParameters Allowed	E
Weak PKCS#11 Mechanisms	w

Each of these flags is fully described in Security flag descriptions.

-g<file>, --upgrade-fw=<file>

Upgrade firmware with file

-h, --help

Display usage information

-j<file>, --download-fm=<file>

Download FM module file

-k<FM_file>, --validate-fm=<file>

Validate FM module file. You must also specify the certificate used to validate the FM (-b<name>).

-l<fmID>, --delete-fm, --disable-fm, --fmid=<fmid>

Disable/delete an FM module, specifying the FM ID in hex format.

-m<n>, --mode=<n>

Set the transport mode for the HSM. The following transport modes can be set with <n>:

Caution

Transport Mode only disables the tamper response mechanism when removing the ProtectServer 3 PCIe adapter from the PCIe bus. Attempting any other hardware tamper procedure described in Hardware tamper procedures or physically attacking the ProtectServer 3 HSM will still result in a tamper response when a Transport Mode is enabled.

Mode number	Mode name	Mode description
0	No Transport Mode (Default)	Default mode that is applied when the HSM is installed and configured. This mode will tamper the HSM if it is removed from the PCI bus or any other hardware tamper procedure described in Hardware tamper procedures is attempted.
1	Single Transport Mode	HSM will not be tampered by removal from the PCI bus and will automatically revert to No Transport Mode the next time the HSM is reset or power is removed and restored.
2	Continuous Transport Mode	HSM will not be tampered by removal from the PCI bus.

See Using Transport Mode to avoid a board removal tamper.

-n<slot>, --init-token=<slot>

Initialize the token in the specified slot

--PST-control=start

Trigger a periodic self-test (PST) instead of waiting 23 hours from completion of the last PST.

Note

This option is only available if you are using ProtectServer 3 HSM Firmware 7.03.00 or newer.

-p, --purge-log

Purge event log. Note that a purge cannot be done until the event log is full.

-q, --query

Query peripheral devices. Check all available serial ports, and attempt to activate drivers for the connected devices.

-r<slot>, --reset-token=<slot>

Reset existing token in specified slot.

-s, --fm-info

Display FM module information.

-t, --time-set

Synchronizes the HSM's internal clock with the host system. This command is only valid when the RTC Status is either HSMADM_RTC_UNINITIALIZED or HSMADM_RTC_STAND_ALONE. For more information about RTC status values, see HSMADM_SetRtcStatus.

-v, --verbose

Display extended status information

Note

When operating multiple ProtectServer 3 HSMs, this option displays extended status information for the first device found and the open session count across all devices.

-x, --tamper

This will cause the Key Store memory on the HSM to be erased (as if tampered) and made ready for re-initialization.

Note

This option is only available on hardware-based ProtectToolkit-C implementations.

--rtc-adj-access-control-rule=<secs>:<count>:<days>

This option sets the rule for RTC Adjustment Access Control. The RTC Adjustment Access Control Rule specifies the guard parameters that control RTC modification. If modification of the RTC is attempted outside of these guard parameters, it will fail.

Parameter	Description
secstotal	Amount of deviation (in seconds) within a guard duration. Range: 1-120
counttotal	Number of adjustment that can be made within the guard duration. Range: 0-no maximum. 0 denotes that unlimited adjustments can be made.
days	The guard duration in number of days. Range 1-12.

The separator : is a compulsory argument. However, the values for <secs>, <count> and <days> can be NULL. A NULL equates to no modification. For example:

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

Use ctconf -v to display the current settings for the RTC Adjustment Access Control Rule.

--rtc-adj-access-control=0|1

RTC Adjustment Access Control can be enabled once the RTC Adjustment Access Control Rule has been set.

When RTC Adjustment Access Control is enabled, the functions provided by the HSMAdmin API (see HSMAdmin.H library reference) are governed by the RTC Adjustment Access Control Rule. By disabling RTC Adjustment Access Control, unlimited adjustments to the RTC can be performed.

ctconf can 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 RTC Adjustment Access Control. Use ctconf -v to display the current settings for the RTC Adjustment Access Control Rule.