Microsoft IIS

General Information

This guide to integrated use with MS IIS (Microsoft Internet Information Services) has been prepared using the software and firmware versions below:

OS: Windows Server 2019 (English)
IIS: 10
HSM firmware: 5.0.26.0 (or higher)
HSM client: 4.7.30 (or higher)
hsmutil utility: 4.7.30 (or higher)

Requirements

Connectivity with the HSM (TCP port 4433).
HSM client software installed, (see Windows topic).
Downloaded hsmutil.exe utility, (check here).
HSM service started.
Windows account with local administration permission.
Credentials of the HSM partition where the private key will be created or imported.
You may need to restart Windows (to load the local machine settings).

Key generated in HSM

Key and CSR generated in HSM via IIS Manager.

Create a Crypto Provider from Dinamo of type RSA Channel (type 12) using the following registry entry.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Dinamo SChannel Cryptographic Provider]
"Image Path"="tacndcsp.dll"
"type"=dword:0000000c

Configure the MS CAPI parameters with the HSM partition credentials in the GUI console (Dinamocon).

Configure the IP address, name and password of a partition in the HSM; and enable CNG. The private key will be generated on this partition.

Note

Keep the Local Machine Configuration option unchecked.

MS CAPI configuration
Open the IISManager screen

IIS Manager
On the IIS Manager Home screen, open the Server Certificates option.

IIS Manager, certificate management
Use the option Create Certificate Request... option to generate a CSR(Certificate Signing Request).

IIS Manager, certificate creation
Fill in the information for the fields that will make up the certificate.

IIS Manager, certificate fields
Choose the Crypto Provider of Dinamo and the size of the private key

IIS Manager, provider selection Dinamo

Write down the path and name of the file with the CSR generated.

CSR file

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIEbzCCA1cCAQAwZTELMAkGA1UEBhMCQlIxCzAJBgNVBAgMAmRmMREwDwYDVQQH
DAhicmFzaWxpYTEPMA0GA1UECgwGZGluYW1vMRcwFQYDVQQLDA5lbmctY3NwLWRp
bmFtbzEMMAoGA1UEAwwDbGFiMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAwENg32Rg9IzuD6wN78syqPLx+OTr9WDWdoaCdKzHGv4ZowZn7svsKc0/HKq6
5m/AyvpUlkDuXF9PJ0TihCcgcTSBDGS5tzdK7b+e+gBC8Jgb1TjE1JnGSbunbKh4
ApPLUCY42tp88fkabvz3Iqp+dHHIDsjG2MDqKrZBX8YXKNPJzJTBihn5glH6unWv
9SrwXZn7AwKqnNQ8NLf1xwQBDQ4b5hzDovmtKhwC39ekhx5Yrtlo8LJ/WM/Lphgk
9UbHpCz4w+L+nZ1FuiS2Fqbi80d1U/YvJuC4X5A5lWxiVLevwH+zmqm+bfKqlOmB
5g68dtxBBh9rvRp6aYOCHxn+sQIDAQABoIIBwzAcBgorBgEEAYI3DQIDMQ4WDDEw
LjAuMTc3NjMuMjBPBgkrBgEEAYI3FRQxQjBAAgEFDA9XSU4tUlZEUDJSUTdISkoM
HVdJTi1SVkRQMlJRN0hKSlxBZG1pbmlzdHJhdG9yDAtpbmV0bWdyLmV4ZTBkBgor
BgEEAYI3DQICMVYwVAIBAR5MAEQAaQBuAGEAbQBvACAAUwBDAGgAYQBuAG4AZQBs
ACAAQwByAHkAcAB0AG8AZwByAGEAcABoAGkAYwAgAFAAcgBvAHYAaQBkAGUAcgMB
ADCB6wYJKoZIhvcNAQkOMYHdMIHaMA4GA1UdDwEB/wQEAwIE8DATBgNVHSUEDDAK
BggrBgEFBQcDATCBkwYJKoZIhvcNAQkPBIGFMIGCMAcGBSsOAwIHMAoGCCqGSIb3
DQMHMA4GCCqGSIb3DQMEAgIAgDALBglghkgBZQMEASowCwYJYIZIAWUDBAEtMAsG
CWCGSAFlAwQBFjALBglghkgBZQMEARkwCwYJYIZIAWUDBAECMAsGCWCGSAFlAwQB
BTANBggqhkiG9w0DAgIBcDAdBgNVHQ4EFgQUjLWAfxVSmthFnKb2sIIIryIwDgcw
DQYJKoZIhvcNAQEFBQADggEBAHruyMBExrnqh8m70dr2CPcIA3Tz23TIYjgaGT+p
PirrYJA9vzf5xaBYD/ghvRHk1LFzw/20CKETFb9qGIH9iUpEH8LVXz3CkuztFxBN
7kcRzW5GO7Xs0C5PhIxPq6ktMsJsWext46LsyNdWD1UOQAPvA5/wPHYe8CvJSmTv
vzUsEkomeGkcR/Y6yX/JeSXXP7qC74D5UWsoY6rWJ67TV9Ox+H+T17iG1n9V/1Z3
GKouUAWFTRddYvbX/jqrfIQVpdSOR04xCkIgn9p9Kqd+pbgFG0SpMirIpAkR+j9a
GT1ckY65z0yvARxdwkFjvCdePvMuyVdlaucjbb2//m61Fc0=
-----END NEW CERTIFICATE REQUEST-----

An RSA private key will be generated on the HSM partition. The name (id) of this key is defined by IIS Manager. Identify and write down the name of the generated key, it will be used later. It may be useful to leave the CLI console hsmcon.exe (command line) showing HSM activity in real time ( Logs/Follow option) to identify the name/id of the generated private key.

HSM log

2021/02/16 17:45:21 00003CE8 00039289 000A3309 session thread up [3]
2021/02/16 17:45:21 00003CE8 0003928A 678CC86D e-conn: 208.115.199.22|208.115.199.22 10.61.53.  60:443 -
2021/02/16 17:45:21 00003CE8 0003928B 000A3309 session thread down [2]|208.115.199.22 10.61.53. 60:443 -
2021/02/16 17:45:24 00003CE7 0003928C DCED7818 new key iispart/CSP0670045F, t: 6, a: 00000001,  c: 31|10.61.53.163 10.61.53.60:4433 iispart
2021/02/16 17:45:24 00003CE7 0003928D DCED7818 R_COOR trying to setup 12EAD6FB1E46ABCB 04|10.61.   53.163 10.61.53.60:4433 iispart
2021/02/16 17:45:24 00003CE7 0003928E DCED7818 R_COOR prepared 12EAD6FB1E46ABCB 04|10.61.53.163    10.61.53.60:4433 iispart
2021/02/16 17:45:24 00003CE7 0003928F DCED7818 iispart/CSP0670045F created|10.61.53.163 10.61.  53.60:4433 iispart
                                               ^^^^^^^ ^^^^^^^^^^^ ^^^^^^^ # (1)!
2021/02/16 17:45:24 00003CE7 00039290 DCED7818 pk iispart/CSP0670045F!F7md3iGOTL34+gRTEo/4okX   +CR719IPywZ2+yqVpegc=, c: 31|10.61.53.163 10.61.53.60:4433 iispart

Key generation in HSM

Take the CSR to a Certificate Authority (CA) to issue the certificate.

This step is external and depends completely on the procedure of the chosen CA. Write down the path and name of the certificate (*.cer file) received from the CA.
In IIS Manager use the option Complete Certificate Request....

IIS Manager, complete the certificate request process
Inform the file of the certificate issued by the CA.

IIS Manager, inform the path of the certificate file received by the CA
At the end of the process, the certificate should be listed in IIS Manager for use on IIS-managed sites.

IIS Manager, list of SSL certificates

Note

IIS Manager will associate the private key and certificate with the CSP Provider in the user account. In the next step, this association will be redone for the CNG Provider and in thelocal machine account.

(Re)associate the key with the certificate in the CNG Provider Dinamo in the local machine account using hsmutil.exe. This re-association is necessary so that the Windows Local Security Authority Subsystem Service can use the key generated in HSM.

Executar o utilitário hsmutil.exe com os parâmetros abaixo. Os valores de <id da chave no HSM> e <hash/fingerprint do certificado> devem ser substituídos conforme explicado a seguir.

hsmutil -j certassignkey -csp "Dinamo HSM Cryptographic Provider" -store local_machine -repo My    -container <id da chave no HSM> -keyspec cng -certhash <hash/fingerprint do certificado>

O <id da chave no HSM> é nome da chave privada gerada no passo acima e identificada. Ele é mostrado também na lista de chaves da partição escolhida do HSM.

RSA key in HSM

Dinamo - Remote Management Console v. 4.7.29.0 2018 (c) Dinamo Networks

HSM 10.61.53.60 e - Engine 5.0.27.0 (DCD) - TCA0000000  - ID iispart
                                                                ^^^^^^^

Keys/Objects - List


Name                                      Type                 T E Label
================================================================================
CSP0670045F                               rsa2048              n y
^^^^^^^^^^^ # (1)!

Total of objects: 1

Press ENTER key to continue...

RSA key in HSM

O <hash/fingerprint do certificado> pode ser verificado diretamente no certificado emitido pela AC, usando o utilitário do Windows certutil (linha de comando) ou abrindo o arquivo do certificado no visualizador do Windows.

Certificate hash verification

PS > certutil <arquivo do certificado> | Select-String 'Cert Hash\(sha1\):'

Cert Hash(sha1): fe8c1b7e672edbc7004a177bc4fad5244c91f4b9

Example of using the association command

hsmutil -j certassignkey -csp "Dinamo HSM Cryptographic Provider" -store local_computer -repo   My -container CSP0670045F -keyspec cng -certhash fe8c1b7e672edbc7004a177bc4fad5244c91f4b9

Change the MS CAPI configuration for the local machine account.

In the HSM client console (Dinamocon), enable the Local Machine configuration option.

MS CAPI configuration with local machine account configuration

Note

The connection test will stop working because the configuration is transferred from the logged-in user's account to the local machine account.
In IIS Manager go to the site (under the Sites branch) where the HTTPS protocol will be bound with the certificate. For example, the Default Web Site.

IIS Manager, Default Web Site, Binding option
In the Bindings... option, click Add to create a new binding

IIS Manager, Default Web Site, Bindings
On the Add Site Binding screen, under Type select https and under SSL Certificate select the certificate issued by the CA and imported above.

IIS Manager, Default Web Site, New Binding details

Test the configuration with browser access to the configured website address.

From a browser, check that the configured website address can be accessed via the https. Check that the certificate used is the one configured above.

For this check, it can be useful to leave the CLI console hsmcon.exe (command line) showing HSM activity in real time ( Logs/Follow option) and verifying that the private key is being activated to close the SSL tunnel.

Logs in HSM

2021/02/16 19:45:05 00003F80 00039C37 13D1B59C iispart auth init, c: 41|10.61.53.163 10.61.53.  60:4433 -
2021/02/16 19:45:05 00003F80 00039C38 13D1B59C iispart auth ok, 10.61.53.163, 6|10.61.53.163 10.   61.53.60:4433 -
                                               ^^^^^^^ # (1)!
2021/02/16 19:45:05 00003F80 00039C39 13D1B59C rsa CSP0670045F!F7md3iGOTL34+gRTEo/4okX +CR719IPywZ2+yqVpegc=, c: 41|10.61.53.163 10.61.53.60:4433 iispart
                                               ^^^ ^^^^^^^^^^^ # (2)!
2021/02/16 19:45:05 00003F80 00039C3A 13D1B59C e-conn: 10.61.53.163|10.61.53.163 10.61.53.   60:4433 iispart
2021/02/16 19:45:05 00003F80 00039C3B 000A3309 session thread down [5]|10.61.53.163 10.61.53.   60:4433 iispart

HSM authentication
Using the key in the HSM

Key generated outside the HSM

Configure the MS CAPI parameters with the HSM partition credentials in the GUI console (Dinamocon).

Configure the IP address, name and password of a partition in the HSM; and enable CNG. The private key will be generated on this partition.

Note

Keep the Local Machine Configuration option unchecked.

MS CAPI configuration

Import the .pfx file into HSM with the hsmcon.exe console (command line).

Write down the name of the private key and certificate imported into the HSM.

Importing a .pfx file into HSM

Dinamo - Remote Management Console v. 4.7.30.0 2018 (c) Dinamo Networks

HSM 10.61.53.60 e - Engine 5.0.27.0 (DCD) - TCA0000000  - ID iispart

Keys/Objects - Import - Asymmetric Keys - PKCS#12

File (local) : iispart.pfx
Private key password : ********
Exportable (y/[n]):
Define an Usage Profile (y/[n]):
Private key name : sslkey
X.509 certificate name (HSM) : sslcert
Public key name (ENTER for none) :

File loaded successfully.

Press ENTER key to continue...

Export the HSM certificate to a file (.cer) with the hsmcon.exe console (command line).

Exporting the certificate

Dinamo - Remote Management Console v. 4.7.30.0 2018 (c) Dinamo Networks

HSM 10.61.53.60 e - Engine 5.0.27.0 (DCD) - TCA0000000  - ID iispart

Keys/Objects - Export - Certificate / PKCS#7 / File

Name (HSM) : sslcert
Output File (local) (ENTER to dump on screen) : ssliss.cer

File exported successfully.

Press ENTER key to continue...

Import the certificate (.cer) to the Local Computer repository using the Snap-in for Certificates (Local Machine) from the Windows Microsoft Management Console (MMC) on the local computer.

Note

Import the .cer file (certificate), not the .pfx file (private key).

MMC, add a Snap-in

MMC, select Certificate Snap-in

MMC, select local machine certificates

MMC, import the certificate

MMC, inform the path of the certificate file

MMC, confirm the My

MMC, list of certificates

Note

The certificate icon in the list does not show a key, as only the certificate has been imported.
(Re)associate the key with the certificate in the CNG Provider Dinamo in the local machine account using hsmutil.exe. This re-association is necessary so that the Windows Local Security Authority Subsystem Service can use the key generated in HSM.

Run the hsmutil.exe utility with the parameters below.
```
hsmutil -j certassignkey -csp "Dinamo HSM Cryptographic Provider" -store local_computer -repo   My -container <id da chave no HSM> -keyspec cng -certhash <hash/fingerprint do certificado>
```
O <id da chave no HSM> é nome da chave privada importada no passo acima e identificada.

O <hash/fingerprint do certificado> pode ser verificado diretamente no certificado emitido pela AC, usando o utilitário do Windows certutil (linha de comando) ou abrindo o arquivo do certificado no visualizador do Windows.
```
PS > certutil <arquivo do certificado> | Select-String 'Cert Hash\(sha1\):'

Cert Hash(sha1): fe8c1b7e672edbc7004a177bc4fad5244c91f4b9
```
Hash or figerprint of the certificate

Example of using the association command:
```
hsmutil -j certassignkey -csp "Dinamo HSM Cryptographic Provider" -store local_computer -repo   My -container sslkey -keyspec cng -certhash fe8c1b7e672edbc7004a177bc4fad5244c91f4b9
```
After the certificate and private key have been successfully associated, the certificate icon in the MMC Snap-in list should display a key.

MMC, list of certificates, with indication of associated key
Change the MS CAPI configuration for the local machine account.

In the HSM client console (Dinamocon), enable the Local Machine configuration option.

MS CAPI configuration with local machine account configuration

Note

The connection test will stop working because the configuration is transferred from the logged-in user's account to the local machine account.
In IIS Manager go to the site (under the Sites branch) where the HTTPS protocol will be bound with the certificate. For example, the Default Web Site.

IIS Manager, Default Web Site, Binding option
In the Bindings... option, click Add to create a new binding

IIS Manager, Default Web Site, Bindings
On the Add Site Binding screen, under Type select https and under SSL Certificate select the certificate issued by the CA and imported above.

IIS Manager, Default Web Site, New Binding details

Test the configuration with browser access to the configured website address.

From a browser, check that the configured website address can be accessed via the https. Check that the certificate used is the one configured above.

For this check, it can be useful to leave the CLI console hsmcon.exe (command line) showing HSM activity in real time ( Logs/Follow option) and verifying that the private key is being activated to close the SSL tunnel.

Logs in HSN

2021/02/16 19:45:05 00003F80 00039C37 13D1B59C iispart auth init, c: 41|10.61.53.163 10.61.53.  60:4433 -
2021/02/16 19:45:05 00003F80 00039C38 13D1B59C iispart auth ok, 10.61.53.163, 6|10.61.53.163 10.   61.53.60:4433 -
                                               ^^^^^^^ # (1)!
2021/02/16 19:45:05 00003F80 00039C39 13D1B59C rsa CSP0670045F!F7md3iGOTL34+gRTEo/4okX +CR719IPywZ2+yqVpegc=, c: 41|10.61.53.163 10.61.53.60:4433 iispart
                                               ^^^ ^^^^^^^^^^^ # (2)!
2021/02/16 19:45:05 00003F80 00039C3A 13D1B59C e-conn: 10.61.53.163|10.61.53.163 10.61.53.   60:4433 iispart
2021/02/16 19:45:05 00003F80 00039C3B 000A3309 session thread down [5]|10.61.53.163 10.61.53.   60:4433 iispart

HSM authentication
Using the key in the HSM