Using nShield commands from PowerShell

PowerShell is a powerful console tool for scripting operations on Windows. nShield applications can be run from PowerShell, locally or remotely, interactively or non-interactively (batch mode). nShield library code implements a set of commands for reading text and passphrases.

Install and configure PowerShell

  1. Install PowerShell, see https://docs.microsoft.com/en-us/powershell/.

  2. Ensure that executing PowerShell scripts is enabled in the system.

    Script execution is not enabled by default on Windows clients. The default permissions usually allow script execution on Windows Server operating systems, but it may be necessary to enable this in a custom Windows Server configuration.

    Open PowerShell and set the signing property and scope of script execution.

    The support files for running nShield commands from PowerShell are Authenticode-signed, so the execution can be restricted to only signed scripts:

    Set-ExecutionPolicy -ExecutionPolicy AllSigned

    If unsigned PowerShell scripts are to be executed, you may want to relax this so that locally created scripts can be run without signing:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

    The above commands can be run with the additional parameter -Scope CurrentUser to restrict the changes to the currently logged-in user. For example to permit the current user to run locally-created scripts, run:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  3. By default, PowerShell commands are created for all executables in $env:NFAST_HOME\bin. If there are additional directories containing nShield executables that you wish to include in the nShield PowerShell module support, you can specify those directories with a semicolon separated list of paths in the NC_PS_ADDITIONAL_DIRECTORIES environment variable.

    $env:NC_PS_ADDITIONAL_DIRECTORIES="C:\Path1;C:\Path2"

  4. To load support for nShield commands in PowerShell, import the nShieldTools.psd1 module located in $env:NFAST_HOME\bin.

    Import-Module 'C:\Program Files\nCipher\nfast\bin\nShieldTools.psd1'

    The support module is installed in the active shell.

  5. To load the nShieldTools.psd1 module automatically every time PowerShell is opened, you can add it to your PowerShell profile with the Add-nShieldToProfile command, included in the nShieldTools.psd1 module.

    Parameter Description

    AllHosts

    (Recommended) Profile is available for all PowerShell hosts, for example both ConsoleHost and ISE, rather just the currently running host.

    AllUsers

    Profile is available for all users on the local machine rather than just the current user.

    Example:

    Add-nShieldToProfile -AllHosts

Calling nShield commands at the PowerShell prompt

nShield commands can be called with their usual names from PowerShell, for example enquiry, cardpp, generatekey, or new-world. Aliases for the .exe variants, for example new-world.exe, are also registered so that the nShield executables in the PATH are only called with PowerShell support.

Do not call the executables directly (for example, do not call & 'C:\Program Files\nCipher\nfast\bin\new-world.exe') because this will not enable the PowerShell support.

Command-line parameters to nShield PowerShell commands can be provided in the same way as the corresponding command under regular Windows consoles. If you can run cardpp --check in a regular Windows console, you can run cardpp --check in PowerShell.

The global variable $LASTEXITCODE of PowerShell contains the exit code (0 for success) immediately after execution of the nShield command.

PowerShell modes: interactive and batch

nShield commands can be run in either interactive or batch (non-interactive) mode.

In the default interactive mode, the output is displayed incrementally on the screen in the PowerShell host user interface. UI prompts are displayed when the command attempts to read user input, for example passphrases or confirmations. Output is not written to a PowerShell pipeline in this mode.

Batch mode is intended for automation. Commands can be run from a script and an output can be redirected to a file. Batch mode does not prompt for input in the host UI. Input can be supplied programmatically with a PowerShell input pipeline. If input is needed but no suitable pipeline was supplied, the command fails rather than stall program execution to wait for user interaction. Standard output and standard error text printed by the underlying nShield program is written to output and error pipelines that can be redirected or piped. If the program fails, that is, it returns a non-zero exit code, the error code is also thrown as an exception that appears in the error pipeline. In batch mode, output and error texts are visible only at the very end of execution, because such texts are objects that the command returns to the pipeline instead of writing them incrementally to the host UI.

If the mode is not explicitly set, PowerShell normally defaults to interactive mode. However, if any input pipeline objects are supplied, PowerShell defaults to batch mode. You can therefore switch to batch mode without setting it explicitly simply by piping $null:

$null | enquiry > enquiry.txt

You can change the default mode to batch mode by setting the NC_PS_INTERACTIVE environment variable:

$env:NC_PS_INTERACTIVE=0

Mode change commands provided in the nShieldTools.psd1 module:

Command Notes

Set-nShieldBatchMode

Set-nShieldInteractiveMode

Reset-nShieldCommandMode

Can be used to restore the default PowerShell behavior based on presence or absence of pipeline input.

To restrict a setting to a particular PowerShell scope, you can use the PowerShell variable $nShieldInteractiveCommandMode, which can be set to $True or $False.

Input pipelines

In both interactive and batch mode, nShield commands support input pipelines with the PowerShell pipe ("|") syntax. The input pipeline can be used to automate the execution of nShield commands that would otherwise have to prompt for user input. For example, a passphrase check on an OCS card can be performed automatically by executing the following command:

Set-nShieldBatchMode
$passphrase | cardpp --check

$passphrase is a variable in the command or script, and contains the card’s passphrase.

Multiple values can be supplied to provide the input to successive prompts. For example, the generatekey command can be automated to provide passphrases for operator cards, softcards, or administrator cards. In the following example, the passphrase variables are passed to the input pipeline, and the remaining key generation parameters are passed on the command-line:

PS C:\temp\test> $acs_passphrase, $softcard_passphrase | generatekey --batch pkcs11 protect=softcard softcard=mysoftcard plainname=mykeyname nvram=yes
key generation parameters:
operation    Operation to perform               generate
application  Application                        pkcs11
module       Module to use                      1
protect      Protected by                       softcard
slot         Slot to read cards from            0
softcard     Soft card to protect key           mysoftcard
recovery     Key recovery                       yes
verify       Verify security of key             yes
type         Key type                           RSA
size         Key size                           2048
pubexp       Public exponent for RSA key (hex)
logkeyusage  Log key usage                      no
plainname    Key name                           mykeyname
nvram        Blob in NVRAM (needs ACS)          yes

Load Admin Card (for KNV):
Module 1 slot 0: Admin Card #1
Module 1 slot 0: Enter passphrase:
Module 1 slot 0:- passphrase supplied - reading card
Module #1 Slot #0: Processing ...
Card reading complete.

Please enter the passphrase for softcard 'mysoftcard':
Please wait........
Key successfully generated.
Path to key: C:\ProgramData\nCipher\Key Management Data\local\key_pkcs11_uce586891...

Secure strings

A passphrase or other sensitive string can be read into a variable in PowerShell using $passphrase = Read-Host -AsSecureString. $passphrase in this case is an instance of System.Security.SecureString and not the System.String type used for normal strings. The contents of a SecureString cannot be read directly. If print the value of $passphrase in PowerShell, you only see the type name displayed and not the value that was entered to the Read-Host -AsSecureString prompt.

nShield commands support using SecureString instances both for the input pipeline and as parameters to the nShield command. This helps reduce the visibility of plaintext passphrases or other sensitive values in scripts or in the shell. This is useful when using the input pipeline to automate the presentation of passphrases to the prompts in card-loading commands. It also means that nShield commands that take a passphrase as a command-line parameter can be presented that string without the string becoming directly visible.

Example:

PS ppmk --new --newpp $passphrase newsoftcard