Cloud-HSM

Using a SmartCard-HSM as Cloud-HSM is basically using the RAMOverHTTP client to permanently connect a local SmartCard-HSH to a cloud service using the RAMOverHTTP protocol.

Cloud services typically run in virtual environments that do not have physical USB-Ports to which you can connect a SmartCard-HSM. You can rarely enter the server room of your favorite cloud provider and attach a SmartCard-HSM USB-Token to one of the servers.

This is where a Cloud-HSM setup come to play, where you permanently connect a SmartCard-HSM to the cloud service, so that the cloud service can access keys on the token. The technology that makes this available is the OCF Servlet and the SmartCard-HSM JCE-Provider from OpenSCDP. Both components are used in the software of the PKI-as-a-Service Portal.

Building the ram-client

The ram-client is part of the sc-hsm-embedded project hosted at GitHub. It is a library and a program written in C, that uses CURL and OPENSSL to implement the protocol.

The project uses automake as build system, so the traditional

./configure --enable-ram
make
sudo make install

will configure, compile and install the software. If you use

git clone https://github.com/CardContact/sc-hsm-embedded

to checkout from GitHub, then you will need to enter

autoreconf -fis

to bootstrap the autotools. The --enable-ram option is required, as the ram-client is not build by default.

You will need to install the CURL and OPENSSL development libraries (libcurl4-openssl-dev and libssl-dev on Debian) and libpcsclite1 for PC/SC access.

For Windows, the sc-hsm-embedded project has a meson branch that builds with MSYS2. See the readme for details.

Testing the ram-client

To test the ram-client and the installation use

asc@raspi2:~ $ ram-client -l
Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026231832) 00 00
No URL defined
Completed

It shows that a card reader was detected and no URL was defined for connection. You can select the card reader or token with -r.

asc@raspi2:~ $ ram-client -r "Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026231832) 00 00"
No URL defined
Completed

Please note, that the reader name must be quoted, as it contains spaces.

Adding an URL will connect the SmartCard-HSM to the RAMOverHTTP endpoint.

asc@raspi2:~ $ ram-client -r "Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026231832) 00 00" https://test.pki-as-a-service.net/sems-rt/hsm
(0) Provider added

The ram-client continues to run, until the portal ends the connection or an error occurs. The (0) Provider added message is from the portal to inform that the JCE-Provider has added the HSM.

To see APDUs exchanged with the service you can use the -v option.

asc@raspi2:~ $ ram-client -r "Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026231832) 00 00" https://test.pki-as-a-service.net/sems-rt/hsm -v
C: 00200081
R: 63C3
C: 00A404000BE82B0601040181C31F0201
R: 6F0A820178850500000604019000

If you configured your SmartCard-HSM to use Public Key Authentication then you are are all set. Authentication to enable access to keys is done in the TrustCenter view. If you configured a user PIN, then this PIN can be provided with the -p <pin> option.

Automating the ram-client

For a permanent connection it is important, that the connection is reestablished after an outage or communication error. This can be achieved using a systemd unit file:

[Unit]
Description=SmartCard-HSM for Test DICA
After=network.target

[Service]
ExecStart=/usr/local/bin/ram-client -r "Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026231832)" -v -p 648219 https://test.pki-as-a-service.net/sems-rt/hsm
User=root
Type=simple
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

You need to place the above unit definition with the extension .service in the /etc/systemd/system directory. After that run

systemctl daemon-reload

to load the unit file. With the command

root@raspi2:/etc/systemd/system# systemctl status hsm-test-dica
○ hsm-test-dica.service - SmartCard-HSM for Test DICA
     Loaded: loaded (/etc/systemd/system/hsm-test-dica.service; disabled; preset: enabled)
     Active: inactive (dead)

you can see, that the service is now known. Use `systemctl start' to start the service.

root@raspi2:/etc/systemd/system# systemctl start hsm-test-dica
root@raspi2:/etc/systemd/system# systemctl status hsm-test-dica
● hsm-test-dica.service - SmartCard-HSM for Test DICA
     Loaded: loaded (/etc/systemd/system/hsm-test-dica.service; disabled; preset: enabled)
     Active: active (running) since Tue 2026-03-03 13:16:14 GMT; 2s ago
   Main PID: 21656 (ram-client)
      Tasks: 1 (limit: 1595)
        CPU: 336ms
     CGroup: /system.slice/hsm-test-dica.service
             └─21656 /usr/local/bin/ram-client -r "Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026231832)" -v -p 648219 https://test.pki-as-a-service.net/sems-rt/hsm

Mar 03 13:16:16 raspi2 ram-client[21656]: R: 99026A888E0808C13145EE30C6B16A88
Mar 03 13:16:16 raspi2 ram-client[21656]: C: 0CB1C70F00002085100D84A2696433CAAEF016771C698E1679970204AF8E087E3FC08F17349E8B0000
Mar 03 13:16:16 raspi2 ram-client[21656]: R: 99026A828E08DD9FC065B5561DE96A82

To start this service automatically, you need to enable it.

systemctl enable hsm-test-dica