Certificate

class Certificate(api)

Bases: FeatureBase

associate_application(certificate, applications, push_to_new=False)

Associates an application object to a certificate object.

Parameters
create(name, parent_folder, description=None, contacts=None, approvers=None, management_type=None, service_generated_csr=None, generate_key_on_application=None, hash_algorithm=None, common_name=None, organization=None, organization_unit=None, city=None, state=None, country=None, san_dns=None, san_email=None, san_upn=None, san_ip=None, san_uri=None, key_algorithm=None, key_strength=None, elliptic_curve=None, ca_template=None, disable_automatic_renewal=None, renewal_window=None, attributes=None, get_if_already_exists=True)

Note

The certificate is not automatically requested. Use renew() to obtain a certificate.

Parameters

  • name (str) – Name of the Certificate object.

  • parent_folder (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the parent folder.

  • description (str) – Description of the certificate object.

  • contacts (List[Union[ident.Identity, str]]) – List of Identity Object or Prefixed Name of the contacts for this certificate.

  • approvers (List[Union[ident.Identity, str]]) – List of Identity Object or Prefixed Name of the approvers for this certificate.

  • management_type (str) – Certificate management type.

  • service_generated_csr (bool) – If True, TPP generates the CSR.

  • generate_key_on_application (bool) – If True, the key/CSR are generated on the target application.

  • hash_algorithm (str) – Hash algorithm.

  • common_name (str) – Common name (CN) of the certificate.

  • organization (str) – Organization of the certificate.

  • organization_unit (List[str]) – Organization units (OU) of the certificate.

  • city (str) – City.

  • state (str) – State.

  • country (str) – Country code.

  • san_dns (List[str]) – List of Subject Alternative Names for DNS.

  • san_email (List[str]) – List of Subject Alternative Names for e-mail addresses.

  • san_upn (List[str]) – List of Subject Alternative Names for UPN.

  • san_ip (List[str]) – List of Subject Alternative Names for IP addresses.

  • san_uri (List[str]) – List of Subject Alternative Names for URI.

  • key_algorithm (str) – Signing key algorithm.

  • key_strength (int) – Key strength in bits.

  • elliptic_curve (str) – Elliptic curve.

  • ca_template (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the Certificate Authority template.

  • disable_automatic_renewal (bool) – If True, disables automatic renewal.

  • renewal_window (int) – Number of days that make the renewal window.

  • attributes (dict) – Additional attributes that define this certificate.

  • get_if_already_exists (bool) – If the objects already exists, just return it as is.

Returns

Config Object

delete(certificate)

Deletes the certificate object from TPP.

Parameters

certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

details(certificate)
Parameters

certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

Returns

CertificateDetails

dissociate_application(certificate, applications, delete_orphans=False)

Dissociate an application object from a certificate.

Parameters
download(format, certificate=None, friendly_name=None, include_chain=False, include_private_key=False, keystore_password=None, password=None, root_first_order=False, vault_id=None, timeout=60, poll_interval=0.5)

Downloads a certificate and returns the encoded content, filename, and format as a single object. If vault_id is provided, then that specific version of a certificate is downloaded, which is particularly useful when trying to download historical certificates.

Attempts to download the certificate occur every poll_interval seconds for up to a timeout threshold. This is because the certificate may be currently processing and not ready for download.

Parameters

  • format (str) – One of the following: * Base64 * Base64 (PKCS #8) * DER * JKS * PKCS #7 * PKCS #12

  • certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object. Not required if using vault id.

  • friendly_name (str) – Label or alias for the given format.

  • include_chain (bool) – Include parent or root chain.

  • include_private_key (bool) – Include the private key.

  • keystore_password (str) – JKS Keystore password.

  • password (str) – Password.

  • root_first_order (bool) – If True, show root certificate first, followed by intermediate, and finally the end entity certificate.

  • vault_id (int) – If provided, downloads the certificate with the given Vault ID. Use this when trying to download historical certificates. Not required if using certificate config object.

  • timeout (int) – Timeout threshold in seconds until a TimeoutError is raised.

  • poll_interval (float) – Time in seconds to attempt a retry of downloading the certificate.

Returns

A DownloadedCertificate with these properties

  • certificate_data str - Encoded certificate data.

  • format str - File Format.

  • filename str - File name.

get(certificate_dn, raise_error_if_not_exists=True)
Parameters

  • certificate_dn (str) – Distinguished Name (DN) of the certificate object.

  • raise_error_if_not_exists (bool) – Raise an exception if the object DN does not exist.

Returns

Config Object

get_previous_versions(certificate, exclude_expired=False, exclude_revoked=False)
Parameters

  • certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

  • exclude_expired (bool) – If True, do not include expired certificates.

  • exclude_revoked (bool) – If True, do not include revoked certificates.

Returns

List[PreviousVersions]

get_validation_results(certificate)
Parameters

certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

Returns

Tuple[File, SslTls]

list(country=None, certificate_type=None, common_name=None, issuer=None, is_self_signed=None, is_wild_card=None, key_algorithm=None, key_size=None, key_size_greater=None, key_size_less=None, city=None, organization=None, organization_unit=None, state=None, san_dns=None, san_email=None, san_ip=None, san_upn=None, san_uri=None, serial=None, signature_algorithm=None, thumbprint=None, valid_from=None, valid_from_greater=None, valid_from_less=None, valid_to=None, valid_to_greater=None, chain_validation_error=None, created_on=None, created_on_greater=None, created_on_less=None, disabled=None, in_error=None, management_type=None, name=None, network_validation_disabled=None, parent_folder=None, recursive=True, pending_workflow=None, ssl_tls_protocol=None, stage=None, stage_greater=None, stage_less=None, tls_validation_failure=None, validation_disabled=None, validation_state=None, valid_to_less=None, additional_filters=None, limit=1000, offset=None, return_limit=False, include_issuer=None, include_key_algorithm=None, include_key_size=None, include_subject=None, concurrency=16, cap=None)

Lists all certificates with the given parameters. Some parameters allow a union of values:

  • If datetime, then the ISO format is used.

  • If a list of strings, then each value is joined by an ampersand (&) and appended to the query string.

  • If a list of a tuple of strings, then each value in the tuple is joined by a comma (,) and each tuple in the list is joined by an ampersand (&), and the whole joined to the query string.

Refer to the Venafi TPP WebSDK Documentation for detailed parameter descriptions.

Parameters

  • country (Union[str, List[str], List[Tuple[str, ...]]]) – Country attribute of the Subject DN.

  • certificate_type (Union[str, List[str], List[Tuple[str, ...]]]) – Use CodeSigning, Device, Server, and/or User.

  • common_name (Union[str, List[str], List[Tuple[str, ...]]]) – CN of the Subject DN.

  • issuer (Union[str, List[str], List[Tuple[str, ...]]]) – Issuer.

  • is_self_signed (bool) – Include only self-signed (True) or CA-signed (False) certificates.

  • is_wild_card (bool) – Include only certificates that have wild card notation (True) or those that do not (False).

  • key_algorithm (Union[str, List[str], List[Tuple[str, ...]]]) – Public key algorithm.

  • key_size (Union[str, List[str], List[Tuple[str, ...]]]) – Public key size.

  • key_size_greater (Union[str, List[str], List[Tuple[str, ...]]]) – Minimum key size, non-inclusive.

  • key_size_less (Union[str, List[str], List[Tuple[str, ...]]]) – Maximum key size, inclusive.

  • city (Union[str, List[str], List[Tuple[str, ...]]]) – City attribute of the Subject DN.

  • organization (Union[str, List[str], List[Tuple[str, ...]]]) – Organization attribute of the Subject DN.

  • organization_unit (Union[str, List[str], List[Tuple[str, ...]]]) – Organization Unit attribute of the Subject DN.

  • state (Union[str, List[str], List[Tuple[str, ...]]]) – State attribute of the Subject DN.

  • san_dns (Union[str, List[str], List[Tuple[str, ...]]]) – SAN DNS of the certificate.

  • san_email (Union[str, List[str], List[Tuple[str, ...]]]) – SAN E-mail of the certificate.

  • san_ip (Union[str, List[str], List[Tuple[str, ...]]]) – SAN IP of the certificate.

  • san_upn (Union[str, List[str], List[Tuple[str, ...]]]) – SAN UPN of the certificate.

  • san_uri (Union[str, List[str], List[Tuple[str, ...]]]) – SAN URI of the certificate.

  • serial (Union[str, List[str], List[Tuple[str, ...]]]) – Serial number of the certificate.

  • signature_algorithm (Union[str, List[str], List[Tuple[str, ...]]]) – Signature algorithm used to sign the certificate.

  • thumbprint (Union[str, List[str], List[Tuple[str, ...]]]) – Certificate thumbprint.

  • valid_from (Union[datetime, str]) – Issuance date of the certificate.

  • valid_from_greater (Union[datetime, str]) – Minimum expiration date of the certificate.

  • valid_from_less (Union[datetime, str]) – Maximum expiration date of the certificate.

  • valid_to (Union[datetime, str]) – Expiration date of the certificate.

  • valid_to_greater (Union[datetime, str]) – Minimum expiration date of the certificate.

  • valid_to_less (Union[datetime, str]) – Maximum expiration date of the certificate.

  • chain_validation_error (Union[str, List[str], List[Tuple[str, ...]]]) – Chain Validation Error code.

  • created_on (Union[datetime, str]) – Creation date of the certificate.

  • created_on_greater (Union[datetime, str]) – Minimum creation date of the certificate.

  • created_on_less (Union[datetime, str]) – Maximum creation date of the certificate.

  • disabled (bool) – Include only enabled (False) or disabled (True) certificates.

  • in_error (bool) – Include only certificates in an error state (True) or a healthy state (False).

  • management_type (Union[str, List[str], List[Tuple[str, ...]]]) – Management type (Unassigned, Monitoring, Enrollment, or Provisioning) of the certificate.

  • name (Union[str, List[str], List[Tuple[str, ...]]]) – Name of the certificate object.

  • network_validation_disabled (bool) – Include only certificates with Network Validation enabled (False) or disabled (True).

  • parent_folder (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the parent folder.

  • recursive (bool) – Requires parent to be given. If True, search for certificates recursively.

  • pending_workflow (bool) – Include only certificates pending workflow resolution.

  • ssl_tls_protocol (Union[str, List[str], List[Tuple[str, ...]]]) – SSL/TLS Protocols (Ssl2, Ssl3, Tls, Tls11, Tls12) that failed to communicate with the target host.

  • stage (Union[str, List[str], List[Tuple[str, ...]]]) – Processing stage of the certificate.

  • stage_greater (str) – Minimum processing stage of the certificate.

  • stage_less (str) – Maximum processing stage of the certificate.

  • tls_validation_failure (Union[str, List[str], List[Tuple[str, ...]]]) – TLS Validation Failure code.

  • validation_disabled (bool) – Include only certificates with validation enabled (False) or disabled (True).

  • validation_state (Union[str, List[str], List[Tuple[str, ...]]]) – Include only certificates having a validation state of “Blank”, “Success”, or “Failure”.

  • additional_filters (Dict[str, str]) – A dictionary of additional filters as would be passed directly to the GET Certificates API.

  • limit (int) – The maximum number of certificates to return.

  • offset (int) – The offset from the filtered list that will be the first item of the returned list of certificates. Obsolete if return_limit is False.

  • include_issuer (bool) – Show the DN of the issuing CA.

  • include_key_algorithm (bool) – Show the public key algorithm.

  • include_key_size (bool) – Show the public key size.

  • include_subject (bool) – Show the certificate subject DN.

  • return_limit (bool) – If True, then only one API call is sent to the server and the amount of certificates up to the limit will be returned. If False then return all certificates that apply to the given filters.

  • concurrency (int) – When return_limit is False, then this is the amount of threads to spawn when querying for certificates. This is done by first submitting a HEAD Certificates request to get the count of certificates that apply to the filters and then by creating a thread pool for as many offsets are required to retrieve the total amount of certificates.

  • cap (int) – When the desired amount of certificates exceeds the desired limit, the cap defines how many certificates from the offset and beyond the limit to retrieve. For example, with offset=10, limit=200, and cap=400, then certificates 10 thru 410 will be returned at a rate of 200 retrievals.

Returns

List[Certificate]

push_to_applications(certificate, applications=None)

Pushes the active certificate to the applications.

Parameters
renew(certificate, csr=None, re_enable=False)

Renews or requests a certificate.

Parameters

  • certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

  • csr (str) – If provided, uploads the PKCS10 CSR to TPP to send to the CA. If not provided, TPP generates the CSR.

  • re_enable (bool) – The action to control a previously disabled certificate: If False, do not renew a previously disabled certificate. If True, clear the Disabled attribute, re-enable, and then renew the certificate (in this request).

Returns

The current thumbprint of the active certificate. This should be used when checking the renewal status to ensure that TPP has registered a new certificate to its vault with a new thumbprint.

Return type

str

reset(certificate)

Resets the certificate to a non-processing state. No attempt to reprocess the certificate renewal is made.

Parameters

certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

retry_from_current_stage(certificate)

Retries renewal from the current processing stage of the certificate.

Parameters

certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

retry_from_stage_0(certificate)

Retries renewal from stage 0. This clears all current processing data and restarts processing.

Parameters

certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

revoke(certificate, comments=None, disable=None, reason=None, thumbprint=None)

Revokes the certificate. If a thumbprint is provided, then the particular historical certificate associated to the certificate having that thumbprint will be revoked.

Parameters

  • certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

  • comments (str) – Any comments to include in the revoke request.

  • disable (bool) – If True, disables the certificate object.

  • reason (int) – Reason for revoking.

  • thumbprint (str) – If given, the thumbprint of the historical certificate to be revoked.

upload(certificate_data, parent_folder, certificate_authority_attributes=None, name=None, password=None, private_key_data=None, reconcile=False)

Uploads the certificate data to TPP to create a certificate object under the given parent folder DN. If the BEGIN/END header or footer is missing, the data is assumed to be Base 64 encoded in the PKCS#12 format. For Base 64 encoded certificates, characters, such as spaces and new line escape characters (/n), are optional. White space characters are removed before any attempt is made to decode the certificate.

Parameters

  • certificate_data (str) – Encoded certificate data.

  • parent_folder (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the parent folder.

  • certificate_authority_attributes (dict) – Attributes pertaining to the Certificate Authority to store with the certificate object. This is not a DN to a Certificate Authority in TPP.

  • name (str) – If given, the name of the new certificate object. If not given, then the Common Name is used.

  • password (str) – Password to decrypt the private key.

  • private_key_data (str) – Encoded private key data.

  • reconcile (bool) – If False, replaces the current certificate, if it exists, and stores the current certificate as a historical certificate. If True, then TPP activates the certificate with the newest “ValidFrom” date and archives the other certificate as a historical certificate.

Returns

Config Object of the uploaded certificate.

validate(certificates)

Performs SSL/TLS network validation of certificate on all applications associated to certificate that are not disabled.

Parameters

certificates (List[Union[config.Object, str]]) – List of Config Object or Distinguished Name (DN) to validate.

Returns

Tuple of Distinguished Name (DN) and validation warnings

Return type

Tuple[str, List[str]]

wait_for_enrollment_to_complete(certificate, current_thumbprint, timeout=60, poll_interval=0.5)

Waits for the certificate renewal to complete over a period of timeout seconds. The current_thumbprint is returned by renew(). Renewal is complete when the current_thumbprint does not match the new thumbprint and either the processing stage is “None” or greater than or equal to 800, which is the start of the provisioning stage. If the certificate management type is set to Provisioning, use the application feature wait_for_installation_to_complete().

Parameters

  • certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

  • current_thumbprint (str) – Thumbprint of the current certificate object.

  • timeout (int) – Timeout in seconds before raising an error.

  • poll_interval (float) – Interval to poll TPP for the renewal status.

Returns

CertificateDetails

wait_for_stage(certificate, stage, expect_workflow=True, timeout=60, poll_interval=1)

Waits for the current processing of the certificate to reach the given stage over a period of timeout seconds. If the timeout is reached, an error is raised.

Parameters

  • certificate (Union[config.Object, str]) – Config Object or Distinguished Name (DN) of the certificate object.

  • stage (int) – Stage at which to return

  • expect_workflow (bool) – If True, validates that a Ticket DN has been issued to the certificate.

  • timeout (int) – Timeout in seconds before throwing an error.

  • poll_interval (int) – Interval to poll TPP for the renewal status.

Returns

The values returned by the TPP WebSDK API, namely

  • approver (List[str]) - List of approvers on the certificate object.

  • certificate_details (CertificateDetails) - Certificate details.

  • contact (List[str]) - List of contacts on the certificate object.

  • created_on (datetime) - Date on which the certificate object was created.

  • custom_fields (List[dict]) - Custom fields on the certificate object.

  • dn (str) - Distinguished Name (DN) of the certificate object.

  • guid (str) - GUID of the certificate object.

  • name (str) - Name of the certificate object.

  • parent_dn (str) - Parent Distinguished Name (DN) of the certificate object.

  • processing_details (ProcessingDetails) - Certificate processing details.

  • renewal_details (RenewalDetails) - Certificate renewal settings details.

  • schema_class (str) - Schema class.

  • validation_details (ValidationDetails) - Certificate validation details.