Downloads HSM API

Microsoft IIS

Informações Gerais

Este guia de uso integrado com o MS IIS (Microsoft Internet Information Services) foi preparado usando as versões de software e firmware abaixo:

  • SO: Windows Server 2019 (inglês)

  • IIS: 10

  • Firmware do HSM: 5.0.26.0 (ou superior)

  • Cliente do HSM: 4.7.30 (ou superior)

  • Utilitário hsmutil: 4.7.30 (ou superior)

Requisitos

  1. Conectividade com o HSM (porta TCP 4433).

  2. Software client do HSM instalado, (consulte o tópico Windows).

  3. Utilitário hsmutil.exe baixado, (verificar aqui).

  4. Serviço do HSM iniciado.

  5. Conta do Windows com permissão de administração local.

  6. Credenciais da partição do HSM onde será criada ou importada a chave privada.

  7. Pode ser necessário um restart do Windows (para carregar as configurações de local machine).

Chave e CSR gerados no HSM via IIS Manager

  1. Criar uma Crypto Provider da Dinamo do Tipo RSA Channel (tipo 12) usando a seguinte entrada na registry.

    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. Configurar os parâmetros MS CAPI com as credenciais de partição do HSM na console GUI (Dinamocon).

    Configurar endereço IP, nome e senha de uma partição no HSM; e habilitar CNG. A chave privada será gerada nesta partição.

    Nota: manter desmarcada a opção Local Machine Configuration.

  3. Abrir tela de gerência do IIS (IIS Manager)

  4. Na tela Home do IIS Manager abrir a opção de Server Certificates.

  5. Usar a opção Create Certificate Request... para gerar um CSR (Certificate Signing Request).

  6. Preencher as informações dos campos que irão compor o certificado.

  7. Escolher a Crypto Provider da Dinamo e o tamanho da chave privada

  8. Anotar o caminho e o nome do arquivo com o CSR gerado.

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

    Será gerada uma chave privada RSA na partição do HSM. O nome (id) desta chave é definido pelo IIS Manager. Identifique e anote o nome da chave gerada, ele será utilizado mais adiante. Pode ser útil deixar a console CLI hsmcon.exe (linha de comando) mostrando em tempo real a atividade do HSM (opção Logs/Follow) para identificar o nome/id da chave privada gerada.

    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. Levar o CSR até uma Autoridade Certificadora (AC) para a emissão do certificado.

    Este passo é externo e depende completamente do procedimento da AC escolhida. Anotar o caminho e nome do certificado (arquivo *.cer) recebido da AC.

  10. No IIS Manager use a opção Complete Certificate Request....

  11. Informar o arquivo do certificado emitido pela AC.

  12. No final do processo o certificado deverá estar listado no IIS Manager para ser utilizado nos Sites gerenciados pelo IIS.

    Nota: O IIS Manager vai fazer a associação entre chave privada e certificado o Provider CSP na conta do usuário. No passo esta associação será refeita para o Provider CNG e na conta da máquina local (local machine).

  13. (Re)fazer associação da chave com o certificado no Provider CNG Dinamo na conta da máquina local utilizando o hsmutil.exe. Esta reassociação é necessário para que o Local Security Authority Subsystem Service do Windows possa utilizar a chave gerada no 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.

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

    Exemplo de usdo comando de associação:

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

  14. Alterar a configuração da MS CAPI para a conta de máquina local.

    Na console cliente (Dinamocon) do HSM habilite a opção Local Machine configuration.

    Note: o teste de conexão vai deixar de funcionar pois a configuração é transferida da conta do usuário logado para a conta de máquina local.

  15. No IIS Manager ir até o site (abaixo do ramo Sites) onde será feito o binding do protocolo HTTPS com o certificado. Por exemplo o Default Web Site.

  16. Na opção Bindings... clique em Add para criar um novo binding

  17. Na tela de Add Site Binding em Type selecione https e em SSL Certificate selecione o certificado emitido pela AC e importado acima.

  18. Testar a configuração com acesso via navegador ao endereço do site configurado.

    A partir de um navegador verifique se o endereço do site configurado pode ser acessado via protocolo https. Confira se o certificado utilizado foi o configurado acima.

    Nesta verificação pode ser útil deixar a console CLI hsmcon.exe (linha de comando) mostrando em tempo real a atividade do HSM (opção Logs/Follow) e verificando que a chave privada está sendo ativada para o fechamento do túnel SSL.

    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

Chave gerada externamente (arquivo .pfx, .p12)

  1. Configurar os parâmetros MS CAPI com as credenciais de partição do HSM na console GUI (Dinamocon).

    Configurar endereço IP, nome e senha de uma partição no HSM; e habilitar CNG. A chave privada será gerada nesta partição.

    Nota: manter desmarcada a opção Local Machine Configuration.

  2. Importar o arquivo .pfx no HSM com a console hsmcon.exe (linha de comando).

    Anotar o nome da chave privada e do certificado importados no 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. Exportar o certificado do HSM para um arquivo (.cer) com a console hsmcon.exe (linha de comando).

    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. Importar o certificado (.cer) para o repositório do Computador Local usando o Snap-in para Certificates (Local Machine) do Microsoft Management Console (MMC) do Windows no computador local.

    Nota: importar o arquivo .cer (certificado), não o arquivo .pfx (chave privada).

    Nota: O ícone do certificado na lista não mostra uma chave, pois apenas o certificado foi importado.

  5. (Re)fazer associação da chave com o certificado no Provider CNG Dinamo na conta da máquina local utilizando o hsmutil.exe. Esta reassociação é necessário para que o Local Security Authority Subsystem Service do Windows possa utilizar a chave gerada no HSM.

    Executar o utilitário hsmutil.exe com os parâmetros abaixo.

    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

    Exemplo de usdo comando de associação:

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

    Após a associação com sucesso entre certificado e chave privada o ícone do certificado na lista do Snap-in do MMC deve exibir uma chave.

  6. Alterar a configuração da MS CAPI para a conta de máquina local.

    Na console cliente (Dinamocon) do HSM habilite a opção Local Machine configuration.

    Note: o teste de conexão vai deixar de funcionar pois a configuração é transferida da conta do usuário logado para a conta de máquina local.

  7. No IIS Manager ir até o site (abaixo do ramo Sites) onde será feito o binding do protocolo HTTPS com o certificado. Por exemplo o Default Web Site.

  8. Na opção Bindings... clique em Add para criar um novo binding

  9. Na tela de Add Site Binding em Type selecione https e em SSL Certificate selecione o certificado emitido pela AC e importado acima.

  10. Testar a configuração com acesso via navegador ao endereço do site configurado.

    A partir de um navegador verifique se o endereço do site configurado pode ser acessado via protocolo https. Confira se o certificado utilizado foi o configurado acima.

    Nesta verificação pode ser útil deixar a console CLI hsmcon.exe (linha de comando) mostrando em tempo real a atividade do HSM (opção Logs/Follow) e verificando que a chave privada está sendo ativada para o fechamento do túnel SSL.

    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
AnteriorJar SignerPróximoMicrosoft CA

Atualizado