405 lines
19 KiB
Python
405 lines
19 KiB
Python
# -*- coding: utf-8 -*-
|
|
|
|
# Copyright (c) 2016-2017, Yanis Guenane <yanis+ansible@guenane.org>
|
|
# Copyright (c) 2017, Markus Teufelberger <mteufelberger+ansible@mgit.at>
|
|
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
|
|
# SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
from __future__ import absolute_import, division, print_function
|
|
__metaclass__ = type
|
|
|
|
|
|
class ModuleDocFragment(object):
|
|
|
|
# Standard files documentation fragment
|
|
DOCUMENTATION = r'''
|
|
description:
|
|
- This module allows one to (re)generate OpenSSL certificates.
|
|
- It uses the cryptography python library to interact with OpenSSL.
|
|
requirements:
|
|
- cryptography >= 1.6 (if using C(selfsigned) or C(ownca) provider)
|
|
options:
|
|
force:
|
|
description:
|
|
- Generate the certificate, even if it already exists.
|
|
type: bool
|
|
default: no
|
|
|
|
csr_path:
|
|
description:
|
|
- Path to the Certificate Signing Request (CSR) used to generate this certificate.
|
|
- This is mutually exclusive with I(csr_content).
|
|
type: path
|
|
csr_content:
|
|
description:
|
|
- Content of the Certificate Signing Request (CSR) used to generate this certificate.
|
|
- This is mutually exclusive with I(csr_path).
|
|
type: str
|
|
|
|
privatekey_path:
|
|
description:
|
|
- Path to the private key to use when signing the certificate.
|
|
- This is mutually exclusive with I(privatekey_content).
|
|
type: path
|
|
privatekey_content:
|
|
description:
|
|
- Path to the private key to use when signing the certificate.
|
|
- This is mutually exclusive with I(privatekey_path).
|
|
type: str
|
|
|
|
privatekey_passphrase:
|
|
description:
|
|
- The passphrase for the I(privatekey_path) resp. I(privatekey_content).
|
|
- This is required if the private key is password protected.
|
|
type: str
|
|
|
|
ignore_timestamps:
|
|
description:
|
|
- Whether the "not before" and "not after" timestamps should be ignored for idempotency checks.
|
|
- It is better to keep the default value C(true) when using relative timestamps (like C(+0s) for now).
|
|
type: bool
|
|
default: true
|
|
version_added: 2.0.0
|
|
|
|
select_crypto_backend:
|
|
description:
|
|
- Determines which crypto backend to use.
|
|
- The default choice is C(auto), which tries to use C(cryptography) if available.
|
|
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
|
|
type: str
|
|
default: auto
|
|
choices: [ auto, cryptography ]
|
|
|
|
notes:
|
|
- All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
|
|
- Date specified should be UTC. Minutes and seconds are mandatory.
|
|
- For security reason, when you use C(ownca) provider, you should NOT run
|
|
M(community.crypto.x509_certificate) on a target machine, but on a dedicated CA machine. It
|
|
is recommended not to store the CA private key on the target machine. Once signed, the
|
|
certificate can be moved to the target machine.
|
|
seealso:
|
|
- module: community.crypto.openssl_csr
|
|
- module: community.crypto.openssl_csr_pipe
|
|
- module: community.crypto.openssl_dhparam
|
|
- module: community.crypto.openssl_pkcs12
|
|
- module: community.crypto.openssl_privatekey
|
|
- module: community.crypto.openssl_privatekey_pipe
|
|
- module: community.crypto.openssl_publickey
|
|
'''
|
|
|
|
BACKEND_ACME_DOCUMENTATION = r'''
|
|
description:
|
|
- This module allows one to (re)generate OpenSSL certificates.
|
|
requirements:
|
|
- acme-tiny >= 4.0.0 (if using the C(acme) provider)
|
|
options:
|
|
acme_accountkey_path:
|
|
description:
|
|
- The path to the accountkey for the C(acme) provider.
|
|
- This is only used by the C(acme) provider.
|
|
type: path
|
|
|
|
acme_challenge_path:
|
|
description:
|
|
- The path to the ACME challenge directory that is served on U(http://<HOST>:80/.well-known/acme-challenge/)
|
|
- This is only used by the C(acme) provider.
|
|
type: path
|
|
|
|
acme_chain:
|
|
description:
|
|
- Include the intermediate certificate to the generated certificate
|
|
- This is only used by the C(acme) provider.
|
|
- Note that this is only available for older versions of C(acme-tiny).
|
|
New versions include the chain automatically, and setting I(acme_chain) to C(yes) results in an error.
|
|
type: bool
|
|
default: no
|
|
|
|
acme_directory:
|
|
description:
|
|
- "The ACME directory to use. You can use any directory that supports the ACME protocol, such as Buypass or Let's Encrypt."
|
|
- "Let's Encrypt recommends using their staging server while developing jobs. U(https://letsencrypt.org/docs/staging-environment/)."
|
|
type: str
|
|
default: https://acme-v02.api.letsencrypt.org/directory
|
|
'''
|
|
|
|
BACKEND_ENTRUST_DOCUMENTATION = r'''
|
|
options:
|
|
entrust_cert_type:
|
|
description:
|
|
- Specify the type of certificate requested.
|
|
- This is only used by the C(entrust) provider.
|
|
type: str
|
|
default: STANDARD_SSL
|
|
choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT' ]
|
|
|
|
entrust_requester_email:
|
|
description:
|
|
- The email of the requester of the certificate (for tracking purposes).
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: str
|
|
|
|
entrust_requester_name:
|
|
description:
|
|
- The name of the requester of the certificate (for tracking purposes).
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: str
|
|
|
|
entrust_requester_phone:
|
|
description:
|
|
- The phone number of the requester of the certificate (for tracking purposes).
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: str
|
|
|
|
entrust_api_user:
|
|
description:
|
|
- The username for authentication to the Entrust Certificate Services (ECS) API.
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: str
|
|
|
|
entrust_api_key:
|
|
description:
|
|
- The key (password) for authentication to the Entrust Certificate Services (ECS) API.
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: str
|
|
|
|
entrust_api_client_cert_path:
|
|
description:
|
|
- The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: path
|
|
|
|
entrust_api_client_cert_key_path:
|
|
description:
|
|
- The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
|
|
- This is only used by the C(entrust) provider.
|
|
- This is required if the provider is C(entrust).
|
|
type: path
|
|
|
|
entrust_not_after:
|
|
description:
|
|
- The point in time at which the certificate stops being valid.
|
|
- Time can be specified either as relative time or as an absolute timestamp.
|
|
- A valid absolute time format is C(ASN.1 TIME) such as C(2019-06-18).
|
|
- A valid relative time format is C([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as C(+365d) or C(+32w1d2h)).
|
|
- Time will always be interpreted as UTC.
|
|
- Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate.
|
|
- The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day
|
|
earlier than expected if a relative time is used.
|
|
- The minimum certificate lifetime is 90 days, and maximum is three years.
|
|
- If this value is not specified, the certificate will stop being valid 365 days the date of issue.
|
|
- This is only used by the C(entrust) provider.
|
|
- Please note that this value is B(not) covered by the I(ignore_timestamps) option.
|
|
type: str
|
|
default: +365d
|
|
|
|
entrust_api_specification_path:
|
|
description:
|
|
- The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
|
|
- You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
|
|
- This is only used by the C(entrust) provider.
|
|
type: path
|
|
default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
|
|
'''
|
|
|
|
BACKEND_OWNCA_DOCUMENTATION = r'''
|
|
description:
|
|
- The C(ownca) provider is intended for generating an OpenSSL certificate signed with your own
|
|
CA (Certificate Authority) certificate (self-signed certificate).
|
|
options:
|
|
ownca_path:
|
|
description:
|
|
- Remote absolute path of the CA (Certificate Authority) certificate.
|
|
- This is only used by the C(ownca) provider.
|
|
- This is mutually exclusive with I(ownca_content).
|
|
type: path
|
|
ownca_content:
|
|
description:
|
|
- Content of the CA (Certificate Authority) certificate.
|
|
- This is only used by the C(ownca) provider.
|
|
- This is mutually exclusive with I(ownca_path).
|
|
type: str
|
|
|
|
ownca_privatekey_path:
|
|
description:
|
|
- Path to the CA (Certificate Authority) private key to use when signing the certificate.
|
|
- This is only used by the C(ownca) provider.
|
|
- This is mutually exclusive with I(ownca_privatekey_content).
|
|
type: path
|
|
ownca_privatekey_content:
|
|
description:
|
|
- Content of the CA (Certificate Authority) private key to use when signing the certificate.
|
|
- This is only used by the C(ownca) provider.
|
|
- This is mutually exclusive with I(ownca_privatekey_path).
|
|
type: str
|
|
|
|
ownca_privatekey_passphrase:
|
|
description:
|
|
- The passphrase for the I(ownca_privatekey_path) resp. I(ownca_privatekey_content).
|
|
- This is only used by the C(ownca) provider.
|
|
type: str
|
|
|
|
ownca_digest:
|
|
description:
|
|
- The digest algorithm to be used for the C(ownca) certificate.
|
|
- This is only used by the C(ownca) provider.
|
|
type: str
|
|
default: sha256
|
|
|
|
ownca_version:
|
|
description:
|
|
- The version of the C(ownca) certificate.
|
|
- Nowadays it should almost always be C(3).
|
|
- This is only used by the C(ownca) provider.
|
|
type: int
|
|
default: 3
|
|
|
|
ownca_not_before:
|
|
description:
|
|
- The point in time the certificate is valid from.
|
|
- Time can be specified either as relative time or as absolute timestamp.
|
|
- Time will always be interpreted as UTC.
|
|
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
|
|
+ C([w | d | h | m | s]) (for example C(+32w1d2h)).
|
|
- If this value is not specified, the certificate will start being valid from now.
|
|
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
|
|
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
|
|
avoid relative timestamps when setting I(ignore_timestamps=false).
|
|
- This is only used by the C(ownca) provider.
|
|
type: str
|
|
default: +0s
|
|
|
|
ownca_not_after:
|
|
description:
|
|
- The point in time at which the certificate stops being valid.
|
|
- Time can be specified either as relative time or as absolute timestamp.
|
|
- Time will always be interpreted as UTC.
|
|
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
|
|
+ C([w | d | h | m | s]) (for example C(+32w1d2h)).
|
|
- If this value is not specified, the certificate will stop being valid 10 years from now.
|
|
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
|
|
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
|
|
avoid relative timestamps when setting I(ignore_timestamps=false).
|
|
- This is only used by the C(ownca) provider.
|
|
- On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
|
|
Please see U(https://support.apple.com/en-us/HT210176) for more details.
|
|
type: str
|
|
default: +3650d
|
|
|
|
ownca_create_subject_key_identifier:
|
|
description:
|
|
- Whether to create the Subject Key Identifier (SKI) from the public key.
|
|
- A value of C(create_if_not_provided) (default) only creates a SKI when the CSR does not
|
|
provide one.
|
|
- A value of C(always_create) always creates a SKI. If the CSR provides one, that one is
|
|
ignored.
|
|
- A value of C(never_create) never creates a SKI. If the CSR provides one, that one is used.
|
|
- This is only used by the C(ownca) provider.
|
|
- Note that this is only supported if the C(cryptography) backend is used!
|
|
type: str
|
|
choices: [create_if_not_provided, always_create, never_create]
|
|
default: create_if_not_provided
|
|
|
|
ownca_create_authority_key_identifier:
|
|
description:
|
|
- Create a Authority Key Identifier from the CA's certificate. If the CSR provided
|
|
a authority key identifier, it is ignored.
|
|
- The Authority Key Identifier is generated from the CA certificate's Subject Key Identifier,
|
|
if available. If it is not available, the CA certificate's public key will be used.
|
|
- This is only used by the C(ownca) provider.
|
|
- Note that this is only supported if the C(cryptography) backend is used!
|
|
type: bool
|
|
default: yes
|
|
'''
|
|
|
|
BACKEND_SELFSIGNED_DOCUMENTATION = r'''
|
|
notes:
|
|
- For the C(selfsigned) provider, I(csr_path) and I(csr_content) are optional. If not provided, a
|
|
certificate without any information (Subject, Subject Alternative Names, Key Usage, etc.) is created.
|
|
|
|
options:
|
|
# NOTE: descriptions in options are overwritten, not appended. For that reason, the texts provided
|
|
# here for csr_path and csr_content are not visible to the user. That's why this information is
|
|
# added to the notes (see above).
|
|
|
|
# csr_path:
|
|
# description:
|
|
# - This is optional for the C(selfsigned) provider. If not provided, a certificate
|
|
# without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
|
|
# created.
|
|
|
|
# csr_content:
|
|
# description:
|
|
# - This is optional for the C(selfsigned) provider. If not provided, a certificate
|
|
# without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
|
|
# created.
|
|
|
|
selfsigned_version:
|
|
description:
|
|
- Version of the C(selfsigned) certificate.
|
|
- Nowadays it should almost always be C(3).
|
|
- This is only used by the C(selfsigned) provider.
|
|
type: int
|
|
default: 3
|
|
|
|
selfsigned_digest:
|
|
description:
|
|
- Digest algorithm to be used when self-signing the certificate.
|
|
- This is only used by the C(selfsigned) provider.
|
|
type: str
|
|
default: sha256
|
|
|
|
selfsigned_not_before:
|
|
description:
|
|
- The point in time the certificate is valid from.
|
|
- Time can be specified either as relative time or as absolute timestamp.
|
|
- Time will always be interpreted as UTC.
|
|
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
|
|
+ C([w | d | h | m | s]) (for example C(+32w1d2h)).
|
|
- If this value is not specified, the certificate will start being valid from now.
|
|
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
|
|
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
|
|
avoid relative timestamps when setting I(ignore_timestamps=false).
|
|
- This is only used by the C(selfsigned) provider.
|
|
type: str
|
|
default: +0s
|
|
aliases: [ selfsigned_notBefore ]
|
|
|
|
selfsigned_not_after:
|
|
description:
|
|
- The point in time at which the certificate stops being valid.
|
|
- Time can be specified either as relative time or as absolute timestamp.
|
|
- Time will always be interpreted as UTC.
|
|
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
|
|
+ C([w | d | h | m | s]) (for example C(+32w1d2h)).
|
|
- If this value is not specified, the certificate will stop being valid 10 years from now.
|
|
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
|
|
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
|
|
avoid relative timestamps when setting I(ignore_timestamps=false).
|
|
- This is only used by the C(selfsigned) provider.
|
|
- On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
|
|
Please see U(https://support.apple.com/en-us/HT210176) for more details.
|
|
type: str
|
|
default: +3650d
|
|
aliases: [ selfsigned_notAfter ]
|
|
|
|
selfsigned_create_subject_key_identifier:
|
|
description:
|
|
- Whether to create the Subject Key Identifier (SKI) from the public key.
|
|
- A value of C(create_if_not_provided) (default) only creates a SKI when the CSR does not
|
|
provide one.
|
|
- A value of C(always_create) always creates a SKI. If the CSR provides one, that one is
|
|
ignored.
|
|
- A value of C(never_create) never creates a SKI. If the CSR provides one, that one is used.
|
|
- This is only used by the C(selfsigned) provider.
|
|
- Note that this is only supported if the C(cryptography) backend is used!
|
|
type: str
|
|
choices: [create_if_not_provided, always_create, never_create]
|
|
default: create_if_not_provided
|
|
'''
|