Acme Certificate
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. |