Usar a Common Expression Language

Nesta página, descrevemos como usar a Common Expression Language (CEL) com políticas de emissão de certificados, modelos de certificados e condições do Identity and Access Management (IAM) no pool de ACs.

Visão geral

A Common Expression Language (CEL) é uma linguagem de código aberto sem completude de Turing que implementa semântica comum para avaliação de expressões. Certificate Authority Service oferece suporte à CEL para aplicar vários controles de política para emissão de certificados.

Há dois dialetos CEL que podem ser usados com o serviço de AC:

  • Um dialeto flexível que pode ser usado nas políticas de emissão de certificados e nos modelos de certificados de um pool de ACs.
  • Um dialeto mais limitado que pode ser usado nas condições do IAM.

Dialeto CEL para políticas de emissão de certificados e modelos de certificados

Ao criar um pool de ACs ou um modelo de certificado, é possível especificar uma expressão CEL como parte das restrições de identidade do certificado. A expressão CEL permite validar os campos "Assunto" e "Nome alternativo do assunto" (SAN, na sigla em inglês).

Para mais informações sobre políticas de emissão, consulte Adicionar políticas de emissão de certificados.

Para mais informações sobre modelos de certificados, consulte Visão geral dos controles de política.

O dialeto CEL para as restrições de identidade de pools de ACs e modelos de certificados expõe as seguintes variáveis para acessar e validar os campos de assunto e SAN:

  • Assunto: subject
  • SAN: subject_alt_names

Assunto

É possível validar todos os campos no nome de domínio do assunto de um certificado (incluindo o nome comum), conforme especificado na solicitação de certificado usando uma variável do tipo Subject e o nome subject.

Subject é uma estrutura que contém os seguintes campos:

Tipo Nome
String common_name
String country_code
String organization
String organizational_unit
String locality
String province
String street_address
String postal_code

Nomes alternativos do assunto (SANs)

É possível validar todos os SANs especificados na solicitação de certificado usando a variável subject_alt_names. A variável subject_alt_names contém uma lista de estruturas SAN, em que cada SAN é do tipo SubjectAltName.

SubjectAltName é uma estrutura que contém os seguintes campos:

Tipo Nome
String valor
[]Int32 oid
Enum tipo

É possível usar os seguintes valores para o tipo SubjectAltName:

  • DNS
  • URI
  • EMAIL
  • IP_ADDRESS
  • CUSTOM

A variável subject_alt_names contém uma lista com todos os SANs solicitados.

É possível usar as seguintes macros em SANs:

  • subject_alt_names.all(san, predicate)
  • subject_alt_names.exists(san, predicate)
  • subject_alt_names.exists_one(san, predicate)
  • subject_alt_names.filter(san, predicate)

Para mais informações sobre macros, consulte Definição de linguagem: macros.

Exemplos de expressões

Como garantir um nome comum específico e um conjunto de países

subject.common_name == "google.com" && (subject.country_code == "US" || subject.country_code == "IR")

Como garantir que todos os nomes DNS terminem com uma string personalizada

subject_alt_names.all(san, san.type == DNS && san.value.endsWith(".test.com"))

Como garantir que todos os SANs sejam do tipo DNS ou EMAIL

subject_alt_names.all(san, san.type == DNS || san.type == EMAIL )

Como garantir apenas um SAN personalizado com um OID específico

subject_alt_names.size() == 1 && subject_alt_names[0].oid == [1, 2, 3, 5, 17]

Como garantir que os SANs personalizados sejam apenas um conjunto de OIDs

subject_alt_names.all(san, san.oid == [1, 2, 4, 5, 55] || san.oid == [1, 2, 4, 5, 54])

Dialeto CEL para políticas do IAM

Use as condições do IAM para sujeitar as vinculações de papéis do IAM a uma expressão condicional. Se a condição for avaliada como true, a vinculação de papel do IAM será eficaz. Caso contrário, ela será ignorada. O serviço de AC permite adicionar vinculações condicionais do IAM a um pool de ACs.

A condição do IAM é uma expressão CEL que referencia um conjunto de atributos contextuais sobre a solicitação e avalia como um booleano. Os usuários definem condições nas vinculações de papéis em uma política do IAM, que é armazenada pelo IAM e avaliada para verificar se a operação que está prestes a ser realizada é permitida.

Para mais informações sobre as condições do IAM, consulte Visão geral das condições do IAM.

Os atributos a seguir são expostos durante a avaliação CEL das condições do IAM:

  • privateca.googleapis.com/subject

    O privateca.googleapis.com/subject pode ser acessado como api.getAttribute('privateca.googleapis.com/subject', {}).

Tipo Descrição
map{string, string} Esse campo contém o nome distinto do assunto (incluindo o nome comum), conforme especificado na solicitação de certificado recebida.

Exemplo

{
 'common_name': 'Foobar',
 'organization': 'Example LLC'
 'country_code' :'US'
 'organizational_unit':'Foobar'
 'locality':'Mountain View'
 'Province':'California'
 'street_address':'Foobar 22'
 'postal_code':55555
}

  • privateca.googleapis.com/subject_alt_names

    O privateca.googleapis.com/subject_alt_names pode ser acessado como api.getAttribute('privateca.googleapis.com/subject_alt_names', []).

Tipo Descrição
list{string} Esse campo contém todos os SANs solicitados, conforme especificado na solicitação de certificado recebida. Cada um dos SANs solicitados é prefixado com o tipo. Os SANs com tipos desconhecidos são prefixados com o OID serializado do tipo.

Exemplo

{
 'dns:foo.bar.com',
 'uri:spiffe://foo/ns/bar/sa/baz'
 'email:foo@bar.com'
 'ip:169.169.254.254'
 'custom:1.2.3.4.5.6.3:foobar'
}

  • privateca.googleapis.com/template

    O privateca.googleapis.com/template pode ser acessado como api.getAttribute('privateca.googleapis.com/template', '').

Tipo Descrição
String O modelo de certificado usado, se houver. O formato é {project_id}/-/{template_id}.

Exemplo: my-project-pki/-/workload_tls

A sintaxe do modelo usa {project_id}/-/{template_id} em vez do nome completo do recurso padrão projects/{project_id}/locations/{location}/certificateTemplates/{template_id} porque os modelos de certificado precisam residir no mesmo local que o pool de ACs. Nesse formato, o hífen (-) atua como um curinga de local, o que mantém as condições CEL concisas, legíveis e independentes do local.

O nome do modelo fornecido na condição do IAM precisa corresponder ao nome do modelo na solicitação de certificado. Portanto, se você estiver fornecendo um ID do projeto no atributo privateca.googleapis.com/template da expressão CEL, também será necessário fornecer um ID do projeto ao solicitar o certificado. Se você fornecer um número do projeto na expressão CEL, também será necessário fornecer um número do projeto na solicitação de certificado.

Exemplos de expressões

Como garantir que todos os assuntos tenham a organização definida como "Exemplo" e o código do país definido como US ou UK

api.getAttribute('privateca.googleapis.com/subject', {})['organization'] == 'Example' &&
api.getAttribute('privateca.googleapis.com/subject', {})['country_code'] in ['US', 'UK']

Como garantir que a solicitação de certificado inclua apenas os SANs DNS fornecidos

api.getAttribute('privateca.googleapis.com/subject_alt_names', [])
        .hasOnly(['dns:sample1.prod.example.com', 'dns:sample2.prod.example.com'])

Como garantir que todos os certificados usem um modelo específico

api.getAttribute('privateca.googleapis.com/template', '') == 'my-project-pki/-/leaf-server-tls'

A seguir