Environment Variables for CNG Protection

A set of environment variables are supported for controlling CNG protection options on a per-application basis. These variables are documented here to facilitate more complicated deployments, but it should be noted that they are liable to change between releases.

Environment Variable Description

NCCNG_PIN

Passphrase for Softcard. This enables the passphrase to be specified programmatically rather than through the GUI passphrase prompt. Note: This can expose your passphrase.

It is recommended that this be set in a context where the passphrase will be visible only to the user or service that should have access to this passphrase. It should not be set as a machine-wide environment variable.

NCCNG_USE_MODULE_KEYS

  • If set to 1, module protection will be used for new keys that are generated.

  • If set to 0, the NCCNG_PROTECTION_TOKEN environment variable controls the protection option used.

NCCNG_PROTECTION_TOKEN

If NCCNG_USE_MODULE_KEYS is set to 0 (or a protection option other than module key protection or HSM pool mode was selected in the wizard) this environment variable enables the protection token to be specified for new keys that are generated.

  • If set to softcard:HASH the Softcard with the specified hash will be used.

  • If set to cardset:HASH the OCS with the specified hash will be used.

  • If set to anything else (e.g. wizard), the GUI key protection wizard will be used. The HASH for Softcard or OCS protections refers to its Security World hash in hexadecimal, which can be identified using nfkminfo -s for softcards or nfkminfo -c for OCS.

NCCNG_ALWAYS_USE_AGENT

By default, if a CNG provider must display GUI, it will display it in the calling application if not in Session 0, and in the nShield Service Agent if running in Session 0 (e.g. running as a service).

Setting NCCNG_ALWAYS_USE_AGENT to 1 forces CNG GUI prompts to always be displayed in the nShield Service Agent regardless of whether it is running in Session 0.

(If setting this value to 1 ensure that the nShield Service Agent is running).