Acme Certificate

7 min

Resumo

Crie e renove certificados SSL / TLS com uma CA que suporte o protocolo ACME, como Let’s Encrypt ou Buypass.
A implementação atual suporta challenges http-01, dns-01 e tls-alpn-01.
Você deve cumprir as etapas exigidas para o challenge escolhido por todos os meios necessários.
- Para http-01, isso significa criar o arquivo de desafio necessário no servidor da Web de destino.
- Para dns-01, o registro dns necessário deve ser criado.
- Para tls-alpn-01, o certificado necessário deve ser criado e servido.
O módulo inclui suporte experimental para identificadores de IP de acordo com o RFC 8738.

Parâmetros

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
account_email	string		O endereço de e-mail associado a esta conta. Ele será usado para avisos de expiração de certificado. Observe que quando modify_account não está definido como no e você também usou o módulo acme_account para especificar mais de um contato para sua conta, este módulo irá atualizar sua conta e restringi-la ao (no máximo um) endereço de e-mail de contato especificado aqui.
agreement	string		URI para um documento de termos de serviço com o qual você concorda ao usar o serviço ACME v1 em acme_directory. O padrão é obtido por último a partir do URL acme_directory. Esta opção só será usada quando acme_version for 1.
chain_dest	string		Se especificado, o certificado intermediário será gravado neste arquivo.
challenge	string	Escolhas: - http-01 (Padrão) - dns-01 - tls-alpn-01	Challenge a ser executado.
csr	string		Arquivo contendo o CSR para o novo certificado. O CSR pode conter vários nomes alternativos, mas cada um levará a um challenge individual que deve ser cumprido para que o CSR seja assinado.
csr_content	string		Conteúdo do CSR para o novo certificado. O CSR pode conter vários nomes alternativos de assunto, mas cada um levará a um desafio individual que deve ser cumprido para que o CSR seja assinado. Nota: a chave privada usada para criar o CSR não deve ser a chave da conta. Esta é uma má ideia do ponto de vista da segurança e a CA não deve aceitar o CSR. O servidor ACME deve retornar um erro neste caso.
data	dict		Os dados para validar os desafios em andamento. O valor que deve ser usado aqui será fornecido por um uso anterior deste módulo. Veja os exemplos para mais detalhes. Observe que para ACME v2, apenas a entrada de dados order_uri será usada. Para ACME v1, os dados não devem estar vazios para indicar que o segundo estágio está ativo; todos os dados necessários serão retirados do CSR.
deactivate_authzs	bool	Escolhas: - False (Padrão) - True	Desative os objetos de autenticação (authz) após emitir um certificado ou quando a emissão do certificado falhar. Os objetos de autenticação são vinculados a uma chave de conta e permanecem válidos por um determinado período de tempo, e podem ser usados para emitir certificados sem a necessidade de reautenticar o domínio.
dest	string		O arquivo de destino do certificado. Obrigatório se fullchain_dest não for especificado.
force	bool	Escolhas: - False (Padrão) - True	Força a execução do challenge e validação, mesmo se um certificado existente ainda for válido por mais do valor especificado em remaining_days. Isso é especialmente útil ao ter um CSR atualizado, por exemplo, com domínios adicionais para os quais um novo certificado é desejado.
fullchain_dest	string		O arquivo de destino para a cadeia completa (ou seja, certificado seguido pela cadeia de certificados intermediários). Obrigatório se dest não for especificado.
modify_account	bool	Escolhas: - False - True (Padrão)	Booleano que indica se o módulo deve criar a conta, se necessário, e atualizar seus dados de contato. Defina como no se desejar usar o módulo acme_account para gerenciar sua conta e evitar a criação acidental de uma nova conta usando uma chave antiga se você alterou a chave da conta com acme_account. Se definido como no, terms_agreed e account_email são ignorados.
remaining_days	inteiro	Padrão: 10	O número de dias que o certificado deve ter deixado de ser válido. Se cert_days < restante_days, ele será renovado. Se o certificado não for renovado, os valores de retorno do módulo não incluirão challenge_data. Para garantir que o certificado seja renovado em qualquer caso, você pode usar a opção forçar.
retrieve_all_alternates	bool	Escolhas: - False (Padrão) - True	Quando definido como True, recuperará todas as cadeias de confiança alternativas oferecidas pela ACME CA. Eles não serão gravados no disco, mas serão retornados junto com a cadeia principal como all_chains. Consulte a documentação do valor de retorno all_chains para obter detalhes.
select_chain	list		Permite especificar os critérios pelos quais uma cadeia de confiança (alternativa) pode ser selecionada. A lista de critérios será processada um a um até que seja encontrada uma cadeia que corresponda a um critério. Se tal cadeia for encontrada, ela será usada pelo módulo em vez da cadeia padrão. Se um critério corresponder a várias cadeias, a primeira correspondência será retornada. A ordem é determinada pela ordem dos cabeçalhos do Link retornados pelo servidor ACME e pode não ser determinística. Cada critério pode consistir em várias condições diferentes, como emissor e assunto. Para que o critério corresponda a uma cadeia, todas as condições devem se aplicar ao mesmo certificado na cadeia. Esta opção só pode ser usada com o backend de criptografia.
select_crypto_backend	string		Determina qual back-end criptográfico usar. A escolha padrão é auto, que tenta usar criptografia, se disponível, e volta para o openssl. Se definido como openssl, tentará usar o binário openssl. Se definido como criptografia, tentará usar a biblioteca de criptografia.
terms_agreed	bool	Escolhas: - False (Padrão) - True	Booleano que indica se você concorda com o documento de termos de serviço. Alguns servidores ACME podem exigir que a opção seja True. Esta opção só será usada quando acme_version não for 1.

Subcampos da opção select_chain

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
authority_key_identifier	string		Verifica a extensão AuthorityKeyIdentifier. Este é um identificador baseado na chave privada do emissor do certificado intermediário. O identificador deve ter o formato C4: A7: B1: A4: 7B: 2C: 71: FA: DB: E1: 4B: 90: 75: FF: C4: 15: 60: 85: 89: 10.
issuer	dictionary		Permite especificar partes do emissor de um certificado na cadeia deve ter que ser selecionado. Se o emissor estiver vazio, qualquer certificado corresponderá.
subject	dictionary		Permite especificar partes do assunto de um certificado na cadeia deve ter que ser selecionado. Se o assunto estiver vazio, qualquer certificado corresponderá.
subject_key_identifier	string		Verifica a extensão SubjectKeyIdentifier. Este é um identificador baseado na chave privada do certificado intermediário.
test_certificates	string	Escolhas: - first - last - all (default)	Determina quais certificados da cadeia serão testados. all testa todos os certificados da cadeia (excluindo a folha, que é idêntica em todas as cadeias). primeiro testa apenas o primeiro certificado da cadeia, ou seja, aquele que assinou a folha. last testa apenas o último certificado da cadeia, ou seja, o que está mais longe da folha. Seu emissor é o certificado raiz desta cadeia.

Exemplos

- name: Crie um desafio para sample.com usando uma chave de conta de uma variável.
  acme_certificate:
    account_key_content: "{{ account_private_key }}"
    csr: /etc/pki/cert/csr/sample.com.csr
    dest: /etc/httpd/ssl/sample.com.crt
  register: sample_com_challenge
# Primeira etapa alternativa:
- name: Create a challenge for sample.com using a account key from hashi vault.
  acme_certificate:
    account_key_content: "{{ lookup('hashi_vault', 'secret=secret/account_private_key:value') }}"
    csr: /etc/pki/cert/csr/sample.com.csr
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
  register: sample_com_challenge

# Primeira etapa alternativa:
- name: Create a challenge for sample.com using a account key file.
  acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
    dest: /etc/httpd/ssl/sample.com.crt
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
  register: sample_com_challenge

tasks:
  - name: Deixe o desafio ser validado e recupere o cert e o certificado intermediário
    acme_certificate:
      account_key_src: /etc/pki/cert/private/account.key
      account_email: [email protected]
      csr: /etc/pki/cert/csr/sample.com.csr
      dest: /etc/httpd/ssl/sample.com.crt
      fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
      chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
      challenge: dns-01
      acme_directory: https://acme-v01.api.letsencrypt.org/directory
      acme_version: 1
      remaining_days: 60
    register: sample_com_challenge

### Exemplo com desafio de DNS contra servidor ACME de produção ###

- name: Crie um desafio para sample.com usando um arquivo de chave de conta.
  acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    account_email: [email protected]
    src: /etc/pki/cert/csr/sample.com.csr
    cert: /etc/httpd/ssl/sample.com.crt
    challenge: dns-01
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    # Renew if the certificate is at least 30 days old
    remaining_days: 60
  register: sample_com_challenge

- name: Deixe o desafio ser validado e recupere o cert e o certificado intermediário
  acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    account_email: [email protected]
    src: /etc/pki/cert/csr/sample.com.csr
    cert: /etc/httpd/ssl/sample.com.crt
    fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
    chain: /etc/httpd/ssl/sample.com-intermediate.crt
    challenge: dns-01
    acme_directory: https://acme-v01.api.letsencrypt.org/directory
    remaining_days: 60
    data: "{{ sample_com_challenge }}"
  when: sample_com_challenge is changed

# Segunda etapa alternativa:
- name: Deixe o desafio ser validado e recupere o cert e o certificado intermediário
  acme_certificate:
    account_key_src: /etc/pki/cert/private/account.key
    account_email: [email protected]
    src: /etc/pki/cert/csr/sample.com.csr
    cert: /etc/httpd/ssl/sample.com.crt
    fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
    chain: /etc/httpd/ssl/sample.com-intermediate.crt
    challenge: tls-alpn-01
    remaining_days: 60
    data: "{{ sample_com_challenge }}"
    # We use Let's Encrypt's ACME v2 endpoint
    acme_directory: https://acme-v02.api.letsencrypt.org/directory
    acme_version: 2
    # Garante que, se uma cadeia com / CN = DST Root CA X3 em seu emissor for fornecida como alternativa, 
    # ela será selecionada. Estas são as raízes assinadas por IdenTrust. Desde que o Let's Encrypt forneça 
    # cadeias alternativas com a(s) raiz(es) com sinal cruzado(s) ao alternar para sua própria raiz 
    # ISRG Root X1, isso usará a cadeia que termina com uma raiz com sinal cruzado. 
    # Esta cadeia é mais compatível com clientes TLS mais antigos.
    select_chain:
      - test_certificates: last
        issuer:
          CN: DST Root CA X3
          O: Digital Signature Trust Co.
  when: sample_com_challenge is changed

Valores Retornados

Chave			Descrição
account_uri	string	alterado	ACME account URI.
all_chains	list / elements=dictionary	quando o certificado foi recuperado e retrieve_all_alternates é definido como yes	Quando retrieve_all_alternates é definido como yes, o módulo irá consultar o servidor ACME para cadeias alternativas. Este valor de retorno conterá uma lista de todas as cadeias retornadas, a primeira entrada sendo a cadeia principal retornada pelo servidor.
authorizations	dictionary	alterado	Dados de autorização ACME. Mapeia um identificador para objetos de autorização ACME.
cert_days	integer	sucesso	O número de dias que o certificado permanece válido.
challenge_data	list / elements=dictionary	alterado	Por identificador/tipo de desafio de dados de desafio. Apenas desafios que ainda não são válidos são retornados.
challenge_data_dns	dictionary	alterado	Lista de valores TXT por registro DNS, caso o desafio seja dns-01. Apenas desafios que ainda não são válidos são retornados.
finalization_uri	string	alterado	URI de finalização ACME.
order_uri	string	alterado	URI do pedido ACME.

Subcampos do valor de retorno all_chains

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
cert	string	sempre	O próprio certificado folha, em formato PEM.
chain	string	sempre	A cadeia de certificados, excluindo a raiz, como certificados PEM concatenados.
full_chain	string	sempre	A cadeia de certificados, excluindo a raiz, mas incluindo o certificado folha, como certificados PEM concatenados.

Subcampos do valor de retorno challenge_data

Parâmetro	Tipo	Escolhas \| Valor Padrão	Comentários
record	string	alterado	O nome completo do registro DNS para o desafio.
resource	string	alterado	O recurso de desafio que deve ser criado para validação.
resource_original	string	alterado	O recurso de desafio original incluindo identificador de tipo para desafios tls-alpn-01.
resource_value	string	alterado	O valor que o recurso deve produzir para a validação. Para desafios http-01 e dns-01, o valor pode ser usado no estado em que se encontra. Para desafios tls-alpn-01, observe que este valor de retorno contém uma versão codificada em Base64 do blob binário correto que deve ser colocado na extensão acmeValidation x509; Para fazer isso, você pode precisar do filtro b64decode Jinja para extrair o blob binário desse valor de retorno.