HSM for Windows - REST API

The HSM for Windows webserver uses secure HTTPS connections to its clients, TLS 1.2 or higher.
If no valid certificate exists, the HSM net service, hsmnet, will not start.

Prerequisites
Certificates
Configuration
Prometheus
Multiple HSM Installations

Prerequisites


HSM certificate creation and handling requires a Windows OpenSSL 1.1.1 LTS installation. The OpenSSL version is important, other branches will not work.

We recommend NOT to install OpenSSL files in the Windows system32 directory, but in the OpenSSL installation directory.

HSM searches required OpenSSL binaries at runtime using the PATH environment variable. Add the OpenSSL bin-directory (NOT the installation directory) to the PATH variable on the HSM file server. Make sure, that the two files libcrypto-1_1-x64.dll and libssl-1_1-x64.dll are located in the bin-directory. Check the version using

> openssl version

Certificates


In order to use secure TLS connections to the Prometheus TSDB, you may create self-signed certificates by issuing

> dsmcertficate self-cert [-cn <CN>] [-p[s]]

in a command shell in the HSM installation root. The certificate is created for the computer, where the command is executed.

The computer name can be specified with option -cn. TLS certificates require the fully specified hostname in the CN (Common Name) entry of the issuer. If option -cn is omitted the certificate is created for the computer using the FQDN (fully qualified domain name). You will be asked twice for the password.

A password can optionally be created from random data using option -p[s]. -p creates certificates without showing the password, -ps also prints the password to the command line.

The command will create 4 files in the cert-subdirectory:

<installation-dir>\cert\HSM-server-<hostname>.pem
<installation-dir>\cert\client\HSM-server-<hostname>.crt
<installation-dir>\cert\client\HSM-client-<hostname>.crt
<installation-dir>\cert\client\HSM-client-<hostname>.key

<hostname> is the fully qualified name of the HSM file server machine, or the name specified in option -cn.

Use the 4 files in the following manner:

<installation-dir>\cert\HSM-server-<hostname>.pem
contains an encrypted, private RSA key, as well as a self-signed X509 server certificate.

The file is used by the HSM webserver. The path to this file is stored in the registry, so do not move the file away from its place.

<installation-dir>\cert\client\HSM-server-<hostname>.crt
contains only the X509 server certificate, i.e. a part of HSM-server-<hostname>.pem.

To use the certificate, you need to install the certificate in the certificate store of your webclient, which is Prometheus. Follow these steps to install the certificate on Windows:

<installation-dir>\cert\client\HSM-client-<hostname>.crt
<installation-dir>\cert\client\HSM-client-<hostname>.key
contain a client certificate, and client key, respectively.

Copy both files to the Prometheus installation and update the Prometheus configuration file as described in the Prometheus section of this README.

Remarks:

Configuration


The HSM net service, hsmnet, is configured not to start automatically, by default. To start and stop the service manually enter

> net start hsmnet
> net stop hsmnet

The HSM net service listens on port 8888, per default. The port can be changed using regedit in the Windows registry at

HKLM\Software\IBM\ADSM\CurrentVersion\HsmClient\Net\ListeningPorts 8888s

Note, that the trailing character s must be appended for HTTPS ports.

Prometheus


Prometheus comes with a configuration file, that is named prometheus.yml, by default. Add an HSM job to the configuration file, e.g.


  # HSM for Windows Clients
  - job_name: 'hsm'
  
    scrape_interval: 30s
    scrape_timeout: 30s
    static_configs:
      - targets: ['<hostname>:8888']
  
    scheme: https
  
    tls_config:
      cert_file: C:\Prometheus\HSM-client-<hostname>.crt
      key_file:  C:\Prometheus\HSM-client-<hostname>.key
  
    metrics_path: /prometheus
   

Then, start prometheus.exe and wait until Prometheus has started.

Remarks:

Multiple HSM Installations


To monitor more than 1 HSM installation, you may add multiple jobs to the Prometheus configuration file, one for each separate installation.

Another way is to add multiple HSM installations to the same Prometheus configuration job.

Example with 2 HSM installations:

The client certificate files HSM-client-*.crt from the 2 HSM installations are stored in HSM-client.crt, and client key files HSM-client-*.key are stored in HSM-client.key, i.e.

> type HSM-client-<hostname1>.crt > HSM-client.crt
> type HSM-client-<hostname2>.crt >> HSM-client.crt

> type HSM-client-<hostname1>.key > HSM-client.key
> type HSM-client-<hostname2>.key >> HSM-client.key

You may also use

> merge-certs.bat

to automatically create the merged files. Copy all certificate and key files, as well as merge-certs.bat, from the HSM directory <installation-dir>\cert\client\ to the Prometheus installation, then run merge-certs.bat in the current directory.


  # HSM for Windows Clients
  - job_name: 'hsm'
 
    scrape_interval: 30s
    scrape_timeout: 30s
    static_configs:
      - targets: ['<hostname1>:8888','<hostname2>:8888']
 
    scheme: https
 
    tls_config:
      cert_file: C:\Prometheus\HSM-client.crt
      key_file:  C:\Prometheus\HSM-client.key
 
    metrics_path: /prometheus