System Properties

You can use system properties to control the provider. You set system properties when starting the Java Virtual Machine using a command such as:

java -D<property>=<value> <MyJavaApplication>

In this example command, <property> represents any system property, <value> represents the value set for that property, and <MyJavaApplication> is the name of the Java application you are starting. You can set multiple system properties in a single command, for example:

java -Dprotect=module -DignorePassphrase=true MyJavaApplication

The available system properties and their functions as controlled by setting different values for a property are described in the following table:

Property Function for different values

Property	Function for different values
`JCECSP_DEBUG`	This property is a bit mask for which different values specify different debugging functions; the default value is `0`. For details about the effects of setting different values for this property, see JCECSP_DEBUG property values.
`JCECSP_DEBUGFILE`	This property specifies a path to the file to which logging output is to be written. Set this property if the `JCECSP_DEBUG` property is set to a value other than the default of `0`. For details about the effects of setting different values for this property, see JCECSP_DEBUG property values. In a production environment, we recommend that you disable debug logging to prevent sensitive information being made available to an attacker.
`CKNFAST_JCE_COMPATIBILITY`	This property is included to allow the saving of objects when using Java PKCS#11 providers.
`protect`	This property specifies the type of protection to be used for key generation and nCipherKM KeyStore instances. You can set the value of this property to one of `module`, softcard:`IDENT or `cardset. OCS protection (`cardset`) uses the card from the first slot of the first usable hardware security module. To find the logical token hash IDENT of a softcard, run the command `nfkminfo` `--softcard-list`.
`module`	This property lets you override the default module and select a specific module to use for module and OCS protection. Set the value of this property as the ESN of the module you want to use.
`slot`	This property lets you override the default slot for OCS-protection and select a specific slot to use. Set this the value of this property as the number of the slot you want to use.
`ignorePassphrase`	If the value of this property is set to `true`, the nCipherKM provider ignores the passphrase provided in its KeyStore implementation. This feature is included to allow the Oracle or IBM `keytool` utilities to be used with module-protected keys. The `keytool` utilities require a passphrase be provided; setting this property allows a dummy passphrase to be used.
`seeintegname`	Setting the value of this property to the name of an SEE integrity key causes the provider to generate SEE application keys. These keys may only be used by an SEE application signed with the named key.
`com.ncipher.provider.announcemode`	The default value for this property is `auto`, which uses firmware auto-detection to disable algorithms in the provider that cannot be supported across all installed modules. Setting the value of this property to `on` forces the provider to advertise all mechanisms at start-up. Setting the value of this property to `off` forces the provider to advertise no mechanisms at start-up.
`com.ncipher.provider.enable`	For the value of this property, you supply a comma-separated list of mechanism names that are to be forced on, regardless of the announce mode selected.
`com.ncipher.provider.disable`	For the value of this property, you supply a comma-separated list of mechanism names that are to be forced off, regardless of the announce mode selected. Any mechanism supplied in the value for the `com.ncipher.provider.disable` property overrides the same mechanism if it is supplied in the value for the `com.ncipher.provider.enable` property.

JCECSP_DEBUG

This property is a bit mask for which different values specify different debugging functions; the default value is 0. For details about the effects of setting different values for this property, see JCECSP_DEBUG property values.

JCECSP_DEBUGFILE

This property specifies a path to the file to which logging output is to be written. Set this property if the JCECSP_DEBUG property is set to a value other than the default of 0. For details about the effects of setting different values for this property, see JCECSP_DEBUG property values.

In a production environment, we recommend that you disable debug logging to prevent sensitive information being made available to an attacker.

CKNFAST_JCE_COMPATIBILITY

This property is included to allow the saving of objects when using Java PKCS#11 providers.

protect

This property specifies the type of protection to be used for key generation and nCipherKM KeyStore instances. You can set the value of this property to one of module, softcard:`IDENT or `cardset. OCS protection (cardset) uses the card from the first slot of the first usable hardware security module. To find the logical token hash IDENT of a softcard, run the command nfkminfo --softcard-list.

module

This property lets you override the default module and select a specific module to use for module and OCS protection. Set the value of this property as the ESN of the module you want to use.

slot

This property lets you override the default slot for OCS-protection and select a specific slot to use. Set this the value of this property as the number of the slot you want to use.

ignorePassphrase

If the value of this property is set to true, the nCipherKM provider ignores the passphrase provided in its KeyStore implementation. This feature is included to allow the Oracle or IBM keytool utilities to be used with module-protected keys. The keytool utilities require a passphrase be provided; setting this property allows a dummy passphrase to be used.

seeintegname

Setting the value of this property to the name of an SEE integrity key causes the provider to generate SEE application keys. These keys may only be used by an SEE application signed with the named key.

com.ncipher.provider.announcemode

The default value for this property is auto, which uses firmware auto-detection to disable algorithms in the provider that cannot be supported across all installed modules. Setting the value of this property to on forces the provider to advertise all mechanisms at start-up. Setting the value of this property to off forces the provider to advertise no mechanisms at start-up.

com.ncipher.provider.enable

For the value of this property, you supply a comma-separated list of mechanism names that are to be forced on, regardless of the announce mode selected.

com.ncipher.provider.disable

For the value of this property, you supply a comma-separated list of mechanism names that are to be forced off, regardless of the announce mode selected. Any mechanism supplied in the value for the com.ncipher.provider.disable property overrides the same mechanism if it is supplied in the value for the com.ncipher.provider.enable property.

JCECSP_DEBUG property values

The JCECSP_DEBUG system property is a bit mask for which you can set different values to control the debugging functions. The following table describes the effects of different values that you can set for this property:

JCECSP_DEBUG value Function

`JCECSP_DEBUG` value	Function
`0`	If this property has no bits set, no debugging information is reported. This is the default setting.
`1`	If this property has the bit 1 set, minimal debugging information (for example, version information and critical errors) is reported.
`2`	If this property has the bit 2 set, comprehensive debugging information is reported.
`4`	If this property has the bit 3 set, debugging information relating to creation and destruction of memory and module resources is reported.
`8`	If this property has the bit 4 set, `debugFunc` and `debugFuncEnd` generate debugging information for functions that call them.
`16`	If this property has the bit 5 set, `debugFunc` and `debugFuncEnd` display the values for all the arguments that are passed in to them.
`32`	If this property has the bit 6 set, context information is reported with each debugging message (for example, the `ThreadID` and the current time.
`64`	If this property has the bit 7 set, the time elapsed during each logged function is calculated, and information on the number of times a function is called and by which function it was called is reported.
`128`	If this property has the bit 8 set, debugging information for NFJAVA is reported in the debugging file.
`256`	If this property has the bit 9 set, the call stack is printed for every debug message.

0

If this property has no bits set, no debugging information is reported. This is the default setting.

1

If this property has the bit 1 set, minimal debugging information (for example, version information and critical errors) is reported.

2

If this property has the bit 2 set, comprehensive debugging information is reported.

4

If this property has the bit 3 set, debugging information relating to creation and destruction of memory and module resources is reported.

8

If this property has the bit 4 set, debugFunc and debugFuncEnd generate debugging information for functions that call them.

16

If this property has the bit 5 set, debugFunc and debugFuncEnd display the values for all the arguments that are passed in to them.

32

If this property has the bit 6 set, context information is reported with each debugging message (for example, the ThreadID and the current time.

64

If this property has the bit 7 set, the time elapsed during each logged function is calculated, and information on the number of times a function is called and by which function it was called is reported.

128

If this property has the bit 8 set, debugging information for NFJAVA is reported in the debugging file.

256

If this property has the bit 9 set, the call stack is printed for every debug message.

To set multiple logging functions, add up the JCECSP_DEBUG values for the debugging functions you want to set, and specify the total as the value for JCECSP_DEBUG. For example, if you want to set the debugging to use both function tracing (bit 4) and function tracing with parameters (bit 5), add the JCECSP_DEBUG values shown in the table for these debugging functions (8 + 16 = 24) and specify this total (24) as the value to use for JCECSP_DEBUG.