entrust.crypto.cagw_certificate module – Request SSL/TLS certificates with the Certificate Authority Gateway (CAGW) API

Note

This module is part of the entrust.crypto collection (version 1.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install entrust.crypto. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: entrust.crypto.cagw_certificate.

Synopsis

• Create, get, and take actions (Hold, Unhold, Revoke certificates) with the Certificate Authority Gateway (CAGW) API.

• Requires credentials for calling the CAGW API.

Requirements

The below requirements are needed on the host that executes this module.

• cryptography >= 1.6

• Ansible Core >= 2.14.0

• Minimum Python Version = 3.6

Parameters

Parameter	Comments
action_reason string	Reason has to be given for the action.
action_type string	What action has to be taken on the certificate that is RevokeAction, HoldAction, UnholdAction. Choices: "RevokeAction" "HoldAction" "UnholdAction"
additional_emails list / elements=string	A list of additional email addresses to receive the delivery notice and expiry notification for the certificate.
cagw_api_client_cert_key_path path / required	Path for the Client cert key issued by the same CA.
cagw_api_client_cert_path path / required	Path for the Client cert issued by the same CA.
cagw_api_specification_path path / required	Path for CAGW api specification doc.
certificate_authority_id string / required	Unique id for the Certificate Authority.
certificate_profile_id string	Profile id for the Certificate Authority.
connector_name string	This parameter defines which CA type connected at the backend. Supported list of CAs include Entrust Certificate Solution(ECS), Entrust Security Manager(SM), Entrust PKIHUB CA(PKIaaS), Microsoft CA(MSCA). If connector_name is not provided when request_type=new, module will be failed. Choices: "SM" "ECS" "PKIaaS" "MSCA"
csr path	Base-64 encoded Certificate Signing Request (CSR). csr is accepted without PEM formatting around the Base-64 string. If no csr is provided when request_type=new and enrollment_format=X509, the certificate will not be generated and module will be failed.
custom_fields dictionary	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.
date1 string	Custom date field.
date2 string	Custom date field.
date3 string	Custom date field.
date4 string	Custom date field.
date5 string	Custom date field.
dropdown1 string	Custom dropdown field.
dropdown2 string	Custom dropdown field.
dropdown3 string	Custom dropdown field.
dropdown4 string	Custom dropdown field.
dropdown5 string	Custom dropdown field.
email1 string	Custom email field.
email2 string	Custom email field.
email3 string	Custom email field.
email4 string	Custom email field.
email5 string	Custom email field.
number1 float	Custom number field.
number2 float	Custom number field.
number3 float	Custom number field.
number4 float	Custom number field.
number5 float	Custom number field.
text1 string	Custom text field (maximum 500 characters).
text10 string	Custom text field (maximum 500 characters).
text11 string	Custom text field (maximum 500 characters).
text12 string	Custom text field (maximum 500 characters).
text13 string	Custom text field (maximum 500 characters).
text14 string	Custom text field (maximum 500 characters).
text15 string	Custom text field (maximum 500 characters).
text2 string	Custom text field (maximum 500 characters).
text3 string	Custom text field (maximum 500 characters).
text4 string	Custom text field (maximum 500 characters).
text5 string	Custom text field (maximum 500 characters).
text6 string	Custom text field (maximum 500 characters).
text7 string	Custom text field (maximum 500 characters).
text8 string	Custom text field (maximum 500 characters).
text9 string	Custom text field (maximum 500 characters).
dn string	Distinguished name given for the enrollment.
validity_period string	The certificate validity period. An ISO 8601 date-time interval or duration indicating the not before and/or not after dates of the certificate. Specify the start date and expiry date as follows 2018-07-06T13:00Z/2019-07-06T09:00:00Z Specify the start date and a duration. Start on July 6, 2018 13:00Z with a lifetime of 1 year and 3 months 2018-07-06T13:00Z/P1Y3M0DT0H0M Specify the expiry date and a duration. Expire on December 31, 2018 with a lifetime of 3 months. Note that the start date will be automatically calculated. P0Y3M0DT0H0M/2018-12-31T00:00Z Specify a duration only. A lifetime of 1 year, 3 months, 10 days, 0 hours and 0 minutes. Note that the start date will always be the current date. P1Y3M10DT0H0M
enrollment_format string	enrollment_format that is X509 or PKCS12. Choices: "X509" "PKCS12"
force boolean	If force=true then a certificate is requested regardless of whether path points to an existing valid certificate. Choices: false ← (default) true
host string / required	Host or IP address for Entrust CAGW.
p12_protection_password string	PKCS12 password for server side generation of the private key and CSR.
path path	The destination path for the generated certificate as a PEM encoded cert. If there is already a certificate at this location and force=true then it will be replaced always. but if force is not specified then we get the certificate validity for existing certificate from Entrust CAGW. If cert_days < remaining_days then only a new certificate will be obtained. If enrollment_format=PKCS12 then it will have Base64 encoded PKCS12 body.
port integer	Port for Entrust CAGW. Default: 443
remaining_days integer	The number of days the certificate must have left being valid. If a certificate is already present at the path and force is not specified then we get the certificate validity for existing certificate from Entrust CAGW. If cert_days < remaining_days then a new certificate will be obtained. The force=true option may be used to ensure that a new certificate is always obtained. Default: 30
request_type string / required	Request type that is new (stands for enrollment), get (stands for get certificate), action (stands for action to be taken on the certificate). Choices: "new" "action" "get"
requester_email string	-The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate. - If requester_email is not provided when connector_name=ECS, module will be failed.
requester_name string	The requester name to associate with certificate tracking information. If requester_name is not provided when connector_name=ECS, module will be failed.
requester_phone string	The requester phone number to associate with certificate tracking information.
serial_no string	Serial number of the already issued certificate.
subject_alt_name dictionary	The subject alternative name identifiers.
directoryName string	directoryName of the target server.
dNSName string	DNS name of the target server.
iPAddress string	IP address of the target server.
rfc822Name string	rfc822 name of the target server.
uniformResourceIdentifier string	URI of the target server.
tracking_info string	Free form tracking information to attach to the record for the certificate.
validate_certs boolean	If set to false then SSL validation with Server is skipped. This should be set to false only for testing purposes. Choices: false true ← (default)

Notes

Note

• path must be specified as the output location of the certificate.

See Also

See also

community.crypto.openssl_privatekey

Can be used to create private keys (both for certificates and accounts).

community.crypto.openssl_csr

Can be used to create a Certificate Signing Request (CSR).

Examples

- name: Request a new certificate from SM via CAGW with bare minimum parameters.  Will request a new certificate
  entrust.crypto.cagw_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    certificate_profile_id: profile_id
    request_type: new
    enrollment_format: X509
    connector_name: SM
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml

- name: Request a new certificate from CAGW with subjectAltName parameters and server cert validation is false
  entrust.crypto.cagw_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    certificate_profile_id: profile_id
    request_type: new
    enrollment_format: X509
    connector_name: SM
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
    validity_period: 2018-07-06T13:00Z/2019-07-06T09:00:00Z
    subject_alt_name:
      dNSName: server.example.com
      iPAddress: 192.168.1.1
      directoryName: cn=john doe,o=example inc,c=us
      uniformResourceIdentifier: http://example.com/
      rfc822Name: server.example.com
    validate_certs: false

- name: Get an already issued certificate from CAGW with valid serial num in hexadecimal format
  entrust.crypto.cagw_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    request_type: get
    serial_no: 5b9ba13d
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml

- name: Request a certificate from CAGW with enrollment format PKCS12
  entrust.crypto.cagw_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    certificate_profile_id: profile_id
    request_type: new
    enrollment_format: PKCS12
    connector_name: SM
    p12_protection_password: 'Password@2023'
    dn: /C=CA/O=iotrust/CN=CA/CN=ans-test-101
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml

- name: Request a new SSL certificate from ECS via CAGW with bare minimum parameters.  Will request a new certificate
  entrust.crypto.cagw_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    certificate_profile_id: profile_id
    request_type: new
    enrollment_format: X509
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
    connector_name: ECS
    requester_name: John-Clark
    requester_email: john.clark@example.com

- name: Request a new SSL certificate from ECS via CAGW with optional custom_field parameters.  Will request a new certificate
  entrust.crypto.cagw_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr: /etc/ssl/csr/ansible.com.csr
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    certificate_profile_id: profile_id
    request_type: new
    enrollment_format: X509
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml
    connector_name: ECS
    requester_name: John-Clark
    requester_email: john.clark@example.com
    custom_fields:
      text1: Admin
      text2: Invoice 25
      number1: 342
      date1: '2018-01-01'
      email1: sales@ansible.testcertificates.com
      dropdown1: red

- name: Take an action(HoldAction) on certificate already recieved from CAGW
  entrust.crypto.cagw_certificate:
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    request_type: action
    action_type: HoldAction
    action_reason: unspecified
    serial_no: 5b9ba13d
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml

- name: Take an action(UnholdAction) on certificate already recieved from CAGW
  entrust.crypto.cagw_certificate:
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    request_type: action
    action_type: UnholdAction
    action_reason: unspecified
    serial_no: 5b9ba13d
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml

- name: Take an action(RevokeAction) on certificate already recieved from CAGW
  entrust.crypto.cagw_certificate:
    cagw_api_client_cert_path: /etc/ssl/entrust/cagw-client.crt
    cagw_api_client_cert_key_path: /etc/ssl/entrust/cagw-client.key
    certificate_authority_id: ca_id
    request_type: action
    action_type: RevokeAction
    action_reason: unspecified
    serial_no: 5b9ba13d
    cagw_api_specification_path: /etc/ssl/entrust/cagw-api.yaml

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
cert_days integer	The number of days the certificate remains valid from now. Returned: success Sample: 253
cert_details dictionary	The full response JSON from the New/Get Certificate call of the CAGW API. While the response contents are guaranteed to be forwards compatible with new CAGW 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
cert_status string	The certificate status in CAGW. Possible values are: ACCEPTED, normal, Revoked, Held Returned: success
filename string	The destination path for the generated certificate or PKCS12. Returned: changed or success Sample: "/etc/ssl/crt/www.ansible.com.crt"
message dictionary	Message we get from CAGW. Returned: success
serial_number string	The serial number of the issued certificate. Returned: success Sample: "5b9ba13d"

Authors

• Sapna Jain (@sapnajainEntrust)

Collection links

• Issue Tracker
• Repository (Sources)