Content:
- Introduction
- Prerequisites
- Downloading and installing Smart Card Shell 3
- Running Smart Card Shell 3 GUI
- Loading the key manager in Smart Card Shell 3 GUI
- Initializing the token and configuring DKEK to enable the import of keys and X.509 certificates from PKCS#12 files
- Generating ECC key pair (by means of DKEK shares)
- Importing key pair and the corresponding X.509 certificate from PKCS#12 file into the token (by means of DKEK shares)
1. Introduction
The SmardCard-HSM (Standard-A USB) token (you can order it online):
is a reliable, fast, secure, and OpenSC compatible HSM device, for generating, storing, and importing RSA, AES, and Elliptic Curve (EC) keys and X.509 certificates. Maybe, the best feature of the device is its enhanced support for EC (up to 521-bit keys), and the ability to import key pairs and certificates from PKCS#12 containers. Later allows to clone a key pair into several token devices, as a hardware backup scenario.
Unfortunately, the vendor does not provide (yet) a comprehensive documentation for end users, describing in details the specific process of importing key pairs and X.509 certificates from PKCS#12 containers (files) into the token (which is something very much in demand). Therefore, the goal of this document is to fix (at least partially) that gap in the documentation.
Note, that the procedures, described above, are not part of the everyday practice. They are required only for initializing the token device, generating EC keys for curves that are not currently listed as supported in the token's firmware (for instance, secp384r1 curve is supported by the token's processor, but not listed as supported in the firmware and the OpenSC based tools cannot request secp384r1 key generation), and to import key pairs and X.509 certificates from PKCS#12 files.
2. Prerequisites
To be able to follow the steps given below, you need to have installed and updated Linux distribution, running a Graphical Desktop environment (GNOME, KDE). Recent OpenJDK (17 is recommended if available) must be installed and kept updated. Do not install OpenJDK manually, since it is an essential software package! Always use the package manager, provided by the vendor of your Linux distribution to install or update OpenJDK:
-
RHEL7, CentOS 7, Scientific Linux 7:
# yum install java-11-openjdk.x86_64
-
Fedora (current), RHEL8/9, CentOS 8, Scientific Linux 8, Rocky Linux 8/9, Alma Linux 9:
# dnf install java-17-openjdk.x86_64
-
Ubuntu:
# apt-get install openjdk-17-jdk-headless
It is not a good idea to configure the HSM token and manage its content on a system, that is used for social networking, software testing, gaming, or any other activity, that might be considered risky in this case. Always use a dedicated desktop system (or dedicated Linux virtual machine) for managing your PKI infrastructure.
You might have more than one version of OpenJDK installed on your system. So the first step is to check that and set the latest OpenJDK as a default Java provider. Execute the following command line (be super user or root):
# alternatives --config java
to check how many Java packages (provides) are installed and available locally, and which one of them is set as current default. For example, the following result:
There are 2 programs which provide 'java'.
Selection Command
-----------------------------------------------
*+ 1 java-11-openjdk.x86_64 (/usr/lib/jvm/java-11-openjdk-11.0.19.0.7-1.el9_1.x86_64/bin/java)
2 java-17-openjdk.x86_64 (/usr/lib/jvm/java-17-openjdk-17.0.7.0.7-1.el9_1.x86_64/bin/java)
Enter to keep the current selection[+], or type selection number:
means there are two OpenJDK packages installed, and the first one is set a default Java provider (see which is the entry marked with "+" in the first column). To set OpenJDK 17 default Java provider, type the ID number assigned to the package in the list (in the "Selection" column) and press "Enter" afterwards (in the above example, the ID used is 2):
Enter to keep the current selection[+], or type selection number: 2
It is always a good idea to check if the symlinks created by the alternatives tool points to the correct target. The simplest way to do so for OpenJDK 11 is to follow the symlink /etc/alternatives/java:
$ ls -al /etc/alternatives/java
and verify that the target is the OpenJDK 11 java executable:
lrwxrwxrwx. 1 root root 63 Apr 29 13:58 /etc/alternatives/java -> /usr/lib/jvm/java-17-openjdk-17.0.7.0.7-1.el9_1.x86_64/bin/java
Also check if the Java major version of the target:
$ java --version
is 17:
openjdk 17.0.7 2023-04-18 LTS
OpenJDK Runtime Environment (Red_Hat-17.0.7.0.7-1.el9_1) (build 17.0.7+7-LTS)
OpenJDK 64-Bit Server VM (Red_Hat-17.0.7.0.7-1.el9_1) (build 17.0.7+7-LTS, mixed mode, sharing)
Also, have pcscd running.
3. Downloading and installing Smart Card Shell 3
Be sure you have OpenJDK 17 installed, as specified above. Then visit the web page:
https://www.openscdp.org/scsh3/download.html
click on "IzPack Installer" link, and save locally the provided JAR archive of the installer.
Decide what kind of installation of Smart Card Shell 3 do you really need - to allow all users of the system to run the program code (run the installer as super user), or to limit that ability to a certain unprivileged user (perform the installation using that particular user ID):
-
run the installer as super user (root):
You should install the program into a system folder, where the users can only read and execute the Java code (no write access should be given by default). That kind of restrictions will protect the executable code from deletion of modification.
-
run the installer as a non-privileged user:
In this case, the simplest solution is to install the program into the home folder of the user. That type of installation is recommended only for a user, who really understands how to keep the executable code safe.
If followed, the steps given bellow will install the executable code of the program in the home folder of those user, who is executing the installer.
Open a terminal and type:
$ java -jar /path/to/scsh3.XX.YYY.jar
(here XX and YYY are numbers, unique for the current version). The following window will appear (press there the button "Next" to continue):
Select the installation folder (use the button "Browse" to change it, if you do not like the one suggested by the installer), and press "Next":
Now you will be able to see the progress of the installation process (press the button "Next" to continue, when it is done):
Next, you need to decide whether or not to create a shortcut to the program in the GNOME "Applications" menu (it is recommended to create such a shortcut), and who will be able to invoke the installed program (the last is useful only if you install the software as super user or root into a system folder). Press the button "Next":
and in the last window of the installer, press "Done" to exit:
Important note for those who are running Smart Card Shell 3 on RHEL9 (Rocky Linux 9, Alma Linux 9)!
Smart Card Shell 3 needs the library libpcsclite.so, but no package provides libpcsclite.so on RHEL9. To overcome that issue, install the package pcsc-lite-libs (if it is not already installed) and create the symlink /usr/lib64/libpcsclite.so that points to /usr/lib64/libpcsclite.so.1:
cd /usr/lib64
ln -s libpcsclite.so.1 libpcsclite.so
4. Running Smart Card Shell 3 GUI
Be sure the Smart Card Shell 3 GUI is installed. Expand the "Applications" menu (1), go to "Programming" (2), press there "Smart Card Shell 3" (3):
and wait for the appearance of the main window of the program:
During the first run, a new window might appear, asking for configuring the path to a working directory, where the output files will be stored by default. Click the "Browse" button:
select the folder (1) and press "Open" (2) to go back:
Thus path to the folder will appear in the text field (next to the "Browse" button). In addition, mark at least "Use this as the default and do not ask again", to complete the configuration and pressing "OK" to exit:
5. Loading the key manager in Smart Card Shell 3 GUI
Run Smart Card Shell 3 GUI. The key manager is a loadable script, dedicated to manage the objects in the token.
To load it, either expand "File" menu and select there "Key Manager":
or press "Ctrl+M". Once loaded, the key manager will check if the token is connected and will create in the main window a tree of those objects, it discovered in the token. Details about all important events will be reported in the "Shell" tab:
6. Initializing the token and configuring DKEK to enable the import of keys and X.509 certificates from PKCS#12 files
The goal of the initialization process, is to enable the import (export too) of keys and X.509 certificates, stored in files (most often PKCS#12 files), into the token, , based on "device-key-encryption-key" (DKEK) type of store. Note that DKEK is not enabled by default.
WARNING! DURING THE INITIALIZATION, ALL DATA, STORED IN THE TOKEN, WILL BE LOST!
To start with the initialization, run the Smart Card Shell 3, load the key manager script, click once with the right button of the mouse upon "SmartCard-HSM" (that is the root of the key manager tree), and select "Initialize Device" in the menu:
Supply the following information (or press "Cancel" to terminate the initialization):
-
The actual SO-PIN for configuring the token. The default SO-PIN code is 3537363231383830, unless it has been changed (if you forget the SO-PIN, consider the token lost). Press "OK" to continue:
-
The label of the token (that is the token's friendly name, displayed in the PKI applications). Press "OK" to continue:
-
The authentication mechanism for restricting the access to the objects and processor of the token. In most cases, you might need to select "User PIN" (you may set another authentication mechanism, but this one is the most poplar one). Press "OK" to continue:
-
The way to restore the access to the keys and X.509 certificates, if the PIN is lost, forgotten, or locked (if a wrong PIN is entered more than 3 times, consecutively). Select "Resetting PIN with SO-PIN allowed" and press "OK" (select "Resetting PIN with SO-PIN not allowed" only in specific cases, where the implementation of such policy is necessary):
-
The new PIN code (do not use the number shown in the picture bellow). Press "OK" to continue:
-
The new PIN code (again, for confirmation). Press "OK" to continue:
-
Request for using "DKEK Shares". Press "OK" to continue:
-
The number of DKEK shares (use 1, unless you are expert). Press "OK" to continue:
-
Press "Cancel" here (if you press "OK" both SO-PIN and PIN codes will be stored locally in an unencrypted file):
After the success of the initialization, you will see only three objects displayed in the key manager tree: User PIN, SO-PIN, and DKEK entry. The message "Initializing complete" (an indication that the requested initialization has been successfully completed) will be seen in the "Shell" tab:
Note, that at this point, the requested DKEK shares are not yet initialized or/and imported to the token! The appearance of "DKEK set-up in progress with 1 of 1 shares missing" in the key manager tree indicates that. You need to request manually the creation of DKEK shares file and import its content to the token, by following strictly the instructions given bellow:
-
Request the creation of DKEK share, by clicking once with the right button of the mouse on the root of the key manager tree (on "SmartCard-HSM) and picking "Create DKEK share" in the menu:
-
Enter the name of DKEK file to create, and press "OK" (store the file in the working directory of the program, configured during the first run):
-
Set the password for protecting the DKEK share file content and press "OK":
-
Confirm the password for protecting the DKEK share file content and press "OK":
-
With the left button of the mouse, click once upon the object named "DKEK set-up in progress with 1 of 1 shares missing", displayed in the key manager section of the main window of the program:
-
Use the button "Browse" to find and choose the created DKEK file (file extension is *.pbe), and press "OK":
-
Enter the password set (before) for protecting the content of the DKEK file:
It will take up to 10 seconds to derive the keys and import the DKEK into the token (watch the related messages, appearing in the "Shell" tab). At the end, you will see that the object "DKEK set-up in progress with 1 of 1 shares missing" (in the key manager tree) will be renamed (the new name will include the ID of the DKEK object):
IMPORTANT! At this point, you need to store a copy of the DKEK share file, generated during the initialization, in a safe place!
In the examples above, that file is /home/vesso/CardContact/2019_02.pdb, but in you case the file will be with different name and location.
7. Generating ECC key pair (by means of DKEK shares)
IMPORTANT! Be absolutely sure that no application, other than Smart Card Shell 3, is communicating with the token. Stop all running processes of PKCS#11 compatible software (like Mozilla Firefox, Mozilla Thunderbird, Google Chrome, XCA), that might take over the token.
Start the Smart Card Shell 3, plug the token into the USB port, and load the key manager script. Be sure that the token is initialized properly, to support DKEK shares.
Click once on the token name, in the key manager section, with the right button of the mouse and select "Generate ECC Key" in the menu:
Select the elliptic curve type, and press "OK":
Provide a friendly name (alias) for the key pair (it is an internal name for naming the key pair object in the token) and press "OK":
Type (separated by comma) the list of the hex codes of the signature algorithms, that will be allowed for the signing, when using the encryption key (the most commonly used ones, 73,74,75, are given in the example bellow), then press "OK":
Wait until the token is finishing with the generation of the requested key pair. Once ready, you will see the new key object under the tree of the DKEK share:
7. Importing key pair and the corresponding X.509 certificate from PKCS#12 file into the token (by means of DKEK shares)
IMPORTANT! Be absolutely sure that no application, other than Smart Card Shell 3, is communicating with the token. Stop all running processes of PKCS#11 compatible software (like Mozilla Firefox, Mozilla Thunderbird, Google Chrome, XCA), that might take over the token.
Otherwise the PKCS#12 import might fail, by rising (in the "Shell" tab) the following error:
GPError: Card (CARD_INVALID_SW/27010) - "Unexpected SW1/SW2=6982 (Checking error: Security condition not satisfied) received" in ...
Start the Smart Card Shell 3, plug the token into the USB port, and load the key manager script. Be sure that the token is initialized properly, to support DKEK shares. Using DKEK share in this case is mandatory for this operation.
-
Click once on the token name in the key manager section, with the right button of the mouse, and select "Import from PKCS#12" in the menu:
-
Specify the number of DKEK shares to use (use 1, if you follow the recipes provided in this document), and click "OK":
-
Select the file, containing the DKEK shares (use the file name created during the initialization), and click "OK":
-
Enter the password for decrypting the DKEK file (that password is set during the creation of the file), click "OK", and wait up to 10 seconds for generating the shared keys:
-
Select the PKCS#12 file and click "OK":
-
Provide the password, set for protecting the content of the PKCS#12 file, and click "OK":
-
Select the key pair and X.509 certificate to import from the PKCS#12 file, by choosing their internal PKCS#12 name, and click "OK":
-
Enter a name to assign to the imported key pair and X.509 certificate, and click "OK":
-
Click "OK" if you wanna import more key pairs and X.509 certificates, stored in the same PKCS#12 file, or click "Cancel" to finish:
If the import is successful, you will see the key pair imported into the DKEK share (in the key manager section), and information about the process, in the "Shell" section (as shown in the red frames bellow):
IMPORTANT! You cannot import X.509 certificate chain from a PKCS#12 container into the token, by using the procedure proposed above.
But you might do that later, by using pkcs11-tool, it that is really necessary. Notice, that the X.509 certificates in the chain are public information and they might be used in out-of-the-box manner (installed in the software certificate repository of the browser, which will be using with the token). Their presence in the token storage is not mandatory.
