Install the nShield PQC Option Pack

Before installing the nShield PQC Option Pack

Before you install the PQCOP, ensure that:

The HSM is installed and set up.
The Security World software is installed.
You have created a Security World and its required ACS and OCS.

You have added the bin directory containing the Security World binaries to your PATH.
The commands in this guide do not include the path, so they will only work if your PATH variable has been updated.

Linux

export PATH=/opt/nfast/bin:$PATH

Windows

$path = [Environment]::GetEnvironmentVariable('Path','Machine')
$newpath = $path + ';C:\Program Files\nCipher\nfast\bin'
[Environment]::SetEnvironmentVariable("Path", $newpath, 'Machine')

The example commands in the following sections use module 1 (-m 1). If you are using a different module, update the value accordingly.

Install the nShield PQC Option Pack

Obtain the PQCOP release file from Entrust Professional Services.

In this guide, the release file is called pqsdk-1.4.1-win64.zip.
Transfer the file to the PQCOP server.

Unzip the file.

mkdir ~/pqsdk
cd ~/pqsdk
mv ~/Downloads/pqsdk-1.4.1-win64.zip .
unzip pqsdk-1.4.1-win64.zip

CodeSafe Setup

The PQCOP functions as a CodeSafe machine running on the HSM. CodeSafe setup differs between nShield Connect XC and nShield 5c HSMs. Ensure you have the correct license and follow the instructions for your HSM.

Before proceeding with the setup, install the relevant CodeSafe license in the HSM if it is not already present:

Check whether the licenses are installed in the HSM using the fet command:

nShield 5c: SEE Activation (CodeSafe 5)
nShield Connect XC: SEE Activation (EU+10)

/opt/nfast/bin/fet -m 1

                         Feature Enable Tool
                         ===================

                      ISO Smart Card Support
                      |  Remote Operator
                      |  |  Korean Algorithms
                      |  |  |  SEE Activation (EU+10)
                      |  |  |  |  SEE Activation (Restricted)
                      |  |  |  |  |  SEE Activation, CodeSafe 5
                      |  |  |  |  |  |  Elliptic Curve algorithms
                      |  |  |  |  |  |  |  Elliptic Curve MQV
                      |  |  |  |  |  |  |  |  Fast RNG for ECDSA
                      |  |  |  |  |  |  |  |  |  HSM Speed Rating
Mod   Electronic      |  |  |  |  |  |  |  |  |  |
No.  Serial Number
1   7852-268D-3BF9 -- Y  Y  Y  N  N  Y  Y  Y  N  High Speed

If the required license is not installed:
1. Request a license file from Entrust Support.
2. Transfer the license file to the following folder on the RFS: /opt/nfast/kmdata/hsm-<ESN>/features, replacing <ESN> with the ESN of your HSM.
3. In the RFS, run the following commands to install the license:
  cd /opt/nfast/kmdata/hsm-<ESN>/features /opt/nfast/bin/nethsmadmin -m 1 -s RFS_IP_ADDRESS -a LICENSE_FILE.txt /opt/nfast/bin/nopclearfail -c -m 1 /opt/nfast/bin/fet -m 1

nShield XC Setup

To set up the PQCOP CodeSafe machine in an nShield XC HSM:

Change directory to where the PQCOP release file was unzipped.
```
cd pqsdk-1.4.1-win64
```
Make sure the ACS card is presented on the front of the HSM.

Use the generatekey utility to create the signing key.
In this example and the remaining steps, the key is named pqsdk-signer

The signing key must have the seeinteg appname and must be protected by an operator card set.

If you need to share LMS keys between nShield Connect XC and nShield 5c devices, the key must be an ECDSA key that uses the NIST 521-bit prime curve.

generatekey seeinteg type=ecdsa curve=nistp521 plainname=pqsdk-signer nvram=no recovery=yes protect=token cardset=testOCS

Example output

slot: Slot to read cards from? (0-5) [0] > 3
key generation parameters:
 operation    Operation to perform       generate
 application  Application                seeinteg
 protect      Protected by               token
 slot         Slot to read cards from    3
 recovery     Key recovery               yes
 verify       Verify security of key     yes
 type         Key type                   ecdsa
 plainname    Key name                   pqsdk-signer
 nvram        Blob in NVRAM (needs ACS)  no
 curve        Elliptic curve             nistp521

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 2: `testOCS' #5
 Module 1 slot 0: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 3:- passphrase supplied - reading card
Card reading complete.

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_seeinteg_pqsdk-signer

Use the same key name to create an NVRAM delegation certificate:

You must have presented the ACS card to do this step.

Linux

/opt/nfast/python3/bin/python3 userdatatool.py -A seeinteg -I pqsdk-signer -f userdata.raw

Windows

c:\> & 'C:\Program Files\nCipher\nfast\python3\python3.exe' C:\Users\Administrator\pqsdk\pqsdk-1.4.1-win64\userdatatool.py -A seeinteg -I pqsdk-signer -f userdata.raw

Example output

Loading ACS KNV for NVMem delegation:
 Module 1 slot 0: Admin Card #1
 Module 1 slot 2: `testOCS' #5
 Module 1 slot 3: `codesign' #1
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Sign the SEE machine.

This example uses the key created earlier to sign both the SEE machine and the user data; however, you can use a different key for each.

tct2 --sign-and-pack -m 1 -k pqsdk-signer --is-machine --machine-type PowerPCELF -o pqsdk-1.4.1.sar pqsdk-1.4.1.elf

Example output

Signing machine as `PowerPCELF'.

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 0: Admin Card #1
 Module 1 slot 2: `testOCS' #5
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 3:- passphrase supplied - reading card
Card reading complete.

Sign the user data file:

tct2 --sign-and-pack -m 1 -k pqsdk-signer --machine-key-ident pqsdk-signer -o userdata.sar userdata.raw

Example output

Loading `codesign':
 Module 1: 0 cards of 1 read
 Module 1 slot 3: `codesign' #1
 Module 1 slot 0: Admin Card #1
 Module 1 slot 2: `testOCS' #5
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 3:- passphrase supplied - reading card
Card reading complete.

Create the /opt/nfast/kmdata/custom-seemachines directory and copy the pqsdk-1.4.1.sar and the userdata.sar files to it:

Linux

sudo mkdir -p /opt/nfast/kmdata/custom-seemachines
sudo cp pqsdk-1.4.1.sar /opt/nfast/kmdata/custom-seemachines/.
sudo cp userdata.sar /opt/nfast/kmdata/custom-seemachines/.

Windows

mkdir 'C:\ProgramData\nCipher\Key Managemeent Data\custom-seemachines'
cp pqsdk-1.4.1.sar 'C:\ProgramData\nCipher\Key Managemeent Data\custom-seemachines\.'
cp userdata.sar 'C:\ProgramData\nCipher\Key Managemeent Data\custom-seemachines\.'

Configure one or more nShield XC devices to run the SEE machine.

You can also do this by using the front panel and the configuration file. For more information, see Configure the HSM using the front panel and the configuration file.

This will prompt you to reset the nShield HSM. Doing so should start the SEE machine and restart it whenever the HSM is restarted.

Linux

loadsee-setup --setup \
     -m 1 -M /opt/nfast/kmdata/custom-seemachines/pqsdk-1.4.1.sar \
     -U /opt/nfast/kmdata/custom-seemachines/userdata.sar -p pqsdk

Windows

loadsee-setup --setup -m 1
  -M 'C:\ProgramData\nCipher\Key Managemeent Data\custom-seemachines\pqsdk-1.4.1.sar'
  -U 'C:\ProgramData\nCipher\Key Managemeent Data\custom-seemachines\userdata.sar'
  -p pqsdk

Example output

Module #1 new SEE configuration saved, new configuration follows:

Module #1:
  Machine file:             /opt/nfast/kmdata/custom-seemachines/pqsdk-1.4.1.sar
  Encryption key:
  Signing key hash:
  Userdata file:            /opt/nfast/kmdata/custom-seemachines/userdata.sar
  WorldID published object: pqsdk
  Postload helper:
  Postload args:

Reload new configuration now? (yes/no): yes
Clear modules before reloading new configuration? (yes/no): yes
Modules cleared for new configuration.
Check the hardserver log to ensure the SEE machine was loaded correctly after clearing.

Check that the SEE machine has been loaded:
```
hsc_loadseemachine -m1
```

Configure the HSM using the front panel and the configuration file

In the RFS, create a copy of the /opt/nfast/kmdata/hsm-<ESN>/config/config file, where <ESN> is the ESN of the nShield Connect.

In this example, the new copy of the file is named config_new and is in the current directory. The file can have any name, as long as it is used consistently.

Edit the [load_seemachine] section in the new copy to resemble the following example:

module=1
machine_file=pqsdk-1.4.1.sar
encryption_key=
signing_hash=
userdata=userdata.sar
worldid_pubname=pqsdk
postload_prog=
postload_args=
pull_rfs=yes

Use cfg-pushnethsm to push the new configuration, where <HSM_IP_ADDRESS> is the IP address of the HSM being used.
```
cfg-pushnethsm -a <HSM_IP_ADDRESS> config_new
```
Check that the SEE machine has been loaded:
```
hsc_loadseemachine -m1
```

[[5c_setup]] === nShield 5c Setup

Before you set up a PQCOP CodeSafe machine in an nShield 5c HSM, install the CodeSafe 5 software if it is not already installed.

Install CodeSafe 5 (Linux)

For more information on installing CodeSafe 5, refer to Install the CodeSafe 5 SDK on Linux.

Download the CodeSafe 5 ISO image. This example uses Codesafe_Lin64-13.9.3.iso.
Transfer the ISO image to the PQCOP server.
Make a mountpoint directory:
```
mkdir -p ~/codesafe_iso_mountpoint
```

Mount the ISO image:

sudo mount ~/Downloads/Codesafe_Lin64-13.9.3.iso ~/codesafe_iso_mountpoint/

Extract the tar archives into the root directory:

sudo tar -zxvf ~/codesafe_iso_mountpoint/linux/amd64/csd.tar.gz -C /
sudo tar -zxvf ~/codesafe_iso_mountpoint/linux/amd64/csdref.tar.gz -C /

Unmount the mount directory:
```
sudo umount ~/codesafe_iso_mountpoint
```

Install CodeSafe 5 (Windows)

For more information on installing CodeSafe 5, refer to [security-world-docs:codesafe5:install-codesafe-windows].

Download the CodeSafe 5 ISO image. This example uses Codesafe_Windows-13.9.3.iso.
Transfer the ISO image to the PQCOP server.
Mount the ISO image and navigate into the mounted directory.
Launch setup.msi.
Follow the on-screen instructions.
Accept the license terms and select Next to continue.
Specify the installation directory and select Next to continue.
Select Install.
Select Finish to complete the installation.

This installs the nShield CodeSafe 5 SDK under C:\Program Files\nCipher\nfast\c\csd5 and the nShield CodeSafe 5 SDK Python files under C:\Program Files\nCipher\nfast\python3\csd5.

Set up the PQCOP CodeSafe machine

Running a CodeSafe 5 container requires an application signing key (ASK), a developer key, and a developer certificate. You must generate the key pair first, and then send a signing request to Entrust Support. After Entrust Support accepts the signing request, it will send you a certificate.

Change directory to where the PQCOP release file was unzipped:
```
cd pqsdk-1.4.1-win64
```

Create a developer key and certificate signing request (CSR).

When you create the CSR, you must present an OCS card to protect the key.

csadmin ids create --keyname devkeyident -m 1 --x509cname COMMON_NAME --x509org ORGANIZATION_NAME

Example output

Generate key 'devkeyident' ...

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 2: `testOCS' #4
 Module 1 slot 0: empty
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 2:- passphrase supplied - reading card
Card reading complete.

OK
Generate a CSR in 'devkeyident.csr' ...

Loading `testOCS':
 Module 1 slot 2: `testOCS' #4
 Module 1 slot 0: empty
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 2:- passphrase supplied - reading card
Card reading complete.

OK
Created CSR file 'devkeyident.csr'. Please send it to Entrust Support

This creates a CSR named devkeyident.csr.

Send the CSR file to Entrust Support.
When Entrust Support sends you the X.509 developer certificate, save it as devkeyident.pem.

Get the CodeSafe 5 client keytype and publickey:

hsmadmin cs5 clientinfo

ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBBpxuj1sCIjvq5dCoprxVCUFTfTVImwO/7WW95njfZOmnw8/aAuW6nQuq4IiBiXeqkAkGbmY2SB5NU3QeUxeyxM=

Set up the CodeSafe 5 client with the details from the previous command:

appliance-cli -m 1 cs5 setclientinfo <keytype> <publickey>

In the previous step, the keytype is ecdsa-sha2-nistp256 and the publickey is the string starting with AAAAE2VjZH:

appliance-cli -m 1 cs5 setclientinfo \
  ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBBpxuj1sCIjvq5dCoprxVCUFTfTVImwO/7WW95njfZOmnw8/aAuW6nQuq4IiBiXeqkAkGbmY2SB5NU3QeUxeyxM=

Client info set

Enable the services on the 5c using the IPv4 address of the HSM:
```
appliance-cli -m 1 cs5 ports enable <IPv4>
```

Get the connection information for the launcher service from the nShield 5c:

appliance-cli -m 1 cs5 getserverinfo

For example:

appliance-cli -m 1 cs5 getserverinfo

CodeSafe 5 server info in format <ESN> <IP Address> <Port> <Key Type> <Public Key>
7852-268D-3BF9 XXX.XXX.XXX.XXX 2205 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCwlIbn33m9WceI2uuQif5ZU/LvLZ1NqZa8W0JtOlNPZOWx5q3vdUxoU9T+l4Ny74qDoB/9eqIYa5h6JU5vA2JU=

Enroll as a client of the CS5 launcher services on this HSM by using the information returned in the previous step:

hsmadmin cs5 enroll <ESN> <IP Address> <Port> <Key Type> <Public Key>

For example:

hsmadmin cs5 enroll 7852-268D-3BF9 XXX.XXX.XXX.XXX 2205 \
       ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCwlIbn33m9WceI2uuQif5ZU/LvLZ1NqZa8W0JtOlNPZOWx5q3vdUxoU9T+l4Ny74qDoB/9eqIYa5h6JU5vA2JU=

Run csadmin list to confirm the RFS connection to this nShield 5c.

The output displays the ESN and informs you that there are no SEE machines:
```
csadmin list

7852-268D-3BF9        No SEE machines currently installed
```
Transfer the devkeyident.pem developer certificate to your PQCOP server.
Register this developer certificate as the first trusted code-signing certificate for the SEE machine on this HSM:
```
csadmin ids --esn <ESN> add devkeyident.pem
```

Check that the new certificate is present:

csadmin ids list --json

Example output

{
    "7852-268D-3BF9": {
        "succeeded": true,
        "data": {
            "Certificates": [
                {
                    "subject": "Common Name: CodeSafe Production, Organizational Unit: nCipher, Organization: Entrust, Country: GB",
                    "keyid": "c9c01efbe14ff33cb9afec71d66639c6e038a378",
                    "serialNumber": "143541911711567699079218604000066011212901051119",
                    "authKeyid": "e193ba2ea9acf291ac3c072261db107d2ef08706",
                    "notBefore": "2023-03-14 09:36:09+00:00",
                    "notAfter": "2033-03-24 09:36:09+00:00"
                },
                {
                    "subject": "Common Name: entrust.com, Organization: ENTRUST, Organizational Unit: PQ SDK Test",
                    "keyid": "400d62ecb83cfd1b6a1a1b844a653e8614c3c737",
                    "serialNumber": "226364443189258673605810532466534336860",
                    "authKeyid": "c9c01efbe14ff33cb9afec71d66639c6e038a378",
                    "notBefore": "2026-02-13 17:18:39+00:00",
                    "notAfter": "2029-02-13 17:18:38+00:00"
                },
                {
                    "subject": "Common Name: interops.local, Organization: Hurricanes, Organizational Unit: PQ SDK Test",
                    "keyid": "a1d2a0415f313f50a1485bec75c45f20619812e4",
                    "serialNumber": "238627680622732813176583323266486551324",
                    "authKeyid": "c9c01efbe14ff33cb9afec71d66639c6e038a378",
                    "notBefore": "2026-02-19 16:04:34+00:00",
                    "notAfter": "2029-02-19 16:04:33+00:00"
                }
            ]
        }
    }
}

Use the generatekey utility to create the application signing key (ASK).

The ASK must have the simple appname and must be an ECDSA key that uses the NIST 521-bit prime curve.

Remember the slot number because this is the slot where you need to present the OCS card that will be used to protect the key.
```
generatekey simple type=ecdsa curve=nistp521 ident=pqsdk-signer plainname=pqsdk-signer
    nvram=no recovery=yes protect=token cardset=testOCS slot=2
    trusted-certifier= seeintegname=
```

Use the same key name to create an NVRAM delegation certificate.

Make sure the ACS card is presented on the front slot of the HSM.

Linux

/opt/nfast/python3/bin/python3 userdatatool.py -A simple -I pqsdk-signer -f userdata.raw

Windows

c:\> & 'C:\Program Files\nCipher\nfast\python3\python3.exe' userdatatool.py -A simple -I pqsdk-signer -f userdata.raw

Example output

Loading ACS KNV for NVMem delegation:
 Module 1 slot 0: Admin Card #1
 Module 1 slot 2: `testOCS' #6
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Create the container CodeSafe 5 machine directory structure.

Create a directory that reflects the intended file structure of the container. Include the pqsdk.bin file as the entry point.

Note the release number in the pqsdk.bin filename.
```
mkdir -p container/usr/bin
mkdir -p container/etc
cp pqsdk-1.4.1.bin container/usr/bin/entrypoint
cp userdata.raw container/etc/userdata.codesafe
```

Create an unsigned container image using the csadmin tool:

csadmin image generate
  --package-name "pqsdk-1.4.1"
  --version-str "1.4.1"
  --entry-point /usr/bin/entrypoint
  --network-conf network.json
  --packages-conf packages.json
  --rootdir container pqsdk.cs5

Example output

Copying  /opt/nfast/python3/csd5/ppc64/usr/bin to /home/user/pqsdk/pqsdk-1.4.1-win64/rfs_build_YlydVwJozb/usr/bin
Copying  /opt/nfast/python3/csd5/ppc64/usr/lib/python3.11 to /home/user/pqsdk/pqsdk-1.4.1-win64/rfs_build_YlydVwJozb/usr/lib/python3.11
Copying  /opt/nfast/c/csd5/rootfs to /home/user/pqsdk/pqsdk-1.4.1-win64/rfs_build_YlydVwJozb/

The network.json and package.json files provided with PQCOP contain example configurations that can be used to create a container with reasonable settings.

Sign the container image.

This example uses the devkeyident.pem created earlier. Ensure that this file is inside the pqsdk-1.4.1-win64 folder.

csadmin image sign
  --devkeyname devkeyident --devcert devkeyident.pem
  --askeyname pqsdk-signer --out pqsdk-signed.cs5 pqsdk.cs5

Example output

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 2: `testOCS' #6
 Module 1 slot 0: Admin Card #1
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 2:- passphrase supplied - reading card
Card reading complete.

Loading `testOCS':
 Module 1: 0 cards of 1 read
 Module 1 slot 2: `testOCS' #6
 Module 1 slot 0: Admin Card #1
 Module 1 slot 3: empty
 Module 1 slot 4: empty
 Module 1 slot 5: empty
 Module 1 slot 2:- passphrase supplied - reading card
Card reading complete.

Load the container image into each nShield 5c where it will be used:
```
csadmin load --esn 7852-268D-3BF9 pqsdk-signed.cs5

7852-268D-3BF9        UUID: 3d362d35-fc17-448a-b501-914fe0a680b0
```
Record the UUID. You will need this in the next step.

Start the container to make the code run inside the nShield HSM:

csadmin start --esn 7852-268D-3BF9 --uuid 3d362d35-fc17-448a-b501-914fe0a680b0

7852-268D-3BF9        SUCCESS; IP ADDRESS: XXX.XXX.XXX.XXX

Publish the container so that services and command line tools can find it.

Linux

% /opt/nfast/python3/bin/python3 ./bootstrap.py -m 1 --uuid 3d362d35-fc17-448a-b501-914fe0a680b0 --cs5file pqsdk-signed.cs5

Windows

> c:\> & 'C:\Program Files\nCipher\nfast\python3\python3.exe' ./bootstrap.py -m 1
      --uuid dd8756e4-0bdf-4b25-a640-9e6f6f700fa4
      --cs5file pqsdk-signed.cs5

Containers can be stopped with the stop subcommand and erased when no longer needed using the destroy subcommand.

Published objects become invalid and should no longer appear in pipsqueak when the container is stopped. However, they might cause an error message. You can publish them again later if required.