Compiling GROMACS 2019.5 with Intel Compilers and CUDA on CentOS 7 and 8

All tests reported bellow are performed by using Intel Parallel Studio XE 2019 Update 4. I presume you may achieve the same positive results using older versions of the Intel Compilers package.

Notes on CentOS 7: You have to install the SCL repository and EPEL (that are MANDATORY requirements you cannot skip):

$ sudo yum install centos-release-scl centos-release-scl-rh epel-release

Then, using the new repositories, install dvetoolset-8 and cmake3:

$ sudo yum install devtoolset-8 cmake3

In the bash session, where the compilation process will take place, execute:

$ scl enable devtoolset-8 bash

To install the CUDA latest compiler and libraries, you might use the procedure described in my previous posts. The latest version of CUDA is 10.2. Once all the pre-requisites are satisfied, download the GROMACS 2019.5 source code tarball, unpack it, create a folder named "build" inside the source tree, enter it, load the Intel Compilers variables, then the SCL environment and run the compilation and installation process:

$ mkdir ~/build
$ cd build
$ wget ftp://ftp.gromacs.org/pub/gromacs/gromacs-2019.5.tar.gz
$ tar xvf gromacs-2019.5.tar.gz
$ cd gromacs-2019.5
$ mkdir build
$ cd build
$ source /opt/intel/compilers_and_libraries/linux/bin/compilervars.sh intel64
$ CC=icc CXX=icpc CFLAGS="-xHost" CXXFLAGS="-xHost" cmake3 .. -DCMAKE_INSTALL_PREFIX=/usr/local/appstack/gromacs-2019.5-icc -DGMX_MPI=OFF -DGMX_BUILD_OWN_FFTW=OFF -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda -DGMX_FFT_LIBRARY=mkl
$ make -j6 install

The product of the compilation will be installed in /usr/local/appstack/gromacs-2019.5-icc. You might change that destination by set another value to -DCMAKE_INSTALL_PREFIX.




Read More

Getting ssllabs.com class "A+" by matching at 100% Key Exchange and Cipher Strength criteria

In most cases, getting "A+" rate by the TLS ssllabs.com server checker, does not necessary mean the examined server matches fully (at 100%) all criteria. For instance, "A+" might be given if your server matches partially (at 90% level) the requirements for key exchange protocols and cipher strength:

In my case, I got "A+" status for my Apache/mod_ssl 2.4.6 server (on CentOS 7) by using limited and very conservative list of ciphers (it is a long story about why I do avoid using "CBC"-based ciphers):

ECDHE-RSA-AES256-GCM-SHA384
DHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-AES128-GCM-SHA256
DHE-RSA-AES128-GCM-SHA256

So far (8 months since I implemented the new TLS configuration), I haven't received any complaints from my clients, related to TLS issues. Seems like they keep their mobile and desktop browsers very much up to date.

Recently, for another project (PKI-based one) I decided to go further and try to get "A+" by matching all criteria at 100% (using the same Apache/mod_ssl 2.4.6 setup on CenOS 7):

What I have done? I just removed from the list above the 128-bit ciphers:

ECDHE-RSA-AES256-GCM-SHA384
DHE-RSA-AES256-GCM-SHA384

How does this change affect the clients? I got only 1 complaint from a person who is used to use Firefox on CentOS 6 (rather old distribution for a desktop, I dare say). On the other side, even mobile clients with Android 6.0, using Samsung Internet Browser, do not have any problem with the new TLS cipher set.

What was surprising is that replacing RSA server certificate with ECDSA-based one, does not create any significant TLS issues. Again, the first set of ciphers I tested (where "A+" is matched only partially), was based on both 256 and 128-bit ciphers:

ECDHE-ECDSA-AES256-GCM-SHA384
ECDH-ECDSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES128-GCM-SHA256
ECDH-ECDSA-AES128-GCM-SHA256

and the second one included only 256-bit based ciphers:

ECDHE-ECDSA-AES256-GCM-SHA384
ECDH-ECDSA-AES256-GCM-SHA384

It seems like most of the browser and OS vendors take a lot of measures to secure the TLS protocol implementation in their software products.

Read More

Re-deriving AES and 3DES attribute encryption keys for 389 Directory Server installation

1. Introduction

Even if you do not use attribute encryption keys in your 389 Directory Server (DS) installation, you might be bothered by all those messages that repeat themselves in /var/log/dirsrv/slapd-instance_name/error ("instance name" is your actual instance name), after every start/restart of the 389 DS daemon:

[04/Nov/2019:02:03:16.808096029 +0200] - ERR - attrcrypt_cipher_init - No symmetric key found for cipher AES in backend userRoot, attempting to create one...
[04/Nov/2019:02:03:16.843731964 +0200] - ERR - attrcrypt_wrap_key - Failed to wrap key for cipher AES
[04/Nov/2019:02:03:16.808096029 +0200] - ERR - attrcrypt_cipher_init - No symmetric key found for cipher 3DES in backend userRoot, attempting to create one...
[04/Nov/2019:02:03:16.843731964 +0200] - ERR - attrcrypt_wrap_key - Failed to wrap key for cipher 3DES

What causes their appearance and how to get rid of them (and to solve the problem they point to)?

There are two reasons for those message to be seen in /var/log/dirsrv/slapd-instance_name/error:

• the RSA-based X.509 certificate, used by the 389 DS server, was replaced with a new one and it has new encryption key (that situation might be fatal if your LDAP directory hosts encrypted attributes and the old RSA keys were lost);
• the 389 DS server uses Elliptic Curves based X.509 certificate.

First, some important remarks. While it is true that failing to access the attribute encryption keys is not a fatal event to most of the 389 DS installations, where upon the attribute encryption is not necessary and therefore - not truly implemented, the appearance of those error messages might indicate a disruption of some other services (especially those that frequently query the LDAP server). That means, you really have to investigate the source of those errors, if your goal is a reliable 389 DS installation.

2. The RSA-based X.509 certificate, used by the 389 DS server, was replaced with a new one and it has new encryption key

Go down to "Deriving new attribute encryption keys" to see how to fix the problem.

3. The 389 DS server uses Elliptic Curves (ECC) based X.509 certificate

389 Directory Server stores the keys, certificates, and passwords in Mozilla NSS DB storage. It is usually located inside the folder /etc/dirsrv/slapd-instance_name, where "instance_name" is the actual instance name of your 389 Directory Server setup (depends on how did you name the instance). The NSS DB store is split into three files: cert8.db, keys3.db, and secmod.db.

If the 389 Directory Server is configured to use SSL (and STARTTLS), a X.509v3 certificate is installed in the NSS DB store. The problem is that by default (so far), the administrative server sets any X.509 certificate in use, as if it is RSA-based. Therefore, in /etc/dirsrv/slapd-instance_name/dse.ldif (that is the starting configuration of the instance), you will find the entry:

dn: cn=RSA,cn=encryption,cn=config
objectClass: top
objectClass: nsEncryptionModule
cn: RSA
nsSSLPersonalitySSL: server-cert
nsSSLToken: internal (software)
nsSSLActivation: on

even if the X.509 certificate with nickname "server-cert" installed there (the nickname the certificate is know under in the NSS DB store) is ECDSA-based. And this "masking" of the ECDSA-based certificate as RSA, causes those errors from above to appear, when the SSL certificated is ECDSA-based. Note that the current method for deriving 3DES and AES attribute encryption keys is based on RSA encryption keys only. To solve this problem (especially if you want to deliberately generate 3DES and AES keys), you need to implement some workaround. That workaround works in the following way. Define an entry for the ECDSA certificate in the starting configuration (replace "server-cert" with your actual ECDSA X.509 certificate nickname, listed in the NSS DB certificate store):

$ ldapadd -D "cn=Directory Manager" -x -W
dn: cn=ECDSA,cn=encryption,cn=config
objectClass: top
objectClass: nsEncryptionModule
cn: ECDSA
nsSSLPersonalitySSL: server-cert
nsSSLToken: internal (software)
nsSSLActivation: on

Then import into NSS DB certificate store new RSA certificate, that will be used only to support the attribute encryption key generation (we assume its nickname is "keygen-cert"), remove the old dn "cn=RSA,cn=encryption,cn=config" (if exists):

$ ldapdelete -D "cn=Directory Manager" -x -W "cn=RSA,cn=encryption,cn=config"

and add it again, pointing this time the attribute "nsSSLPersonalitySSL" to the RSA certificate nickname ("keygen-cert" in the example bellow):

$ ldapadd -D "cn=Directory Manager" -x -W
dn: cn=RSA,cn=encryption,cn=config
objectClass: top
objectClass: nsEncryptionModule
cn: RSA
nsSSLPersonalitySSL: keygen-cert
nsSSLToken: internal (software)
nsSSLActivation: off

PAY ATTENTION: To avoid the use of RSA certificate as a host certificate, and to force the use of ECDSA one for that purpose, you have to set nsSSLActivation to off. That is mandatory!

At this point, you might restart your 389 Directory Server instance:

$ sudo systemctl restart dirsrv@instance_name

Then proceed to "Deriving new attribute encryption keys".

4. Deriving new attribute encryption keys

If you don't know how many back-ends does your 389 DS currently supports, you might check that:

$ ldapsearch -D "cn=Directory Manager" -b "cn=config" -x -W "nsslapd-backend=*" nsslapd-backend | grep ^nsslapd-backend | awk '{print $2}'

(you will have to know the "cn=Directory Manager" password to complete the search). In most cases (default setup schema) the result will look like this:

userRoot

If the administrative server is also installed and configured, the NetscapeRoot back-end will be shown too:

NetscapeRoot
userRoot

The next step is to delete the dn-objects containing the AES and 3DES attribute encryption keys. For each back-end, you need to execute (replace BACKEND with the actual name of the back-end):

$ ldapdelete -D "cn=Directory Manager" -x -W "cn=AES,cn=encrypted attribute keys,cn=BACKEND,cn=ldbm database,cn=plugins,cn=config"
$ ldapdelete -D "cn=Directory Manager" -x -W "cn=3DES,cn=encrypted attribute keys,cn=BACKEND,cn=ldbm database,cn=plugins,cn=config"

If you receive "No such object" as a result, that might be a proof that only X.509 ECC-based certificates have been used with the current installation of 389 DS, ever since it was created.

You can restart now the 389 DS daemon (replace "instance_name" with your actual 389 Directory Server instance name):

$ sudo systemctl restart dirsrv@instance_name

and if the keys were successfully derived during the restart of 389 DS daemon, you will see the following messages at the end of /var/log/dirsrv/slapd-instance_name/error (two lines for each back-end):

[04/Nov/2019:04:57:08.393260367 +0200] - ERR - attrcrypt_cipher_init - No symmetric key found for cipher AES in backend userRoot, attempting to create one...
[04/Nov/2019:04:57:08.446317176 +0200] - INFO - attrcrypt_cipher_init - Key for cipher AES successfully generated and stored
[04/Nov/2019:04:57:08.470085086 +0200] - ERR - attrcrypt_cipher_init - No symmetric key found for cipher 3DES in backend userRoot, attempting to create one...
[04/Nov/2019:04:57:08.504787008 +0200] - INFO - attrcrypt_cipher_init - Key for cipher 3DES successfully generated and stored

No such messages will appear again during the next restarts, unless you remove the employed RSA-based X.509 certificates from the NSS DB.

Read More

Keep away the SSH scan bots by hardening the SSH key-exchange on the server side (CentOS/RHEL 7/8 case)

Analyzing the SSH login attempts, regularly performed by a vast number of bots, one can detect and interesting pattern - they use old-fashioned key-exchange protocols, like diffie-hellman-group1-sha1, diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha1. I am not a bot operator myself and I cannot be absolutely sure why do the bot operators and programmers use those old key exchange protocols. I only speculate here, but they either target old SSH installations (old OpenSSH/SSH.com server version), or the bot software employs some old SSH library.

Knowing that certain pattern in the key-exchange, it might be easy to get rid of most of the SSH scans, by simply hardening the key-exchange configuration on the SSH server. To do that, add to the end of your /etc/ssh/sshd_config the following line:

• on CentOS 7/RHEL 7:

  Edit /etc/ssh/sshd_config by appending to its end the line:

  KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512

  Save the changes and restart sshd:

  # systemctl restart sshd

on CentOS 8/RHEL 8:

Edit CRYPTO_POLICY declaration in /etc/crypto-policies/back-ends/opensshserver.config by replacing there the -oKexAlgorithms declaration with:

-oKexAlgorithms=curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp384,ecdh-sha2-nistp521

Save the changes and restart sshd:

# systemctl restart sshd

Finally (after implementing the recommendations from above), tail /var/log/secure and prove that the bots are being repelled. You should see lines like those:

Nov  2 05:07:36 server sshd[26440]: Unable to negotiate with xxx.xxx.xxx.xxx port 28482: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha1 [preauth]
Nov  2 05:16:53 server sshd[26517]: Unable to negotiate with xxx.xxx.xxx.xxx port 14046: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha1 [preauth]

Important note: some old SSH clients might not "speak" the modern key-exchange algorithms, like those recommended above!

Even if the suggested key-exchange settings might drop some of your actual SSH clients, it is better to keep the configuration, for it is the only way to show your SSH users that the SSH clients get old too and they should be replaced or upgraded to keep up with the modern cryptography requirements.

Read More

Using TLSv1.3 and strong cryptography for 389 Directory Server (on CentOS 7)

TLS v1.3 support came recently to the 389 Directory Server (via mod_nss) with the latest CentOS 7. Due to an inconstancy between EPEL and CentOS7 upstream, TLS v1.3 is not currently available to the dirsrv admin service!

To activate the TLS v1.3 protocol for 389 Directory Server, do prepare a LDIF file, and describe there the modification that will take place in "cn=encryption,cn=config" (a dn-object which is a part of the 389 start up configuration), and insert there the following text:

dn: cn=encryption,cn=config
changetype:modify
replace: sslVersionMin
sslVersionMin: TLS1.2

dn: cn=encryption,cn=config
changetype: modify
replace: nsSSL3
nsSSL3: off

dn: cn=encryption,cn=config
changetype: modify
replace: nsSSL3Ciphers
nsSSL3Ciphers:  +TLS_CHACHA20_POLY1305_SHA256,+TLS_AES_256_GCM_SHA384,+TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,+TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

Save that content as "modify.ldif", then invoke ldapmodify, and authenticate as "cn=Directory Manager" to enforce the modification:

$ ldapmodify -D "cn=Directory Manager" -x -W -f modify.ldif

In case of successful modification, the following message will appear:

modifying entry "cn=encryption,cn=config"

At this point you need to restart 389 Directory Server:

systemctl reload dirsrv@instance-name

and check if the requested cipher suite, already requested for TLS v1.2 above, is really available to the server (replace "localhost" with the actual server name of your 389 server):

$ nmap -sV --script ssl-enum-ciphers -p 636 localhost

In latest Fedora, CentOS, and Ubuntu, one can use openssl (>= 1.1.1) to verify that that TLS v1.3 is successfully configured and (therefore) available (just replace "server-name" down bellow with your actual server name):

$ openssl s_client -connect server-name:636

This is how a positive result, the one detecting the presence of TLS v1.3, will appear on your screen:

New, TLSv1.3, Cipher is TLS_CHACHA20_POLY1305_SHA256
Server public key is 4096 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent

Read More

Using high-grade ECC temporary keys with Apache and mod_ssl on CentOS 7

To support ECHDE-based SSL ciphers, your Apache server (through mod_ssl) needs a temporary ECC key to be generated and loaded during each start or restart of the httpd daemon. While on RHEL8 and CentOS 8 you can automatically generate and load such keys, every time when Apache daemon is invoked, simply by adding the declaration:

SSLOpenSSLConfCmd Curves P-384

to the section in /etc/httpd/conf.d/ssl.conf, there is no such support in mod_ssl 2.4.6 - the version shipped with CentOS 7. That does not mean mod_ssl 2.4.6 does not support ECDHE and the use of temporary ECC keys. It supports it, but instead of allowing the temporary ECC key size to be configured as a parameter in /etc/httpd/conf.d/ssl.conf, it sticks only to 256-bit secp256k1 key. Key of that size might not be suitable (cannot be recognized secure enough) for use in long-time running Apache instances. One workaround here is to manually generate ECC key, using secp384r1 (that is high-grade key), and add it to the end of the certificate file (that is the file pointed by the SSLCertificateFile declaration in /etc/httpd/conf.d/ssl.conf).

To generate the key, use openssl:

$ openssl ecparam -genkey -name secp384r1

The output will look like:

-----BEGIN EC PARAMETERS-----
BgUrgQQAIg==
-----END EC PARAMETERS-----
-----BEGIN EC PRIVATE KEY-----
MIGkAgEBBDCL5996z0+JsNAR2boRU0zULurtLbKbILiysJx3BbWEWFrlkuXL11BS
MI9bqrYNXjOgBwYFK4EEACKhZANiAAQISZYiUhc3GUXCaxOfsNun9KBiMyp9yAR3
qGH2NR1Va51Q4WfS4X0XPCaa3w3gA5g69MQV8aak3BVnbE27Q+yAZ5zi+dSNt5VU
Jg1tGgZmzX+SfJ6WWtMSv0Aa3r62UEE=
-----END EC PRIVATE KEY-----

Add it to the end of the certificate file, right after the line:

-----END CERTIFICATE-----

Save the changes to the file and reload or restart Apache's daemon httpd:

$ sudo systemctl reload httpd

To check if the server is successfully loaded and using the newly generated 384-bit long temporary key, use openssl:

$ openssl s_client -connect your_server_name:443

In case of success, you should see in the result the following line:

Server Temp Key: ECDH, P-384, 384 bits

NOTES: The configuration of mod_ssl should include at least one ECDHE cipher. Do not try to go to 521-bit key, for it is not supported by some browsers (yet).

Read More

How to protect the Google Chrome NSS Certificate DB store in Linux with password

Google Chrome for Linux, keeps the installed X.509 certificates and keys in NSS Certificate DB store, which is not protected by default. That means, everyone with access to the browser and/or the user's home directory, can copy the signing keys. The goal of this memo is to explain how to protect the Google Chrome's certificate store with password.

Note, that the folder, where Google Chrome keeps the NSS Certificate DB files per user is:

${HOME}/.pki/nssdb

During its first start (initiated by the user), the browser generates the NSS Certificate DB store files there in:

cert9.db
key4.db
pkcs11.txt

It is very important to keep in mind that Google Chrome uses SQLite3-based format of NSS Certificate DB, when using the NSS tools to manage the database.

To list the content of the database, use the tool certutil (mind the file system locator "sql:" that is after "-d" in the command line bellow):

$ certutil -L -d sql:${HOME}/.pki/nssdb

If there are X.509 certificates installed in NSS Certificate DB, you will see their friendly names and trust attributes (otherwise, only the column descriptions will be displayed).

To set the password for protecting the keys and the integrity of NSS Certificate DB, stop Google Chrome first (check if it is running), and then execute the following command line:

$ certutil -W -d sql:${HOME}/.pki/nssdb

That will start a dialogue in the terminal. At the beginning, you will need to type the current password (simply press "Enter" to try the default password, which is an empty string):

Enter Password or Pin for "NSS Certificate DB":

If that is the correct password, the next step will begin with the following statement displayed:

Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

followed by a prompt, where the new password for protecting NSS Certificate DB to be entered twice:

Enter new password:
Re-enter password:

If the new password is correctly typed, a confirmation message will be displayed:

Password changed successfully.

From this moment onward, the installation of new certificates (with or without their private keys) in NSS Certificate DB, as well as the access to the installed private keys, will be granted based on password.

To verify the password controlled access to the NSS Certificate DB is working, run Google Chrome, type in the address bar:

chrome://settings/certificates

and press "Enter". If NSS Certificate DB is password protected, the following window will appear on the screen:

(note the window description saying "Please sign in to NSS Certificate DB"). In case you cannot provide the correct password, only read-only access to the NSS Certificate DB will be granted, with no access to the private keys installed there (that means no certificate authenticated logins, no digital signatures).

What if I forget the password for NSS Certificate DB?

You cannot do much, because the private keys, previously installed in the database, are now encrypted with a password you have forgotten. Moreover, the password is irretrievable, since no additional decryption key or another mechanism, that might help to retrieve the password from the locked database files exists, as a part of the NSS Certificate DB design. Hence, if you forget the NSS Certificate DB password, consider the keys installed in there lost.

In case you keep backup copies of the certificates and keys (as PFX/PKCS#12 files), you might create a new database and install them there. To create new NSS Certificate DB, you need to stop Google Chrome (mandatory). Then move the old NSS Certificate DB files to a temporary location (who knows, one day the forgotten password might be found):

$ mkdir ${HOME}/.pki/nssdb-lost
$ mv ${HOME}/.pki/nssdb/* ${HOME}/.pki/nssdb-lost/

and create new database files in ${HOME}/.pki/nssdb:

$ certutil -N -d sql:${HOME}/.pki/nssdb

After the message:

Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

enter the new password twice:

Enter new password:
Re-enter password:

and if the confirmation message:

Password changed successfully.

is displayed, you new (but empty) NSS Certificate DB, is created and protected with password.

Now you can run the Google Chrome and install the certificates and private keys, using the NSS Certificate DB management tools, embedded in the browser.

Read More

SmartCard-HSM USB token: Using Smart Card Shell 3 for initializing and configuring the token, generating key pairs, and importing keys and X.509 certificates from external PKCS#12 containers

Content:

1. Introduction
2. Prerequisites
3. Downloading and installing Smart Card Shell 3
4. Running Smart Card Shell 3 GUI
5. Loading the key manager in Smart Card Shell 3 GUI
6. Initializing the token and configuring DKEK to enable the import of keys and X.509 certificates from PKCS#12 files
7. Generating ECC key pair (by means of DKEK shares)
8. 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.

Read More