mirror of
https://github.com/ansible-collections/community.crypto.git
synced 2026-05-08 06:13:03 +00:00
Reformat documentation with 'andebox yaml-doc' (#828)
* Reformat documentation with 'andebox yaml-doc'. * Fix/improve. * Remaining fixes. * One more.
This commit is contained in:
Felix Fontein
GitHub
@@ -9,355 +9,369 @@ from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: ecs_certificate
|
||||
author:
|
||||
- Chris Trufan (@ctrufan)
|
||||
- Chris Trufan (@ctrufan)
|
||||
short_description: Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API
|
||||
description:
|
||||
- Create, reissue, and renew certificates with the Entrust Certificate Services (ECS) API.
|
||||
- Requires credentials for the L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates) (ECS) API.
|
||||
- In order to request a certificate, the domain and organization used in the certificate signing request must be already
|
||||
validated in the ECS system. It is I(not) the responsibility of this module to perform those steps.
|
||||
- Create, reissue, and renew certificates with the Entrust Certificate Services (ECS) API.
|
||||
- Requires credentials for the L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates)
|
||||
(ECS) API.
|
||||
- In order to request a certificate, the domain and organization used in the certificate signing request must be already
|
||||
validated in the ECS system. It is I(not) the responsibility of this module to perform those steps.
|
||||
notes:
|
||||
- O(path) must be specified as the output location of the certificate.
|
||||
- O(path) must be specified as the output location of the certificate.
|
||||
requirements:
|
||||
- cryptography >= 1.6
|
||||
- cryptography >= 1.6
|
||||
extends_documentation_fragment:
|
||||
- community.crypto.attributes
|
||||
- community.crypto.attributes.files
|
||||
- community.crypto.ecs_credential
|
||||
- community.crypto.attributes
|
||||
- community.crypto.attributes.files
|
||||
- community.crypto.ecs_credential
|
||||
attributes:
|
||||
check_mode:
|
||||
support: partial
|
||||
details:
|
||||
- Check mode is only supported if O(request_type=new).
|
||||
diff_mode:
|
||||
support: none
|
||||
safe_file_operations:
|
||||
support: full
|
||||
check_mode:
|
||||
support: partial
|
||||
details:
|
||||
- Check mode is only supported if O(request_type=new).
|
||||
diff_mode:
|
||||
support: none
|
||||
safe_file_operations:
|
||||
support: full
|
||||
options:
|
||||
backup:
|
||||
description:
|
||||
- Whether a backup should be made for the certificate in O(path).
|
||||
type: bool
|
||||
default: false
|
||||
force:
|
||||
description:
|
||||
- If force is used, a certificate is requested regardless of whether O(path) points to an existing valid certificate.
|
||||
- If O(request_type=renew), a forced renew will fail if the certificate being renewed has been issued within the past 30 days, regardless of the
|
||||
value of O(remaining_days) or the return value of RV(cert_days) - the ECS API does not support the "renew" operation for certificates that are not
|
||||
at least 30 days old.
|
||||
type: bool
|
||||
default: false
|
||||
path:
|
||||
description:
|
||||
- The destination path for the generated certificate as a PEM encoded cert.
|
||||
- If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested even if the current
|
||||
certificate is technically valid.
|
||||
- If there is already an Entrust certificate at this location, whether it is replaced is depends on the O(remaining_days) calculation.
|
||||
- If an existing certificate is being replaced (see O(remaining_days), O(force), and O(tracking_id)), whether a new certificate is requested
|
||||
or the existing certificate is renewed or reissued is based on O(request_type).
|
||||
type: path
|
||||
required: true
|
||||
full_chain_path:
|
||||
description:
|
||||
- The destination path for the full certificate chain of the certificate, intermediates, and roots.
|
||||
type: path
|
||||
csr:
|
||||
description:
|
||||
- Base-64 encoded Certificate Signing Request (CSR). O(csr) is accepted with or without PEM formatting around the Base-64 string.
|
||||
- If no O(csr) is provided when O(request_type=reissue) or O(request_type=renew), the certificate will be generated with the same public key as
|
||||
the certificate being renewed or reissued.
|
||||
- If O(subject_alt_name) is specified, it will override the subject alternate names in the CSR.
|
||||
- If O(eku) is specified, it will override the extended key usage in the CSR.
|
||||
- If O(ou) is specified, it will override the organizational units "ou=" present in the subject distinguished name of the CSR, if any.
|
||||
- The organization "O=" field from the CSR will not be used. It will be replaced in the issued certificate by O(org) if present, and if not present,
|
||||
the organization tied to O(client_id).
|
||||
backup:
|
||||
description:
|
||||
- Whether a backup should be made for the certificate in O(path).
|
||||
type: bool
|
||||
default: false
|
||||
force:
|
||||
description:
|
||||
- If force is used, a certificate is requested regardless of whether O(path) points to an existing valid certificate.
|
||||
- If O(request_type=renew), a forced renew will fail if the certificate being renewed has been issued within the past
|
||||
30 days, regardless of the value of O(remaining_days) or the return value of RV(cert_days) - the ECS API does not
|
||||
support the "renew" operation for certificates that are not at least 30 days old.
|
||||
type: bool
|
||||
default: false
|
||||
path:
|
||||
description:
|
||||
- The destination path for the generated certificate as a PEM encoded cert.
|
||||
- If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested
|
||||
even if the current certificate is technically valid.
|
||||
- If there is already an Entrust certificate at this location, whether it is replaced is depends on the O(remaining_days)
|
||||
calculation.
|
||||
- If an existing certificate is being replaced (see O(remaining_days), O(force), and O(tracking_id)), whether a new
|
||||
certificate is requested or the existing certificate is renewed or reissued is based on O(request_type).
|
||||
type: path
|
||||
required: true
|
||||
full_chain_path:
|
||||
description:
|
||||
- The destination path for the full certificate chain of the certificate, intermediates, and roots.
|
||||
type: path
|
||||
csr:
|
||||
description:
|
||||
- Base-64 encoded Certificate Signing Request (CSR). O(csr) is accepted with or without PEM formatting around the Base-64
|
||||
string.
|
||||
- If no O(csr) is provided when O(request_type=reissue) or O(request_type=renew), the certificate will be generated
|
||||
with the same public key as the certificate being renewed or reissued.
|
||||
- If O(subject_alt_name) is specified, it will override the subject alternate names in the CSR.
|
||||
- If O(eku) is specified, it will override the extended key usage in the CSR.
|
||||
- If O(ou) is specified, it will override the organizational units "ou=" present in the subject distinguished name of
|
||||
the CSR, if any.
|
||||
- The organization "O=" field from the CSR will not be used. It will be replaced in the issued certificate by O(org)
|
||||
if present, and if not present, the organization tied to O(client_id).
|
||||
type: str
|
||||
tracking_id:
|
||||
description:
|
||||
- The tracking ID of the certificate to reissue or renew.
|
||||
- O(tracking_id) is invalid if O(request_type=new) or O(request_type=validate_only).
|
||||
- If there is a certificate present in O(path) and it is an ECS certificate, O(tracking_id) will be ignored.
|
||||
- If there is no certificate present in O(path) or there is but it is from another provider, the certificate represented
|
||||
by O(tracking_id) will be renewed or reissued and saved to O(path).
|
||||
- If there is no certificate present in O(path) and the O(force) and O(remaining_days) parameters do not indicate a
|
||||
new certificate is needed, the certificate referenced by O(tracking_id) certificate will be saved to O(path).
|
||||
- This can be used when a known certificate is not currently present on a server, but you want to renew or reissue it
|
||||
to be managed by an ansible playbook. For example, if you specify O(request_type=renew), O(tracking_id) of an issued
|
||||
certificate, and O(path) to a file that does not exist, the first run of a task will download the certificate specified
|
||||
by O(tracking_id) (assuming it is still valid). Future runs of the task will (if applicable - see O(force) and O(remaining_days))
|
||||
renew the certificate now present in O(path).
|
||||
type: int
|
||||
remaining_days:
|
||||
description:
|
||||
- The number of days the certificate must have left being valid. If RV(cert_days) < O(remaining_days) then a new certificate
|
||||
will be obtained using O(request_type).
|
||||
- If O(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30
|
||||
days, so do not set a O(remaining_days) value that is within 30 days of the full lifetime of the certificate being
|
||||
acted upon.
|
||||
- For example, if you are requesting Certificates with a 90 day lifetime, do not set O(remaining_days) to a value V(60)
|
||||
or higher).
|
||||
- The O(force) option may be used to ensure that a new certificate is always obtained.
|
||||
type: int
|
||||
default: 30
|
||||
request_type:
|
||||
description:
|
||||
- The operation performed if O(tracking_id) references a valid certificate to reissue, or there is already a certificate
|
||||
present in O(path) but either O(force) is specified or RV(cert_days) < O(remaining_days).
|
||||
- Specifying O(request_type=validate_only) means the request will be validated against the ECS API, but no certificate
|
||||
will be issued.
|
||||
- Specifying O(request_type=new) means a certificate request will always be submitted and a new certificate issued.
|
||||
- Specifying O(request_type=renew) means that an existing certificate (specified by O(tracking_id) if present, otherwise
|
||||
O(path)) will be renewed. If there is no certificate to renew, a new certificate is requested.
|
||||
- Specifying O(request_type=reissue) means that an existing certificate (specified by O(tracking_id) if present, otherwise
|
||||
O(path)) will be reissued. If there is no certificate to reissue, a new certificate is requested.
|
||||
- If a certificate was issued within the past 30 days, the V(renew) operation is not a valid operation and will fail.
|
||||
- Note that V(reissue) is an operation that will result in the revocation of the certificate that is reissued, be cautious
|
||||
with its use.
|
||||
- I(check_mode) is only supported if O(request_type=new).
|
||||
- For example, setting O(request_type=renew) and O(remaining_days=30) and pointing to the same certificate on multiple
|
||||
playbook runs means that on the first run new certificate will be requested. It will then be left along on future
|
||||
runs until it is within 30 days of expiry, then the ECS "renew" operation will be performed.
|
||||
type: str
|
||||
choices: ['new', 'renew', 'reissue', 'validate_only']
|
||||
default: new
|
||||
cert_type:
|
||||
description:
|
||||
- Specify the type of certificate requested.
|
||||
- If a certificate is being reissued or renewed, this parameter is ignored, and the O(cert_type) of the initial certificate
|
||||
is used.
|
||||
type: str
|
||||
choices: ['STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CODE_SIGNING',
|
||||
'EV_CODE_SIGNING', 'CDS_INDIVIDUAL', 'CDS_GROUP', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT']
|
||||
subject_alt_name:
|
||||
description:
|
||||
- The subject alternative name identifiers, as an array of values (applies to O(cert_type) with a value of V(STANDARD_SSL),
|
||||
V(ADVANTAGE_SSL), V(UC_SSL), V(EV_SSL), V(WILDCARD_SSL), V(PRIVATE_SSL), and V(PD_SSL)).
|
||||
- If you are requesting a new SSL certificate, and you pass a O(subject_alt_name) parameter, any SAN names in the CSR
|
||||
are ignored. If no subjectAltName parameter is passed, the SAN names in the CSR are used.
|
||||
- See O(request_type) to understand more about SANs during reissues and renewals.
|
||||
- In the case of certificates of type V(STANDARD_SSL) certificates, if the CN of the certificate is <domain>.<tld> only
|
||||
the www.<domain>.<tld> value is accepted. If the CN of the certificate is www.<domain>.<tld> only the <domain>.<tld>
|
||||
value is accepted.
|
||||
type: list
|
||||
elements: str
|
||||
eku:
|
||||
description:
|
||||
- If specified, overrides the key usage in the O(csr).
|
||||
type: str
|
||||
choices: [SERVER_AUTH, CLIENT_AUTH, SERVER_AND_CLIENT_AUTH]
|
||||
ct_log:
|
||||
description:
|
||||
- In compliance with browser requirements, this certificate may be posted to the Certificate Transparency (CT) logs.
|
||||
This is a best practice technique that helps domain owners monitor certificates issued to their domains. Note that
|
||||
not all certificates are eligible for CT logging.
|
||||
- If O(ct_log) is not specified, the certificate uses the account default.
|
||||
- If O(ct_log) is specified and the account settings allow it, O(ct_log) overrides the account default.
|
||||
- If O(ct_log) is set to V(false), but the account settings are set to "always log", the certificate generation will
|
||||
fail.
|
||||
type: bool
|
||||
client_id:
|
||||
description:
|
||||
- The client ID to submit the Certificate Signing Request under.
|
||||
- If no client ID is specified, the certificate will be submitted under the primary client with ID of 1.
|
||||
- When using a client other than the primary client, the O(org) parameter cannot be specified.
|
||||
- The issued certificate will have an organization value in the subject distinguished name represented by the client.
|
||||
type: int
|
||||
default: 1
|
||||
org:
|
||||
description:
|
||||
- Organization "O=" to include in the certificate.
|
||||
- If O(org) is not specified, the organization from the client represented by O(client_id) is used.
|
||||
- Unless the O(cert_type) is V(PD_SSL), this field may not be specified if the value of O(client_id) is not "1" (the
|
||||
primary client). non-primary clients, certificates may only be issued with the organization of that client.
|
||||
type: str
|
||||
ou:
|
||||
description:
|
||||
- Organizational unit "OU=" to include in the certificate.
|
||||
- O(ou) behavior is dependent on whether organizational units are enabled for your account. If organizational unit support
|
||||
is disabled for your account, organizational units from the O(csr) and the O(ou) parameter are ignored.
|
||||
- If both O(csr) and O(ou) are specified, the value in O(ou) will override the OU fields present in the subject distinguished
|
||||
name in the O(csr).
|
||||
- If neither O(csr) nor O(ou) are specified for a renew or reissue operation, the OU fields in the initial certificate
|
||||
are reused.
|
||||
- An invalid OU from O(csr) is ignored, but any invalid organizational units in O(ou) will result in an error indicating
|
||||
"Unapproved OU". The O(ou) parameter can be used to force failure if an unapproved organizational unit is provided.
|
||||
- A maximum of one OU may be specified for current products. Multiple OUs are reserved for future products.
|
||||
type: list
|
||||
elements: str
|
||||
end_user_key_storage_agreement:
|
||||
description:
|
||||
- The end user of the Code Signing certificate must generate and store the private key for this request on cryptographically
|
||||
secure hardware to be compliant with the Entrust CSP and Subscription agreement. If requesting a certificate of type
|
||||
V(CODE_SIGNING) or V(EV_CODE_SIGNING), you must set O(end_user_key_storage_agreement) to true if and only if you acknowledge
|
||||
that you will inform the user of this requirement.
|
||||
- Applicable only to O(cert_type) of values V(CODE_SIGNING) and V(EV_CODE_SIGNING).
|
||||
type: bool
|
||||
tracking_info:
|
||||
description: Free form tracking information to attach to the record for the certificate.
|
||||
type: str
|
||||
requester_name:
|
||||
description: The requester name to associate with certificate tracking information.
|
||||
type: str
|
||||
required: true
|
||||
requester_email:
|
||||
description: The requester email to associate with certificate tracking information and receive delivery and expiry notices
|
||||
for the certificate.
|
||||
type: str
|
||||
required: true
|
||||
requester_phone:
|
||||
description: The requester phone number to associate with certificate tracking information.
|
||||
type: str
|
||||
required: true
|
||||
additional_emails:
|
||||
description: A list of additional email addresses to receive the delivery notice and expiry notification for the certificate.
|
||||
type: list
|
||||
elements: str
|
||||
custom_fields:
|
||||
description:
|
||||
- Mapping of custom fields to associate with the certificate request and certificate.
|
||||
- Only supported if custom fields are enabled for your account.
|
||||
- Each custom field specified must be a custom field you have defined for your account.
|
||||
type: dict
|
||||
suboptions:
|
||||
text1:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
tracking_id:
|
||||
description:
|
||||
- The tracking ID of the certificate to reissue or renew.
|
||||
- O(tracking_id) is invalid if O(request_type=new) or O(request_type=validate_only).
|
||||
- If there is a certificate present in O(path) and it is an ECS certificate, O(tracking_id) will be ignored.
|
||||
- If there is no certificate present in O(path) or there is but it is from another provider, the certificate represented by O(tracking_id) will
|
||||
be renewed or reissued and saved to O(path).
|
||||
- If there is no certificate present in O(path) and the O(force) and O(remaining_days) parameters do not indicate a new certificate is needed,
|
||||
the certificate referenced by O(tracking_id) certificate will be saved to O(path).
|
||||
- This can be used when a known certificate is not currently present on a server, but you want to renew or reissue it to be managed by an ansible
|
||||
playbook. For example, if you specify O(request_type=renew), O(tracking_id) of an issued certificate, and O(path) to a file that does not exist,
|
||||
the first run of a task will download the certificate specified by O(tracking_id) (assuming it is still valid). Future runs of the task will
|
||||
(if applicable - see O(force) and O(remaining_days)) renew the certificate now present in O(path).
|
||||
type: int
|
||||
remaining_days:
|
||||
description:
|
||||
- The number of days the certificate must have left being valid. If RV(cert_days) < O(remaining_days) then a new certificate will be
|
||||
obtained using O(request_type).
|
||||
- If O(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30 days, so do not set a
|
||||
O(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon.
|
||||
- For example, if you are requesting Certificates with a 90 day lifetime, do not set O(remaining_days) to a value V(60) or higher).
|
||||
- The O(force) option may be used to ensure that a new certificate is always obtained.
|
||||
type: int
|
||||
default: 30
|
||||
request_type:
|
||||
description:
|
||||
- The operation performed if O(tracking_id) references a valid certificate to reissue, or there is already a certificate present in O(path) but
|
||||
either O(force) is specified or RV(cert_days) < O(remaining_days).
|
||||
- Specifying O(request_type=validate_only) means the request will be validated against the ECS API, but no certificate will be issued.
|
||||
- Specifying O(request_type=new) means a certificate request will always be submitted and a new certificate issued.
|
||||
- Specifying O(request_type=renew) means that an existing certificate (specified by O(tracking_id) if present, otherwise O(path)) will be renewed.
|
||||
If there is no certificate to renew, a new certificate is requested.
|
||||
- Specifying O(request_type=reissue) means that an existing certificate (specified by O(tracking_id) if present, otherwise O(path)) will be
|
||||
reissued.
|
||||
If there is no certificate to reissue, a new certificate is requested.
|
||||
- If a certificate was issued within the past 30 days, the V(renew) operation is not a valid operation and will fail.
|
||||
- Note that V(reissue) is an operation that will result in the revocation of the certificate that is reissued, be cautious with its use.
|
||||
- I(check_mode) is only supported if O(request_type=new)
|
||||
- For example, setting O(request_type=renew) and O(remaining_days=30) and pointing to the same certificate on multiple playbook runs means that on
|
||||
the first run new certificate will be requested. It will then be left along on future runs until it is within 30 days of expiry, then the
|
||||
ECS "renew" operation will be performed.
|
||||
text2:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
choices: [ 'new', 'renew', 'reissue', 'validate_only']
|
||||
default: new
|
||||
cert_type:
|
||||
description:
|
||||
- Specify the type of certificate requested.
|
||||
- If a certificate is being reissued or renewed, this parameter is ignored, and the O(cert_type) of the initial certificate is used.
|
||||
text3:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CODE_SIGNING', 'EV_CODE_SIGNING',
|
||||
'CDS_INDIVIDUAL', 'CDS_GROUP', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT' ]
|
||||
subject_alt_name:
|
||||
description:
|
||||
- The subject alternative name identifiers, as an array of values (applies to O(cert_type) with a value of V(STANDARD_SSL), V(ADVANTAGE_SSL),
|
||||
V(UC_SSL), V(EV_SSL), V(WILDCARD_SSL), V(PRIVATE_SSL), and V(PD_SSL)).
|
||||
- If you are requesting a new SSL certificate, and you pass a O(subject_alt_name) parameter, any SAN names in the CSR are ignored.
|
||||
If no subjectAltName parameter is passed, the SAN names in the CSR are used.
|
||||
- See O(request_type) to understand more about SANs during reissues and renewals.
|
||||
- In the case of certificates of type V(STANDARD_SSL) certificates, if the CN of the certificate is <domain>.<tld> only the www.<domain>.<tld> value
|
||||
is accepted. If the CN of the certificate is www.<domain>.<tld> only the <domain>.<tld> value is accepted.
|
||||
type: list
|
||||
elements: str
|
||||
eku:
|
||||
description:
|
||||
- If specified, overrides the key usage in the O(csr).
|
||||
text4:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
choices: [ SERVER_AUTH, CLIENT_AUTH, SERVER_AND_CLIENT_AUTH ]
|
||||
ct_log:
|
||||
description:
|
||||
- In compliance with browser requirements, this certificate may be posted to the Certificate Transparency (CT) logs. This is a best practice
|
||||
technique that helps domain owners monitor certificates issued to their domains. Note that not all certificates are eligible for CT logging.
|
||||
- If O(ct_log) is not specified, the certificate uses the account default.
|
||||
- If O(ct_log) is specified and the account settings allow it, O(ct_log) overrides the account default.
|
||||
- If O(ct_log) is set to V(false), but the account settings are set to "always log", the certificate generation will fail.
|
||||
type: bool
|
||||
client_id:
|
||||
description:
|
||||
- The client ID to submit the Certificate Signing Request under.
|
||||
- If no client ID is specified, the certificate will be submitted under the primary client with ID of 1.
|
||||
- When using a client other than the primary client, the O(org) parameter cannot be specified.
|
||||
- The issued certificate will have an organization value in the subject distinguished name represented by the client.
|
||||
type: int
|
||||
default: 1
|
||||
org:
|
||||
description:
|
||||
- Organization "O=" to include in the certificate.
|
||||
- If O(org) is not specified, the organization from the client represented by O(client_id) is used.
|
||||
- Unless the O(cert_type) is V(PD_SSL), this field may not be specified if the value of O(client_id) is not "1" (the primary client).
|
||||
non-primary clients, certificates may only be issued with the organization of that client.
|
||||
text5:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
ou:
|
||||
description:
|
||||
- Organizational unit "OU=" to include in the certificate.
|
||||
- O(ou) behavior is dependent on whether organizational units are enabled for your account. If organizational unit support is disabled for your
|
||||
account, organizational units from the O(csr) and the O(ou) parameter are ignored.
|
||||
- If both O(csr) and O(ou) are specified, the value in O(ou) will override the OU fields present in the subject distinguished name in the O(csr)
|
||||
- If neither O(csr) nor O(ou) are specified for a renew or reissue operation, the OU fields in the initial certificate are reused.
|
||||
- An invalid OU from O(csr) is ignored, but any invalid organizational units in O(ou) will result in an error indicating "Unapproved OU". The O(ou)
|
||||
parameter can be used to force failure if an unapproved organizational unit is provided.
|
||||
- A maximum of one OU may be specified for current products. Multiple OUs are reserved for future products.
|
||||
type: list
|
||||
elements: str
|
||||
end_user_key_storage_agreement:
|
||||
description:
|
||||
- The end user of the Code Signing certificate must generate and store the private key for this request on cryptographically secure
|
||||
hardware to be compliant with the Entrust CSP and Subscription agreement. If requesting a certificate of type V(CODE_SIGNING) or
|
||||
V(EV_CODE_SIGNING), you must set O(end_user_key_storage_agreement) to true if and only if you acknowledge that you will inform the user of this
|
||||
requirement.
|
||||
- Applicable only to O(cert_type) of values V(CODE_SIGNING) and V(EV_CODE_SIGNING).
|
||||
type: bool
|
||||
tracking_info:
|
||||
description: Free form tracking information to attach to the record for the certificate.
|
||||
text6:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
requester_name:
|
||||
description: The requester name to associate with certificate tracking information.
|
||||
text7:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
required: true
|
||||
requester_email:
|
||||
description: The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate.
|
||||
text8:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
required: true
|
||||
requester_phone:
|
||||
description: The requester phone number to associate with certificate tracking information.
|
||||
text9:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
required: true
|
||||
additional_emails:
|
||||
description: A list of additional email addresses to receive the delivery notice and expiry notification for the certificate.
|
||||
type: list
|
||||
elements: str
|
||||
custom_fields:
|
||||
description:
|
||||
- Mapping of custom fields to associate with the certificate request and certificate.
|
||||
- Only supported if custom fields are enabled for your account.
|
||||
- Each custom field specified must be a custom field you have defined for your account.
|
||||
type: dict
|
||||
suboptions:
|
||||
text1:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text2:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text3:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text4:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text5:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text6:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text7:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text8:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text9:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text10:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text11:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text12:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text13:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text14:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
text15:
|
||||
description: Custom text field (maximum 500 characters)
|
||||
type: str
|
||||
number1:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number2:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number3:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number4:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number5:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
date1:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date2:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date3:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date4:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date5:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
email1:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email2:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email3:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email4:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email5:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
dropdown1:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown2:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown3:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown4:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown5:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
cert_expiry:
|
||||
description:
|
||||
- The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example,
|
||||
V(2020-02-23), V(2020-02-23T15:00:00.05Z).
|
||||
- O(cert_expiry) is only supported for requests of O(request_type=new) or O(request_type=renew). If O(request_type=reissue),
|
||||
O(cert_expiry) will be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial
|
||||
certificate.
|
||||
- A reissued certificate will always have the same expiry as the original certificate.
|
||||
- Note that only the date (day, month, year) is supported for specifying the expiry date. If you choose to specify an expiry time with the expiry
|
||||
date, the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous
|
||||
day.
|
||||
- Applies only to accounts with a pooling inventory model.
|
||||
- Only one of O(cert_expiry) or O(cert_lifetime) may be specified.
|
||||
text10:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
cert_lifetime:
|
||||
description:
|
||||
- The lifetime of the certificate.
|
||||
- Applies to all certificates for accounts with a non-pooling inventory model.
|
||||
- O(cert_lifetime) is only supported for requests of O(request_type=new) or O(request_type=renew). If O(request_type=reissue), O(cert_lifetime) will
|
||||
be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial certificate.
|
||||
- Applies to certificates of O(cert_type=CDS_INDIVIDUAL), V(CDS_GROUP), V(CDS_ENT_LITE), V(CDS_ENT_PRO), or V(SMIME_ENT)
|
||||
for accounts with a pooling inventory model.
|
||||
- V(P1Y) is a certificate with a 1 year lifetime.
|
||||
- V(P2Y) is a certificate with a 2 year lifetime.
|
||||
- V(P3Y) is a certificate with a 3 year lifetime.
|
||||
- Only one of O(cert_expiry) or O(cert_lifetime) may be specified.
|
||||
text11:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
choices: [ P1Y, P2Y, P3Y ]
|
||||
text12:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
text13:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
text14:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
text15:
|
||||
description: Custom text field (maximum 500 characters).
|
||||
type: str
|
||||
number1:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number2:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number3:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number4:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
number5:
|
||||
description: Custom number field.
|
||||
type: float
|
||||
date1:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date2:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date3:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date4:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
date5:
|
||||
description: Custom date field.
|
||||
type: str
|
||||
email1:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email2:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email3:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email4:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
email5:
|
||||
description: Custom email field.
|
||||
type: str
|
||||
dropdown1:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown2:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown3:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown4:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
dropdown5:
|
||||
description: Custom dropdown field.
|
||||
type: str
|
||||
cert_expiry:
|
||||
description:
|
||||
- The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example, V(2020-02-23),
|
||||
V(2020-02-23T15:00:00.05Z).
|
||||
- O(cert_expiry) is only supported for requests of O(request_type=new) or O(request_type=renew). If O(request_type=reissue),
|
||||
O(cert_expiry) will be used for the first certificate issuance, but subsequent issuances will have the same expiry
|
||||
as the initial certificate.
|
||||
- A reissued certificate will always have the same expiry as the original certificate.
|
||||
- Note that only the date (day, month, year) is supported for specifying the expiry date. If you choose to specify an
|
||||
expiry time with the expiry date, the time will be adjusted to Eastern Standard Time (EST). This could have the unintended
|
||||
effect of moving your expiry date to the previous day.
|
||||
- Applies only to accounts with a pooling inventory model.
|
||||
- Only one of O(cert_expiry) or O(cert_lifetime) may be specified.
|
||||
type: str
|
||||
cert_lifetime:
|
||||
description:
|
||||
- The lifetime of the certificate.
|
||||
- Applies to all certificates for accounts with a non-pooling inventory model.
|
||||
- O(cert_lifetime) is only supported for requests of O(request_type=new) or O(request_type=renew). If O(request_type=reissue),
|
||||
O(cert_lifetime) will be used for the first certificate issuance, but subsequent issuances will have the same expiry
|
||||
as the initial certificate.
|
||||
- Applies to certificates of O(cert_type=CDS_INDIVIDUAL), V(CDS_GROUP), V(CDS_ENT_LITE), V(CDS_ENT_PRO), or V(SMIME_ENT)
|
||||
for accounts with a pooling inventory model.
|
||||
- V(P1Y) is a certificate with a 1 year lifetime.
|
||||
- V(P2Y) is a certificate with a 2 year lifetime.
|
||||
- V(P3Y) is a certificate with a 3 year lifetime.
|
||||
- Only one of O(cert_expiry) or O(cert_lifetime) may be specified.
|
||||
type: str
|
||||
choices: [P1Y, P2Y, P3Y]
|
||||
seealso:
|
||||
- module: community.crypto.openssl_privatekey
|
||||
description: Can be used to create private keys (both for certificates and accounts).
|
||||
- module: community.crypto.openssl_csr
|
||||
description: Can be used to create a Certificate Signing Request (CSR).
|
||||
- plugin: community.crypto.to_serial
|
||||
plugin_type: filter
|
||||
'''
|
||||
- module: community.crypto.openssl_privatekey
|
||||
description: Can be used to create private keys (both for certificates and accounts).
|
||||
- module: community.crypto.openssl_csr
|
||||
description: Can be used to create a Certificate Signing Request (CSR).
|
||||
- plugin: community.crypto.to_serial
|
||||
plugin_type: filter
|
||||
"""
|
||||
|
||||
EXAMPLES = r'''
|
||||
- name: Request a new certificate from Entrust with bare minimum parameters.
|
||||
Will request a new certificate if current one is valid but within 30
|
||||
days of expiry. If replacing an existing file in path, will back it up.
|
||||
EXAMPLES = r"""
|
||||
- name: Request a new certificate from Entrust with bare minimum parameters. Will request a new certificate if current one
|
||||
is valid but within 30 days of expiry. If replacing an existing file in path, will back it up.
|
||||
community.crypto.ecs_certificate:
|
||||
backup: true
|
||||
path: /etc/ssl/crt/ansible.com.crt
|
||||
@@ -372,10 +386,8 @@ EXAMPLES = r'''
|
||||
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
|
||||
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
|
||||
|
||||
- name: If there is no certificate present in path, request a new certificate
|
||||
of type EV_SSL. Otherwise, if there is an Entrust managed certificate
|
||||
in path and it is within 63 days of expiration, request a renew of that
|
||||
certificate.
|
||||
- name: If there is no certificate present in path, request a new certificate of type EV_SSL. Otherwise, if there is an
|
||||
Entrust managed certificate in path and it is within 63 days of expiration, request a renew of that certificate.
|
||||
community.crypto.ecs_certificate:
|
||||
path: /etc/ssl/crt/ansible.com.crt
|
||||
csr: /etc/ssl/csr/ansible.com.csr
|
||||
@@ -391,11 +403,9 @@ EXAMPLES = r'''
|
||||
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
|
||||
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
|
||||
|
||||
- name: If there is no certificate present in path, download certificate
|
||||
specified by tracking_id if it is still valid. Otherwise, if the
|
||||
certificate is within 79 days of expiration, request a renew of that
|
||||
certificate and save it in path. This can be used to "migrate" a
|
||||
certificate to be Ansible managed.
|
||||
- name: If there is no certificate present in path, download certificate specified by tracking_id if it is still valid.
|
||||
Otherwise, if the certificate is within 79 days of expiration, request a renew of that certificate and save it in path.
|
||||
This can be used to "migrate" a certificate to be Ansible managed.
|
||||
community.crypto.ecs_certificate:
|
||||
path: /etc/ssl/crt/ansible.com.crt
|
||||
csr: /etc/ssl/csr/ansible.com.csr
|
||||
@@ -418,10 +428,8 @@ EXAMPLES = r'''
|
||||
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
|
||||
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
|
||||
|
||||
- name: Request a new certificate with an alternative client. Note that the
|
||||
issued certificate will have its Subject Distinguished Name use the
|
||||
organization details associated with that client, rather than what is
|
||||
in the CSR.
|
||||
- name: Request a new certificate with an alternative client. Note that the issued certificate will have its Subject Distinguished
|
||||
Name use the organization details associated with that client, rather than what is in the CSR.
|
||||
community.crypto.ecs_certificate:
|
||||
path: /etc/ssl/crt/ansible.com.crt
|
||||
csr: /etc/ssl/csr/ansible.com.csr
|
||||
@@ -434,8 +442,7 @@ EXAMPLES = r'''
|
||||
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
|
||||
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
|
||||
|
||||
- name: Request a new certificate with a number of CSR parameters overridden
|
||||
and tracking information
|
||||
- name: Request a new certificate with a number of CSR parameters overridden and tracking information
|
||||
community.crypto.ecs_certificate:
|
||||
path: /etc/ssl/crt/ansible.com.crt
|
||||
full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
|
||||
@@ -467,60 +474,60 @@ EXAMPLES = r'''
|
||||
entrust_api_key: a^lv*32!cd9LnT
|
||||
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
|
||||
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
|
||||
"""
|
||||
|
||||
'''
|
||||
|
||||
RETURN = '''
|
||||
RETURN = r"""
|
||||
filename:
|
||||
description: The destination path for the generated certificate.
|
||||
returned: changed or success
|
||||
type: str
|
||||
sample: /etc/ssl/crt/www.ansible.com.crt
|
||||
description: The destination path for the generated certificate.
|
||||
returned: changed or success
|
||||
type: str
|
||||
sample: /etc/ssl/crt/www.ansible.com.crt
|
||||
backup_file:
|
||||
description: Name of backup file created for the certificate.
|
||||
returned: changed and if O(backup) is V(true)
|
||||
type: str
|
||||
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
|
||||
description: Name of backup file created for the certificate.
|
||||
returned: changed and if O(backup) is V(true)
|
||||
type: str
|
||||
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
|
||||
backup_full_chain_file:
|
||||
description: Name of the backup file created for the certificate chain.
|
||||
returned: changed and if O(backup) is V(true) and O(full_chain_path) is set.
|
||||
type: str
|
||||
sample: /path/to/ca.chain.crt.2019-03-09@11:22~
|
||||
description: Name of the backup file created for the certificate chain.
|
||||
returned: changed and if O(backup) is V(true) and O(full_chain_path) is set.
|
||||
type: str
|
||||
sample: /path/to/ca.chain.crt.2019-03-09@11:22~
|
||||
tracking_id:
|
||||
description: The tracking ID to reference and track the certificate in ECS.
|
||||
returned: success
|
||||
type: int
|
||||
sample: 380079
|
||||
description: The tracking ID to reference and track the certificate in ECS.
|
||||
returned: success
|
||||
type: int
|
||||
sample: 380079
|
||||
serial_number:
|
||||
description:
|
||||
- The serial number of the issued certificate.
|
||||
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
|
||||
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
|
||||
returned: success
|
||||
type: int
|
||||
sample: 1235262234164342
|
||||
description:
|
||||
- The serial number of the issued certificate.
|
||||
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
|
||||
you need to convert it to that form with P(community.crypto.to_serial#filter).
|
||||
returned: success
|
||||
type: int
|
||||
sample: 1235262234164342
|
||||
cert_days:
|
||||
description: The number of days the certificate remains valid.
|
||||
returned: success
|
||||
type: int
|
||||
sample: 253
|
||||
description: The number of days the certificate remains valid.
|
||||
returned: success
|
||||
type: int
|
||||
sample: 253
|
||||
cert_status:
|
||||
description:
|
||||
- The certificate status in ECS.
|
||||
- 'Current possible values (which may be expanded in the future) are: V(ACTIVE), V(APPROVED), V(DEACTIVATED), V(DECLINED), V(EXPIRED), V(NA),
|
||||
V(PENDING), V(PENDING_QUORUM), V(READY), V(REISSUED), V(REISSUING), V(RENEWED), V(RENEWING), V(REVOKED), V(SUSPENDED)'
|
||||
returned: success
|
||||
type: str
|
||||
sample: ACTIVE
|
||||
description:
|
||||
- The certificate status in ECS.
|
||||
- 'Current possible values (which may be expanded in the future) are: V(ACTIVE), V(APPROVED), V(DEACTIVATED), V(DECLINED),
|
||||
V(EXPIRED), V(NA), V(PENDING), V(PENDING_QUORUM), V(READY), V(REISSUED), V(REISSUING), V(RENEWED), V(RENEWING), V(REVOKED),
|
||||
V(SUSPENDED).'
|
||||
returned: success
|
||||
type: str
|
||||
sample: ACTIVE
|
||||
cert_details:
|
||||
description:
|
||||
- The full response JSON from the Get Certificate call of the ECS API.
|
||||
- 'While the response contents are guaranteed to be forwards compatible with new ECS API releases, Entrust recommends that you do not make any
|
||||
playbooks take actions based on the content of this field. However it may be useful for debugging, logging, or auditing purposes.'
|
||||
returned: success
|
||||
type: dict
|
||||
|
||||
'''
|
||||
description:
|
||||
- The full response JSON from the Get Certificate call of the ECS API.
|
||||
- While the response contents are guaranteed to be forwards compatible with new ECS API releases, Entrust recommends that
|
||||
you do not make any playbooks take actions based on the content of this field. However it may be useful for debugging,
|
||||
logging, or auditing purposes.
|
||||
returned: success
|
||||
type: dict
|
||||
"""
|
||||
|
||||
from ansible_collections.community.crypto.plugins.module_utils.ecs.api import (
|
||||
ecs_client_argument_spec,
|
||||
|
||||
Reference in New Issue
Block a user