Usar Jsign e PKCS#11 para assinar artefatos do Windows

Este guia fornece instruções para criar uma chave do Cloud HSM para assinatura Microsoft Authenticode usando PKCS#11 e Jsign.

Casos de uso

O fluxo de trabalho descrito neste documento ajuda a atender às seguintes necessidades de segurança empresarial:

  • Assine o firmware com uma chave privada protegida por um HSM FIPS140-2 de nível 3.
  • Assinar artefatos do Windows sem precisar usar o signtool.

Antes de começar

Para concluir este tutorial, você precisa do seguinte:

  • Uma máquina Windows com os artefatos que você quer assinar. Verifique se o Java está instalado nesta máquina.

  • Cloud Shell ou sua própria máquina Linux, para gerar uma solicitação de assinatura de certificado ou um certificado. Nessa máquina, conclua a configuração documentada em Configuração do OpenSSL.

Executar gcloud auth application-default login, se ainda não tiver feito isso.

Na máquina Windows, faça o download do arquivo JAR da versão mais recente do Jsign usando o seguinte comando do PowerShell:

wget https://github.com/ebourg/jsign/releases/download/JSIGN.VERSION/jsign-JSIGN.VERSION.jar -O jsign.jar

Configuração

Criar uma chave de assinatura hospedada no Cloud KMS

Usando o Cloud Shell ou sua própria máquina, crie um keyring do Cloud KMS no projeto Google Cloud usando o seguinte comando:

gcloud kms keyrings create "KEY_RING" --location "LOCATION"

Em seguida, crie uma chave de assinatura de hardware EC-P256-SHA256 do Cloud KMS no projeto Google Cloud , no keyring que você acabou de criar:

gcloud kms keys create "KEY_NAME" --keyring "KEY_RING" \
  --project "PROJECT_ID" --location "LOCATION" \
  --purpose "asymmetric-signing" --default-algorithm "ec-sign-p256-sha256" \
  --protection-level "hsm"

Fazer o download do atestado do HSM

Um atestado de HSM é a prova de que sua chave está em um HSM. Essa comprovação pode ser necessária para que sua autoridade certificadora (AC) emita um certificado de validação estendida (EV).

Para fazer o download do atestado do HSM associado à chave do Cloud KMS, conclua as etapas a seguir:

  1. No console do Google Cloud, acesse a página Gerenciamento de chaves.

    Vá para Gerenciamento de chaves

  2. Selecione o keyring que contém a chave que você quer atestar e selecione a chave.

  3. Clique em Mais na versão da chave que você quer atestar e clique em Verificar atestado.

  4. Na caixa de diálogo Verificar atestado, clique em Fazer o download do pacote de atestado. Isso faz o download de um arquivo ZIP contendo as cadeias de atestado e de certificado.

Consulte Analisar o atestado para conferir instruções completas sobre como verificar o atestado transferido por download.

Criar um certificado autoassinado com o OpenSSL

Esta etapa é opcional, mas ajuda você a se familiarizar com as etapas posteriores antes de passar pelo processo e pela despesa de compra de um certificado assinado por uma autoridade certificadora.

Usando o Cloud Shell ou sua própria máquina, gere um certificado autoassinado com a chave de assinatura hospedada no Cloud KMS. É possível usar o OpenSSL para usar um URI PKCS #11 em vez de um caminho de arquivo e identificar a chave pelo rótulo. Na biblioteca PKCS #11 do Cloud KMS, o rótulo da chave é equivalente ao nome da CryptoKey.

openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=KEY_NAME > ca.cert

Se esse comando falhar, é possível que PKCS11_MODULE_PATH tenha sido definido incorretamente ou que você não tenha as permissões corretas para usar a chave de assinatura do Cloud KMS.

Agora você terá um certificado como este:

-----BEGIN CERTIFICATE-----
...
...
...
-----END CERTIFICATE-----

Copie o certificado para a máquina Windows para que ele possa ser usado com o Jsign para assinar seus artefatos.

Criar uma nova solicitação de assinatura de certificado

É possível gerar uma solicitação de assinatura de certificado (CSR) para uma chave de assinatura do Cloud HSM. Siga estas etapas se a autoridade de certificação exigir um CSR para gerar um novo certificado para assinatura de código.

Usando o Cloud Shell ou sua própria máquina, execute o seguinte comando:

openssl req -new -subj '/CN=CERTIFICATE_NAME/' DIGEST_FLAG \
  -engine pkcs11 -keyform engine \
  -key pkcs11:id=KEY_ID > REQUEST_NAME.csr

Substitua:

  • CERTIFICATE_NAME: um nome para o certificado que você quer gerar.
  • DIGEST_FLAG: uma flag que indica o tipo de resumo. Use -sha256, -sha384 ou -sha512, dependendo do algoritmo da chave.
  • KEY_ID: o ID de recurso totalmente qualificado de uma versão de chave de assinatura assimétrica, por exemplo, projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/1.
  • REQUEST_NAME: um nome para a solicitação de assinatura de certificado.

Use as opções -sigopt corretas para o tipo de chave que você está usando.

Agora que você tem a CSR, pode enviá-la à autoridade certificadora (AC) para receber o certificado de assinatura. Use o certificado fornecido pela AC na próxima seção.

Assinar um artefato com a Jsign

Agora que você criou um certificado (autoassinado ou obtido da Autoridade Certificadora) e o copiou para sua máquina Windows, ele pode ser usado para assinar um artefato do Windows.

Para conferir uma lista de formatos de arquivo aceitos, execute o comando jsign --help.

Use o Jsign para assinar os artefatos usando sua chave do Cloud KMS e seu certificado.

java -jar PATH_TO_JSIGN.JAR --storetype GOOGLECLOUD \
  --storepass $(gcloud auth application-default print-access-token) \
  --keystore projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING \
  --alias KEY_NAME \
  --certfile PATH_TO_CA.CERT
  PATH_TO_ARTIFACT_TO_SIGN

Substitua:

  • PATH_TO_JSIGN.JAR: o caminho para jsign.jar.
  • PATH_TO_CA.CERT: o caminho para o certificado ca.cert.
  • PATH_TO_ARTIFACT_TO_SIGN: o caminho para o artefato que você quer assinar.

Para uma explicação detalhada de cada opção de comando, consulte a documentação oficial do Jsign (link em inglês).