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

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

Key and CSR generated in HSM via IIS Manager

1. 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
   

2. 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

3. Open the IISManager screen

   

   IIS Manager

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

   

   IIS Manager, certificate management

5. Use the option Create Certificate Request... option to generate a CSR(Certificate Signing Request).

   

   IIS Manager, certificate creation

6. Fill in the information for the fields that will make up the certificate.

   

   IIS Manager, certificate fields

7. Choose the Crypto Provider of Dinamo and the size of the private key

   

   IIS Manager, provider selection Dinamo

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

   

   IIS Manager, CSR file path

   -----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 the 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 real-time HSM activity (option Logs/Follow) to identify the name/id of the generated private key.

   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
                                                  ^^^^^^^ ^^^^^^^^^^^ ^^^^^^^
   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
   

9. 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.

10. In IIS Manager use the option Complete Certificate Request....

    

    IIS Manager, complete the certificate request process

11. Inform the file of the certificate issued by the CA.

    

    IIS Manager, inform the path of the certificate file received by the CA

12. At the end of the process the certificate should be listed in the IIS Manager to be used in the Sites managed by IIS.

    

    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.

13. (Re)associate the key with the certificate in the CNG Provider Dinamo account on the local machine using hsmutil.exe. This reassociation is necessary for the Local Security Authority Subsystem Service can use the key generated in the HSM.

    Run the utility hsmutil.exe with the parameters below. The values of <id da chave no HSM> e <hash/fingerprint do certificado> must be replaced as explained below.

    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> is the name of the private key generated in the step above and identified. It is also shown in the key list of the chosen HSM partition.

    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
    ^^^^^^^^^^^
    
    Total of objects: 1
    
    Press ENTER key to continue...
    

    O <hash/fingerprint do certificado> can be checked directly on the certificate issued by the CA, using the Windows utility certutil (command line) or by opening the certificate file in the Windows viewer.

    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 CSP0670045F -keyspec cng -certhash fe8c1b7e672edbc7004a177bc4fad5244c91f4b9
    

14. 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.

15. 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

16. In the Bindings... option, click Add to create a new binding

    

    IIS Manager, Default Web Site, Bindings

17. 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

18. 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 may be useful to leave the CLI console hsmcon.exe (command line) showing real-time HSM activity (option Logs/Follow) and checking that the private key is being activated to close the SSL tunnel.

    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 -
                                                   ^^^^^^^
    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
                                                   ^^^ ^^^^^^^^^^^
    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
    

Externally generated key (.pfx, .p12 file)

1. 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

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

   Write down the name of the private key and certificate imported into the 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...
   

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

   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...
   

4. 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.

5. (Re)associate the key with the certificate in the CNG Provider Dinamo account on the local machine using hsmutil.exe. This reassociation is necessary for the Local Security Authority Subsystem Service can use the key generated in the HSM.

   Run the utility hsmutil.exe 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> is the name of the private key imported in the step above and identified.

   O <hash/fingerprint do certificado> can be checked directly on the certificate issued by the CA, using the Windows utility certutil (command line) or by opening the certificate file in the Windows viewer.

   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

6. 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.

7. 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

8. In the Bindings... option, click Add to create a new binding

   

   IIS Manager, Default Web Site, Bindings

9. 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

10. 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 may be useful to leave the CLI console hsmcon.exe (command line) showing real-time HSM activity (option Logs/Follow) and checking that the private key is being activated to close the SSL tunnel.

    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 -
                                                   ^^^^^^^
    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
                                                   ^^^ ^^^^^^^^^^^
    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