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
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
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
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
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:
HSM-server-<hostname>.crt
to the
client machine"Yes"
"Local Machine"
and click "Next"
"Place all certificates in the following store"
and select "Trusted Root Certificate Authorities"
"Ok"
to install<installation-dir>\cert\client\HSM-client-<hostname>.crt
<installation-dir>\cert\client\HSM-client-<hostname>.key
Copy both files to the Prometheus installation and update the Prometheus configuration file as described in the Prometheus section of this README.
Remarks:
Certificate creation with dsmcertificate.exe
does not
overwrite any files, as certificate files may already be in use on
HTTPS-client side. However, if you would like to cleanup existing files,
use
> dsmcertficate delete-cert [-cn <CN>]
Certificate information can be obtained using the OpenSSL command
> openssl x509 -text -noout -in <file.crt|file.pem>
Private key access requires a password. Private key information can be obtained using the OpenSSL command
> openssl rsa -text -noout -in <file.key|file.pem>
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 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:
If Prometheus does not start, make sure that the YML indention structure is correct. The syntax of the Prometheus YML configuration file is sensible regarding indention.
If Prometheus does start but the connection does not work, try to disable security
tls_config:
insecure_skip_verify: true
# cert_file: C:\Prometheus\HSM-client-<hostname>.crt
# key_file: C:\Prometheus\HSM-client-<hostname>.key
If Prometheus does still not connect, check your firewall settings.
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