Criar um modelo de certificado

Esta página descreve os atributos de um modelo de certificado e explica como você para criar um modelo de certificado.

Visão geral dos modelos de certificado

O serviço de autoridade certificadora fornece modelos reutilizáveis e parametrizados que podem ser usados em cenários comuns de emissão de certificados. Um modelo de certificado representa um esquema de emissão de certificados relativamente estático e bem definido dentro de uma organização. O recurso CertificateTemplate inclui o seguinte.

1. Uma expressão da Common Expression Language (CEL) que é avaliada em relação ao assunto e aos SANs solicitados em todas as solicitações de certificado que usam o modelo. Para mais informações sobre o uso da CEL, consulte Como usar a CEL.
2. Uma lista de permissões que especifica se o assunto ou o nome alternativo do assunto pode ser copiado da solicitação do usuário final para o certificado emitido.
3. Uma lista de permissões opcional que especifica quais extensões X.509, se houver, podem ser copiadas da solicitação do usuário final para o certificado emitido.
4. Um conjunto opcional de valores de extensão X.509 que são adicionados a todos os certificados emitidos que usam o modelo.

Um modelo de certificado pode se tornar um framework completo de emissão de certificados. Para mais detalhes, consulte a definição completa da mensagem CertificateTemplate.

Valores predefinidos em um modelo de certificado

Os valores predefinidos em um modelo de certificado são adicionados a todos os certificados que usam o modelo. Eles permitem criar cenários comuns de emissão de certificados, como mTLS ou assinatura de código. Os valores incluem o seguinte:

• Usos de chave: especifica o uso de chave base para um certificado, de acordo com a seção 4.2.1.12 do RFC 5280 (em inglês).
• Usos de chave estendidos: especifica o uso de chave estendido para um certificado de acordo com a seção 4.2.1.3 do RFC 5280.
• Se o certificado for uma AC: especifica se o certificado pode emitir certificados adicionais ou se é um certificado de entidade final.
• Tamanho máximo do caminho do emissor: no caso de uma AC, especifica o número máximo de ACs que podem ser encadeados a esse certificado de AC. Se o tamanho máximo do caminho do emissor estiver definido como 0, a AC só poderá emitir certificados de entidade final. Se ele for definido como 1, a cadeia abaixo desse certificado de CA poderá incluir apenas uma CA subordinada. Se um valor não for declarado, o número de ACs subordinados na cadeia abaixo dessa AC será ilimitado.
• Servidores OCSP do AIA: refere-se aos servidores OCSP na extensão de acesso a informações de autoridade (AIA) de um certificado, conforme descrito na seção 4.2.2.1 do RFC 5280.
• Extensões X.509 adicionais: descreve extensões X.509 personalizadas.

O exemplo de código a seguir menciona todos os campos predefinidos em um modelo de certificado:

keyUsage:
  baseKeyUsage:
    digitalSignature: true
    keyEncipherment: true
    contentCommitment: false
    dataEncipherment: false
    keyAgreement: false
    certSign: false
    crlSign: false
    encipherOnly: false
    decipherOnly: false
  extendedKeyUsage:
    serverAuth: true
    clientAuth: false
    codeSigning: false
    emailProtection: false
    timeStamping: false
    ocspSigning: false
caOptions:
  isCa: true
  maxIssuerPathLength: 1
policyIds:
- objectIdPath:
  - 1
  - 2
  - 3
additionalExtensions:
- objectId:
    objectIdPath:
    - 1
    - 2
    - 3
  critical: false
  value: "base64 encoded extension value"

Os valores não especificados no YAML são omitidos ou definidos como padrão como false.

As extensões a seguir serão omitidas se um valor não for especificado:

• keyUsage
• policyIds
• additionalExtensions
• Campo maxIssuerPathLength na extensão caOptions

As extensões a seguir são definidas como false por padrão se um valor não for especificado:

• Campo isCa na extensão caOptions

Criar um modelo de certificado

Para criar um modelo de certificado, use o seguinte comando gcloud:

gcloud

gcloud privateca templates create TEMPLATE_ID \
  --copy-subject \
  --copy-sans \
  --identity-cel-expression <expr> \
  --predefined-values-file FILE_PATH \
  --copy-all-requested-extensions \
  --copy-extensions-by-oid <1.2.3.4,5.6.7.8> \
  --copy-known-extensions <ext1,ext2>

Substitua:

• TEMPLATE_ID: o identificador exclusivo do modelo de certificado.
• FILE_PATH: o arquivo YAML que descreve os valores X.509 definidos pelo modelo de certificado.

A flag --copy-sans permite que a extensão do nome alternativo do assunto (SAN) da solicitação de certificado seja copiada para o certificado assinado. Como alternativa, é possível especificar --no-copy-sans para descartar qualquer SAN especificado pelo autor da chamada da solicitação de certificado.

A flag --copy-subject permite que o assunto da solicitação de certificado seja copiado no certificado assinado. Como alternativa, especifique --no-copy-subject para remover os sujeitos especificados pelo autor da chamada da solicitação de certificado.

Observação: se você quiser garantir que um modelo precise ser usado com identidade reflexão, especifique as sinalizações --no-copy-subject e --no-copy-sans juntas. Para mais informações sobre a reflexão de identidade, consulte Reflexão de identidade.

A flag --identity-cel-expression usa uma expressão CEL que é avaliada em relação ao assunto e ao nome alternativo do assunto do certificado antes de ser emitida e retorna um booleano que indica se a solicitação deve ser permitida. Para saber como usar uma expressão da linguagem Common Expression Language (CEL) em um modelo de certificado, consulte Como usar a CEL em modelos de certificado.

A flag --predefined-values-file especifica o caminho para um arquivo YAML que descreve os valores X.509 predefinidos definidos por esse modelo. As extensões fornecidas são copiadas para todas as solicitações de certificado que usam esse modelo e têm precedência sobre todas as extensões permitidas na solicitação de certificado. Se você atualizar qualquer parte dos valores X.509 predefinidos, a atualização vai substituir o conjunto inteiro dos valores X.509 predefinidos.

Se a sinalização --copy-all-requested-extensions estiver definida, todas as extensões especificadas na solicitação de certificado serão copiadas no certificado assinado. Como alternativa, a flag --copy-extensions-by-oid pode ser usada para copiar OIDs específicos da solicitação de certificado para o certificado assinado, e a flag --copy-known-extensions pode ser usada para copiar extensões da solicitação de certificado para o certificado assinado. Precisa ser uma destas opções: base-key-usage, extended-key-usage, ca-options, policy-ids ou aia-ocsp-servers.

Observação: a flag --copy-all-requested-extensions da tag é mutuamente exclusiva das flags --copy-known-extensions e --copy-extensions-by-oid.

Remova a sinalização --copy-all-requested-extensions para ignorar todas as extensões X.509 na solicitação de certificado, mas manter os valores predefinidos definidos neste modelo.

Observação :se você excluir recursos como pools de ACs, autoridades certificadoras e modelos de certificado, não será possível criar um novo recurso desse tipo com o mesmo nome no mesmo projeto e local.

Criar um modelo de certificado para cenários comuns

Esta seção fornece comandos gcloud para criar um modelo de certificado para casos de uso comuns.

Certificados TLS do servidor DNS para qualquer domínio

Para criar um modelo de certificado para emitir certificados TLS do servidor que permitam qualquer domínio, siga estas instruções:

1. Crie um arquivo com o nome leaf_server_tls_values.yaml e adicione a ele a seguinte configuração TLS do servidor de entidade final:

   leaf_server_tls_values.yaml

   keyUsage:
     baseKeyUsage:
       digitalSignature: true
       keyEncipherment: true
     extendedKeyUsage:
       serverAuth: true
   caOptions:
     isCa: false
   

2. Para permitir apenas certificados com SANs do tipo DNS, execute o seguinte comando gcloud:

   gcloud

   gcloud privateca templates create server-tls \
     --predefined-values-file leaf_server_tls_values.yaml \
     --copy-sans --no-copy-subject \
     --identity-cel-expression "subject_alt_names.all(san, san.type == DNS)"
   

   Para mais informações sobre o comando gcloud privateca templates create, consulte gcloud privateca models create.

Certificados TLS do servidor DNS com apenas domínios de teste

Para criar um modelo de certificado para emitir certificados TLS do servidor com SANs DNS limitados a domínios de teste, use o seguinte comando gcloud:

gcloud

gcloud privateca templates create server-tls \
  --predefined-values-file leaf_server_tls_values.yaml \
  --copy-sans --no-copy-subject \
  --identity-cel-expression "subject_alt_names.all(san, san.type == DNS && san.value.endsWith('.test.example.com'))"

O conteúdo do arquivo leaf_server_tls_values.yaml precisa ser o mesmo do exemplo anterior.

Para mais informações sobre o uso de expressões CEL para garantir que os nomes de DNS comecem ou terminem com uma string específica, consulte Exemplos de expressões CEL.

Certificados de identidade da carga de trabalho

Para criar um modelo de certificado e emitir certificados TLS mútuos (mTLS), use as seguintes instruções:

1. Crie um arquivo com o nome leaf_mtls_values.yaml e adicione a seguinte configuração TLS mútua de entidade final a ele.

   leaf_mtls_values.yaml

   keyUsage:
     baseKeyUsage:
       digitalSignature: true
       keyEncipherment: true
     extendedKeyUsage:
       serverAuth: true
       clientAuth: true
   caOptions:
     isCa: false
   

2. Para permitir apenas certificados com URI SANs SPIFFE, use o seguinte comando gcloud:

   gcloud

   gcloud privateca templates create workload-spiffe \
     --predefined-values-file leaf_mtls_values.yaml \
     --copy-sans --no-copy-subject \
     --identity-cel-expression "subject_alt_names.all(san, san.type == URI && san.value.startsWith('spiffe://'))"
   

   Para mais informações sobre o comando gcloud privateca templates create, consulte gcloud privateca models create.

Para mais informações sobre como usar expressões CEL para garantir que os nomes DNS comecem ou terminem com uma string específica, consulte Expressões de exemplo de CEL (em inglês).

Conceder acesso ao modelo de certificado

Você pode usar um modelo de certificado se tiver a função de usuário do modelo de certificado de serviço de AC (roles/privateca.templateUser). Recomendamos que os autores de um modelo de certificado atribuam a função de usuário do modelo de certificado de serviço de CA aos membros da organização que possam usar esse modelo.

Para conceder o papel de usuário do modelo de certificado de serviço de CA (roles/privateca.templateUser) a todos no domínio example.com, use o seguinte comando gcloud:

gcloud

gcloud privateca templates add-iam-policy-binding TEMPLATE_ID \
  --member "domain:example.com" \
  --role "roles/privateca.templateUser"

Substitua:

• TEMPLATE_ID: o identificador exclusivo do modelo de certificado.

Para mais informações sobre o comando gcloud privateca templates add-iam-policy-binding, consulte gcloud privateca models add-iam-policy-binding.

Para mais informações sobre papéis do IAM para serviço de AC, e as permissões associadas a ela, consulte Controle de acesso com o IAM.

A seguir

• Saiba mais sobre a Common Expression Language.
• Aprenda a usar a Linguagem de expressão comum.
• Saiba mais sobre os perfis de certificado.