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 (for example, 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 (for example, 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).

NCCNG_USER_NAMESPACING

Namespacing allows multiple users to generate user keys of the same name. Namespacing is enabled by default.

  • If set to 1, namespacing will be used for new keys that are generated. The key blobs are prefixed with the creating user’s SID.

  • If set to 0, the NCCNG_PROTECTION_TOKEN environment variable controls the protection option used. The key blobs are prefixed with "user".

NCCNG_MACHINE_ACCESS_CONTROL

Configures the default permissions for the key blob files when machine keys are generated if no security descriptor is provided by the application. By default, the machine key access control is configured as STANDARD.

  • If set to STANDARD, then generated keys have read and write permissions for the built-in Administrators group only.

  • If set to CLASSIC, then generated keys use the NFAST_KMLOCAL default permissions.

  • If set to a valid SID starting with S-1-, then generated keys have read and write permissions for the built-in Administrators group and read permissions for the user or group specified by the SID.

  • If set to a valid SDDL, either SACL or DACL, then generated keys will have the file permissions of the SDDL applied to the key blob by default.

NCCNG_USER_ACCESS_CONTROL

Configures the default permissions for the key blob files when user keys are generated if no security descriptor is provided by the application. By default, the user key access control is configured as STANDARD.

  • If set to STANDARD, then generated keys have read and write permissions for the creating user only.

  • If set to CLASSIC, then generated keys use the NFAST_KMLOCAL default permissions.

  • If set to a valid SID starting with S-1-, then generated keys have read and write permissions for the creating user and read permissions for the user or group specified by the SID.

  • If set to a valid SDDL, either SACL or DACL, then generated keys will have the file permissions of the SDDL applied to the key blob by default.

NCCNG_IGNORE_SECURITY_DESCRIPTOR

By default, this is used if an application, for example certreq.exe, provides a security descriptor over the CNG API when keys are generated. This option allows CNG to ignore the provided security descriptor and use the default instead.

  • If set to 1, any supplied security descriptor will be discarded when a new key is generated and the default access control will be applied to the new key.

  • If set to 0, when a new key is generated the supplied security descriptor will be applied to the new key (default).