Provided by: pki-base_11.2.1-2_all bug

NAME

       pki-python-client - Dogtag Python Client API

       Dogtag  is  an  enterprise  software  system  designed  to  manage  enterprise  Public Key
       Infrastructure (PKI) deployments.  These pages document the Python client API that can  be
       used  to  interact with Dogtag's REST API to request and issue certificates, store secrets
       in the KRA etc.

PKI PACKAGE

   pki Package
       This module contains top-level classes and functions used by the Dogtag project.

       class pki.Attribute(name, value)
              Bases: object

              Class representing a key/value pair.

              This object is the basis of the representation of a ResourceMessage.

       class pki.AttributeList
              Bases: object

              Class representing a list of attributes.

              This class is needed because of a JavaMapper used in the REST API.

       exception pki.BadRequestException(message, exception=None, code=None, class_name=None)
              Bases: PKIException

              Bad Request Exception: return code = 400

       exception pki.CertNotFoundException(message, exception=None, code=None, class_name=None)
              Bases: ResourceNotFoundException

              Cert Not Found Exception: return code = 404

       exception    pki.ConflictingOperationException(message,     exception=None,     code=None,
       class_name=None)
              Bases: PKIException

              Conflicting Operation Exception: return code = 409

       class pki.FIPS
              Bases: object

              static is_enabled()

       exception pki.ForbiddenException(message, exception=None, code=None, class_name=None)
              Bases: PKIException

              Forbidden Exception: return code = 403

       exception pki.GroupNotFoundException(message, exception=None, code=None, class_name=None)
              Bases: ResourceNotFoundException

              Group Not Found Exception: return code = 404

       exception pki.HTTPGoneException(message, exception=None, code=None, class_name=None)
              Bases: PKIException

              Gone Exception: return code = 410

       exception pki.KeyNotFoundException(message, exception=None, code=None, class_name=None)
              Bases: ResourceNotFoundException

              Key Not Found Exception: return code 404

       exception pki.PKIException(message, exception=None, code=None, class_name=None)
              Bases: Exception, ResourceMessage

              Base exception class for REST Interface

              classmethod from_json(json_value)
                     Construct PKIException from JSON.  :param json_value: JSON representation of
                     the exception.  :type json_value: str :return: pki.PKIException

       exception      pki.ProfileNotFoundException(message,      exception=None,       code=None,
       class_name=None)
              Bases: ResourceNotFoundException

              Profile Not Found Exception: return code = 404

       class pki.PropertyFile(filename, delimiter='=')
              Bases: object

              Class  to  manage  property files  The contents of the property file are maintained
              internally as a list of properties.

              Properties are strings of the format <name> <delimiter> <value> where  '='  is  the
              default delimiter.

              get(name)
                     Get the value of the specified property.

                     Parameters
                            name (str) -- name of property to be fetched.

                     Returns
                            str -- value of property

              index(name)
                     Find the index (position) of a property in a property file.

                     Parameters
                            name (str) -- name of property

                     Returns
                            int -- index of property.

              insert_line(index, line)
                     Insert property into the list of properties maintained by this object at the
                     specified location (index).

                     Parametersindex (int) -- point at which to insert value.

                            • line (str) -- value to be inserted.

                     Returns
                            None

              read() Read from property file into the  list  of  properties  maintained  by  this
                     object.

                     Returns
                            None

              remove(name)
                     Remove property from list of properties maintained by this object.

                     Parameters
                            name (str) -- name of property to be removed.

                     Returns
                            None

              remove_line(index)
                     Remove property at specified index from the properties list.

                     Parameters
                            index (int) -- location of property to be removed.

                     Returns
                            None

              set(name, value, index=None)
                     Set value of specified property.

                     Parametersname (str) -- name of property to set.

                            • value (str) -- value to set

                            • index (int) -- (optional) position of property

                     Returns
                            None

              show() Print  the  contents  of the list of properties maintained by this object to
                     STDOUT.

                     Returns
                            None

              write()
                     Write the list of properties maintained by this object to the property file.

                     Returns
                            None

       exception      pki.RequestNotFoundException(message,      exception=None,       code=None,
       class_name=None)
              Bases: ResourceNotFoundException

              Request Not Found Exception: return code = 404

       class pki.ResourceMessage(class_name)
              Bases: object

              This class is the basis for the various types of key requests.  It is essentially a
              list of attributes.

              add_attribute(name, value)
                     Add an attribute to the list.

                     Parametersname (str) -- name of attribute to add

                            • value (str) -- value to add

                     Returns
                            None

              get_attribute_value(name)
                     Get the value of a given attribute.

                     Parameters
                            name (str) -- name of attribute to retrieve

                     Returns
                            str -- value of parameter

       exception      pki.ResourceNotFoundException(message,      exception=None,      code=None,
       class_name=None)
              Bases: PKIException

              Not Found Exception: return code = 404

       exception pki.UnauthorizedException(message, exception=None, code=None, class_name=None)
              Bases: PKIException

              Unauthorized Exception: return code = 401

       exception pki.UserNotFoundException(message, exception=None, code=None, class_name=None)
              Bases: ResourceNotFoundException

              User Not Found Exception: return code = 404

       pki.convert_x509_name_to_dn(name)
              Convert X.509 Name into NSS-style DN string.

              See                                     also:                                     -
              https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.Name      -
              https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.RelativeDistinguishedName
              -
              https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.NameAttribute
              -
              https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.ObjectIdentifier

              Parameters
                     name (cryptography.x509.Name) -- X.509 Name

              Returns
                     str -- DN string.

       pki.generate_password(charset='0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#*+,-./:;^_|~',
       length=12)
              This function generates FIPS-compliant password.

              See         sftk_newPinCheck()         in         the        following        file:
              https://dxr.mozilla.org/nss/source/nss/lib/softoken/fipstokn.c

              The minimum password length is FIPS_MIN_PIN Unicode characters.

              The password must contain at least 3 character classes:

                     • digits (string.digits)

                     • ASCII lowercase letters (string.ascii_lowercase)

                     • ASCII uppercase letters (string.ascii_uppercase)

                     • ASCII non-alphanumeric characters (PUNCTUATIONS)

                     • non-ASCII characters

              If an ASCII uppercase letter is the first character of the password, the  uppercase
              letter is not counted toward its character class.

              If  a  digit is the last character of the password, the digit is not counted toward
              its character class.

              The     FIPS_MIN_PIN     is      defined      in      the      following      file:
              https://dxr.mozilla.org/nss/source/nss/lib/softoken/pkcs11i.h

              #define FIPS_MIN_PIN 7

       pki.get_info(name)

       pki.handle_exceptions()
              Decorator handling exceptions from REST methods.

       pki.implementation_version()
              Return implementation version.

              Returns
                     str -- implementation version

       pki.specification_version()
              Return specification version.

              Returns
                     str -- specification version

   account Module
       class pki.account.AccountClient(connection, subsystem=None)
              Bases: object

              Class used to associate an authentication session variable with a connection.

              To use this class:

                     • set the authentication credentials with the connection,

                     • create an AccountClient and then call login().

                     • further  operations  in  this  session  will  use  the same authentication
                       credentials without re-authentication.

                     • call logout() to invalidate the session.

              login()
                     Login to account REST interface.  If login is successful, an  authentication
                     session variable is associated with the connection.

                     Returns
                            None

              logout()
                     Logs  out  of the session.  Authentication session variables are invalidated
                     for the connection

                     Returns
                            None

   cert Module
       class pki.cert.CertClient(connection)
              Bases: object

              Class encapsulating and  mirroring  the  functionality  in  the  CertResource  Java
              interface class defining the REST API for Certificate resources.

              approve_request(request_id, cert_review_response=None)
                     Approves a certificate enrollment request.  If cert_review_response is None,
                     a review request operation is  performed  to  fetch  the  CertReviewResponse
                     object.  Requires as agent level authentication.

              assign_request(request_id, cert_review_response)
                     Assigns  a certificate enrollment request.  If cert_review_response is None,
                     a review request operation is  performed  to  fetch  the  CertReviewResponse
                     object.  Requires as agent level authentication.

              cancel_request(request_id, cert_review_response=None)
                     Cancels  a certificate enrollment request.  If cert_review_response is None,
                     a review request operation is  performed  to  fetch  the  CertReviewResponse
                     object.  Requires as agent level authentication.

              create_enrollment_request(profile_id, inputs)
                     Fetches  the enrollment request object for the given profile and sets values
                     to its attributes using  the  values  provided  in  the  inputs  dictionary.
                     Returns the CertEnrollmentRequest object, which can be submitted to enroll a
                     certificate.

              enroll_cert(profile_id, inputs, authority=None)
                     A convenience method for enrolling a certificate for  a  given  profile  id.
                     The  inputs  parameter  should  be  a dictionary with values for the profile
                     attributes for an enrollment request.

                     Calling this method with valid arguments,  creates  an  enrollment  request,
                     submits  it  to  the server, approves the certificate requests generated for
                     the  enrollment  and  returns  a  list  of  CertData  objects  for  all  the
                     certificates generated as part of this enrollment.

                     Note:  This method supports only certificate enrollment where only one agent
                     approval is sufficient.

                     Requires   an   agent   level   authentication.    Returns   a    list    of
                     CertEnrollmentResult objects.

              get_cert(cert_serial_number)
                     Return a CertData object for a particular certificate.

              get_enrollment_template(profile_id)
                     Fetch the enrollment template for the given profile id.  For the first time,
                     the request is sent to  the  server.   The  retrieved  CertEnrollmentRequest
                     object   is   then   cached   locally   for   future  requests.   Returns  a
                     CerEnrollmentRequest object.

              get_request(request_id)
                     Get information of a certificate request with the given request ID.  Returns
                     a CertRequestInfo object.

              hold_cert(cert_serial_number, comments=None, authority=None)
                     Places  a  certificate  on-hold.  Calls the revoke_cert method with reason -
                     CertRevokeRequest.REASON_CERTIFICATE_HOLD.    Returns   a    CertRequestInfo
                     object.   This  method  requires  an  agent's  authentication  cert  in  the
                     connection object.

              list_certs(max_results=None,      max_time=None,       start=None,       size=None,
              **cert_search_params)
                     Return  a  CertDataInfoCollection  object  with  a information about all the
                     certificates that satisfy the search criteria.  If cert_search_request=None,
                     returns all the certificates.

              list_enrollment_templates(start=None, size=None)
                     Gets  the  list  of  profile  templates supported by the CA.  The values for
                     start and size arguments determine the starting point and the length of  the
                     list.  Returns a ProfileDataInfoCollection object.

              list_requests(request_status=None,     request_type=None,     from_request_id=None,
              size=None, max_results=None, max_time=None)
                     Query for a list of certificates using  the  arguments  passed.   Returns  a
                     CertRequestInfoCollection object.

              reject_request(request_id, cert_review_response=None)
                     Rejects  a certificate enrollment request.  If cert_review_response is None,
                     a review request operation is  performed  to  fetch  the  CertReviewResponse
                     object.  Requires as agent level authentication.

              review_cert(cert_serial_number)
                     Reviews  a certificate. Returns a CertData object with a nonce.  This method
                     requires an agent's authentication cert in the connection object.

              review_request(request_id)
                     Reviews a certificate  enrollment  request.   Returns  a  CertReviewResponse
                     object  which contains the nonce from the server needed to perform an action
                     on the request.

              revoke_ca_cert(cert_serial_number,  revocation_reason=None,   invalidity_date=None,
              comments=None, nonce=None, authority=None)
                     Revokes a CA certificate.  Returns a CertRequestInfo object with information
                     about the request.  This method requires an agent's authentication  cert  in
                     the connection object.

              revoke_cert(cert_serial_number,    revocation_reason=None,    invalidity_date=None,
              comments=None, nonce=None, authority=None)
                     Revokes a certificate.  Returns a CertRequestInfo  object  with  information
                     about  the  request.  This method requires an agent's authentication cert in
                     the connection object.

              submit_enrollment_request(enrollment_request, authority=None)
                     Submits  the  CertEnrollmentRequest  object  to  the  server.    Returns   a
                     CertRequestInfoCollection  object  with  information  about  the certificate
                     requests enrolled at the CA.

              unassign_request(request_id, cert_review_response)
                     Un-assigns a certificate enrollment  request.   If  cert_review_response  is
                     None,   a   review   request   operation   is   performed   to   fetch   the
                     CertReviewResponse object.  Requires as agent level authentication.

              unrevoke_cert(cert_serial_number, authority=None)
                     Un-revokes a revoked certificate.  Returns a CertRequestInfo  object.   This
                     method requires an agent's authentication cert in the connection object.

              update_request(request_id, cert_review_response)
                     Updates  a certificate enrollment request.  If cert_review_response is None,
                     a review request operation is  performed  to  fetch  the  CertReviewResponse
                     object.  Requires as agent level authentication.

              validate_request(request_id, cert_review_response)
                     Validates  a  certificate  enrollment  request.   If cert_review_response is
                     None,   a   review   request   operation   is   performed   to   fetch   the
                     CertReviewResponse object.  Requires as agent level authentication.

       class pki.cert.CertData
              Bases: object

              Class containing certificate data as returned from getCert()

              classmethod from_json(attr_list)
                     Return CertData object from JSON dict

              json_attribute_names  =  {'Encoded':  'encoded',  'IssuerDN': 'issuer_dn', 'Nonce':
              'nonce',  'NotAfter':  'not_after',  'NotBefore':  'not_before',  'PKCS7CertChain':
              'pkcs7_cert_chain',  'PrettyPrint': 'pretty_repr', 'Status': 'status', 'SubjectDN':
              'subject_dn', 'id': 'serial_number'}

       class pki.cert.CertDataInfo
              Bases: object

              Class containing information contained in a CertRecord on the  CA.   This  data  is
              returned when searching/listing certificate records.

              classmethod from_json(attr_list)
                     Return CertDataInfo object from JSON dict

              json_attribute_names   =   {'IssuedBy':   'issued_by',   'IssuedOn':   'issued_on',
              'KeyAlgorithmOID': 'key_algorithm_oid', 'KeyLength': 'key_length', 'NotValidAfter':
              'not_valid_after',   'NotValidBefore':   'not_valid_before',   'Status':  'status',
              'SubjectDN':   'subject_dn',   'Type':   'type',   'Version':   'version',    'id':
              'serial_number'}

       class pki.cert.CertDataInfoCollection
              Bases: object

              Class  containing  list  of CertDataInfo objects and their respective link objects.
              This data is returned when searching/listing certificate records in the CA.

              classmethod from_json(json_value)
                     Populate object from JSON input

       class pki.cert.CertEnrollmentRequest(profile_id=None,  renewal=False,  serial_number=None,
       remote_host=None, remote_address=None, inputs=None, outputs=None)
              Bases: object

              This class encapsulates the parameters required for a certificate
                     enrollment request.

              add_input(profile_input)

              add_output(profile_output)

              classmethod from_json(attr_list)

              get_input(profile_input_name)

              get_output(profile_output_name)

              json_attribute_names   =  {'Input':  'inputs',  'Output':  'outputs',  'ProfileID':
              'profile_id',  'RemoteAddress':  'remote_address',   'RemoteHost':   'remote_host',
              'Renewal': 'renewal', 'SerialNumber': 'serial_number'}

              remove_input(profile_input_name)

              remove_output(profile_output_name)

       class pki.cert.CertEnrollmentResult(request, cert)
              Bases: object

              Class containing results of an enrollment request.

              This  structure  contains  information  about  the  cert  request generated and any
              certificates issued.

       class pki.cert.CertRequestInfo
              Bases: object

              An object of this class stores represents a certificate request.

              classmethod from_json(attr_list)

              json_attribute_names      =      {'certId':      'cert_id',      'certRequestType':
              'cert_request_type',   'certURL':   'cert_url',   'errorMessage':  'error_message',
              'operationResult':    'operation_result',    'requestStatus':     'request_status',
              'requestType': 'request_type', 'requestURL': 'request_url'}

       class pki.cert.CertRequestInfoCollection
              Bases: object

              Class  containing  list  of  CertRequestInfo  objects.   This data is returned when
              listing certificate request records in the CA.

              classmethod from_json(json_value)
                     Populate object from JSON input

       class pki.cert.CertRequestStatus
              Bases: object

              Class containing valid cert statuses.

              CANCELED = 'canceled'

              COMPLETE = 'complete'

              PENDING = 'pending'

              REJECTED = 'rejected'

       class  pki.cert.CertReviewResponse(profile_id=None,   renewal=False,   serial_number=None,
       remote_host=None,     remote_address=None,    inputs=None,    outputs=None,    nonce=None,
       request_id=None,     request_type=None,      request_status=None,      request_owner=None,
       request_creation_time=None,       request_modification_time=None,      request_notes=None,
       profile_approval_by=None, profile_set_id=None, profile_is_visible=None, profile_name=None,
       profile_description=None,      profile_remote_host=None,      profile_remote_address=None,
       policy_sets=None)
              Bases: CertEnrollmentRequest

              An object of this class represent the response from the  server  when  reviewing  a
              certificate  enrollment request.  It contains a nonce required to perform action on
              the request.

              classmethod from_json(attr_list)

              json_attribute_names  =  {'Input':  'inputs',  'Output':  'outputs',   'ProfileID':
              'profile_id', 'ProfilePolicySet': 'policy_sets', 'RemoteAddress': 'remote_address',
              'RemoteHost': 'remote_host', 'Renewal': 'renewal', 'SerialNumber': 'serial_number',
              'profileApprovedBy':          'profile_approved_by',          'profileDescription':
              'profile_description',  'profileIsVisible':  'profile_is_visible',   'profileName':
              'profile_name', 'profileRemoteAddr': 'profile_remote_address', 'profileRemoteHost':
              'profile_remote_host',  'profileSetId':  'profile_set_id',   'requestCreationTime':
              'request_creation_time',   'requestId':   'request_id',  'requestModificationTime':
              'request_modification_time',   'requestNotes':   'request_notes',   'requestOwner':
              'request_owner', 'requestStatus': 'request_status', 'requestType': 'request_type'}

       class pki.cert.CertRevokeRequest(nonce, reason=None, invalidity_date=None, comments=None)
              Bases: object

              An  object  of  this  class encapsulates all the parameters required for revoking a
              certificate.

              Valid values for reasons for revoking a request are:
                     'Unspecified',  'Key_Compromise',  'CA_Compromise',   'Affiliation_Changed',
                     'Superseded',          'Cessation_of_Operation',         'Certificate_Hold',
                     'Remove_from_CRL', 'Privilege_Withdrawn', 'AA_Compromise'

              reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affiliation_Changed',
              'Superseded',   'Cessation_of_Operation',   'Certificate_Hold',  'Remove_from_CRL',
              'Privilege_Withdrawn', 'AA_Compromise']

       class pki.cert.CertSearchRequest(**cert_search_params)
              Bases: object

              An object of this class is used to store the search parameters  and  send  them  to
              server.

              search_params       =       {'cert_type_secure_email':       'certTypeSecureEmail',
              'cert_type_ssl_client':        'certTypeSSLClient',         'cert_type_ssl_server':
              'certTypeSSLServer',         'cert_type_sub_email_ca':        'certTypeSubEmailCA',
              'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'common_name': 'commonName', 'country':
              'country',    'email':    'eMail',   'issued_by':   'issuedBy',   'issued_on_from':
              'issuedOnFrom',    'issued_on_to':    'issuedOnTo',     'locality':     'locality',
              'match_exactly':    'matchExactly',    'org':    'org',    'org_unit':   'orgUnit',
              'revocation_reason':      'revocationReason',      'revoked_by':       'revokedBy',
              'revoked_on_from':  'revokedOnFrom', 'revoked_on_to': 'revokedOnTo', 'serial_from':
              'serialFrom',  'serial_to':  'serialTo',  'state':  'state',  'status':   'status',
              'user_id':       'userID',       'valid_not_after_from':       'validNotAfterFrom',
              'valid_not_after_to':          'validNotAfterTo',          'valid_not_before_from':
              'validNotBeforeFrom',  'valid_not_before_to': 'validNotBeforeTo', 'validity_count':
              'validityCount',   'validity_operation':   'validityOperation',    'validity_unit':
              'validityUnit'}

       pki.cert.main()

   client Module
       class    pki.client.PKIConnection(protocol='http',    hostname='localhost',   port='8080',
       subsystem=None, accept='application/json', trust_env=None, verify=True, cert_paths=None)
              Bases: object

              Class to encapsulate the connection between the client and a Dogtag subsystem.

              authenticate(username=None, password=None)
                     Set the parameters used for authentication if  username/password  is  to  be
                     used.   Both  username and password must not be None.  Note that this method
                     only sets the parameters.  Actual authentication occurs when the  connection
                     is attempted,

                     Parametersusername -- username to authenticate connection

                            • password -- password to authenticate connection

                     Returns
                            None

              delete(path, headers=None, use_root_uri=False)
                     Uses python-requests to issue a DEL request to the server.

                     Parameterspath (str) -- path URI for the DEL request

                            • headers (dict) -- headers for the DEL request

                            • use_root_uri  (boolean) -- use root URI instead of subsystem URI as
                              base

                     Returns
                            request.response -- response from the server

                     Raises Exception from python-requests in case the DEL was not successful, or
                            returns an error code.

              get(path,     headers=None,    params=None,    payload=None,    use_root_uri=False,
              timeout=None)
                     Uses python-requests to issue a GET request to the server.

                     Parameterspath (str) -- path URI for the GET request

                            • headers (dict) -- headers for the GET request

                            • params (dict or bytes) -- Query parameters for the GET request

                            • payload (dict, bytes, file-like object) -- data to be sent  in  the
                              body of the request

                            • use_root_uri  (boolean) -- use root URI instead of subsystem URI as
                              base

                     Returns
                            request.response -- response from the server

                     Raises Exception from python-requests in case the GET was not successful, or
                            returns an error code.

              post(path, payload, headers=None, params=None, use_root_uri=False)
                     Uses python-requests to issue a POST request to the server.

                     Parameterspath (str) -- path URI for the POST request

                            • payload  (dict,  bytes, file-like object) -- data to be sent in the
                              body of the request

                            • headers (dict) -- headers for the POST request

                            • params (dict or bytes) -- Query parameters for the POST request

                            • use_root_uri (boolean) -- use root URI instead of subsystem URI  as
                              base

                     Returns
                            request.response -- response from the server

                     Raises Exception  from  python-requests in case the POST was not successful,
                            or returns an error code.

              put(path, payload, headers=None, use_root_uri=False)
                     Uses python-requests to issue a PUT request to the server.

                     Parameterspath (str) -- path URI for the PUT request

                            • payload (dict, bytes, file-like object) -- data to be sent  in  the
                              body of the request

                            • headers (dict) -- headers for the PUT request

                            • use_root_uri  (boolean) -- use root URI instead of subsystem URI as
                              base

                     Returns
                            request.response -- response from the server

                     Raises Exception from python-requests in case the PUT was not successful, or
                            returns an error code.

              set_authentication_cert(pem_cert_path, pem_key_path=None)
                     Set  the path to the PEM file containing the certificate and private key for
                     the client certificate to be used for authentication  to  the  server,  when
                     client   certificate   authentication  is  required.  The  private  key  may
                     optionally be stored in a different path.

                     Parameterspem_cert_path (str) -- path to the PEM file

                            • pem_key_path (str) -- path to the PEM-formatted private key file

                     Returns
                            None

                     Raises Exception if path is empty or None.

       class  pki.client.SSLContextAdapter(pool_connections=10,  pool_maxsize=10,  max_retries=0,
       pool_block=False, verify=True, cert_paths=None)
              Bases: HTTPAdapter

              Custom SSLContext Adapter for requests

              init_poolmanager(connections, maxsize, block=False, **pool_kwargs)
                     Initializes a urllib3 PoolManager.

                     This method should not be called from user code, and is only exposed for use
                     when subclassing the HTTPAdapter.

                     Parametersconnections -- The number of urllib3 connection pools to cache.

                            • maxsize -- The maximum number of connections to save in the pool.

                            • block -- Block when no free connections are available.

                            • pool_kwargs -- Extra keyword arguments used to initialize the  Pool
                              Manager.

       pki.client.catch_insecure_warning(func)
              Temporary silence InsecureRequestWarning

              PKIConnection  is  not able to verify HTTPS connections yet. This decorator catches
              the warning.

              See    https://fedorahosted.org/pki/ticket/1253

       pki.client.main()
              Test code for the PKIConnection class.  :return: None

   crypto Module
       Module containing crypto classes.

       class pki.crypto.CryptoProvider
              Bases: object

              Abstract class containing methods to do cryptographic operations.

              abstract asymmetric_wrap(data, wrapping_cert, mechanism=None)
                     encrypt a symmetric key with the public key of a transport cert.

                     The mechanism is the type of symmetric key, which defaults to a 56 bit  DES3
                     key.

              abstract generate_nonce_iv(mechanism)
                     Create a random initialization vector

              abstract generate_session_key()
                     Generate  a  session  key  to be used for wrapping data to the DRM This must
                     return a 3DES 168 bit key

              abstract generate_symmetric_key(mechanism=None, size=0)
                     Generate and return a symmetric key

              abstract get_cert(cert_nick)
                     Get the certificate for the specified cert_nick.

              abstract get_supported_algorithm_keyset()
                     returns highest supported algorithm keyset

              abstract initialize()
                     Initialization code

              abstract key_unwrap(mechanism, data, wrapping_key, nonce_iv)
                     Unwrap data that has been key wrapped using AES KeyWrap

              abstract set_algorithm_keyset(level)
                     sets required keyset

              abstract symmetric_unwrap(data, wrapping_key, mechanism=None, nonce_iv=None)
                     decrypt data originally encrypted with symmetric key (wrapping key)

                     We expect the data and nonce_iv values to be base64 encoded.  The  mechanism
                     is  the  type  of key used to do the wrapping.  It defaults to a 56 bit DES3
                     key.

              abstract symmetric_wrap(data, wrapping_key, mechanism=None, nonce_iv=None)
                     encrypt data using a symmetric key (wrapping key)

       class      pki.crypto.CryptographyCryptoProvider(transport_cert_nick,      transport_cert,
       backend=<OpenSSLBackend(version: OpenSSL 3.0.7 1 Nov 2022, FIPS: False)>)
              Bases: CryptoProvider

              Class  that defines python-cryptography implementation of CryptoProvider.  Requires
              a PEM file containing the agent cert to be initialized.

              Note that all inputs and outputs are unencoded.

              asymmetric_wrap(data, wrapping_cert, mechanism=None)
                     :param data             Data to be wrapped  :param  wrapping_cert     Public
                     key  to  wrap  data :param mechanism        algorithm of symmetric key to be
                     wrapped

                     Wrap (encrypt) data using the supplied asymmetric key

              generate_nonce_iv(mechanism='AES')
                     Create a random initialization vector

              generate_session_key()
                     Returns a session key to be used when wrapping secrets for the DRM.

              generate_symmetric_key(mechanism=None, size=0)
                     Returns a symmetric key.

              get_cert(cert_nick)
                     :param cert_nick  Nickname for the certificate to be returned.

              get_supported_algorithm_keyset()
                     returns highest supported algorithm keyset

              initialize()
                     Any operations here that need to be performed before crypto operations.

              key_unwrap(mechanism, data, wrapping_key, nonce_iv)
                     :param mechanism        key wrapping mechanism :param data:             data
                     to  unwrap :param wrapping_key:    AES key used to wrap data :param nonce_iv
                     Nonce data :return:                unwrapped data

                     Unwrap the encrypted data which has been wrapped using a KeyWrap mechanism.

              set_algorithm_keyset(level)
                     sets required keyset

              symmetric_unwrap(data, wrapping_key, mechanism=None, nonce_iv=None)
                     :param data            Data to be unwrapped :param wrapping_key    Symmetric
                     key  to  unwrap data :param mechanism       Mechanism to use when unwrapping
                     :param nonce_iv        iv data

                     Unwrap (decrypt) data using the supplied symmetric key

              symmetric_wrap(data, wrapping_key, mechanism=None, nonce_iv=None)
                     :param data            Data to be wrapped :param  wrapping_key     Symmetric
                     key  to  wrap  data :param mechanism       Mechanism to use for wrapping key
                     :param nonce_iv        Nonce for initialization vector

                     Wrap (encrypt) data using the supplied symmetric key

   encoder Module
       pki.encoder.CustomTypeDecoder(dct)

       class      pki.encoder.CustomTypeEncoder(*,       skipkeys=False,       ensure_ascii=True,
       check_circular=True,   allow_nan=True,   sort_keys=False,   indent=None,  separators=None,
       default=None)
              Bases: JSONEncoder

              A custom JSONEncoder class that knows how to encode core custom objects.

              Custom objects are encoded as JSON  object  literals  (ie,  dicts)  with  one  key,
              'TypeName'  where  'TypeName'  is  the  actual name of the type to which the object
              belongs.  That single key maps to another object literal which is just the __dict__
              of the object encoded.

              Reason  for  ignoring the error: E0202 - An attribute affected in json.encoder line
              157 hide this method reported by pylint:

              The error is in json.encoder.JSONEncoder class.  There is a default  method  (which
              is overridden here) and also a class attribute self.default initialized in the init
              method of the class.  The intention of such  usage  being  that  a  custom  default
              method object can be passed to init when creating an instance of JSONEncoder, which
              is then assigned to class's default method. (which is valid) But pylint  raises  an
              issue due to the usage of same name for a method and an attribute in which case the
              attribute definition hides the method.  The reason and example for the issue:  (top
              rated comment)
                 http://stackoverflow.com/questions/12949064/python-what-happens-
                 when-instance-variable-name-is-same-as-method-name

              static attr_name_conversion(attr_dict, object_class)

              default(o)
                     Implement this method in a subclass such  that  it  returns  a  serializable
                     object for o, or calls the base implementation (to raise a TypeError).

                     For  example,  to  support  arbitrary iterators, you could implement default
                     like this:

                        def default(self, o):
                            try:
                                iterable = iter(o)
                            except TypeError:
                                pass
                            else:
                                return list(iterable)
                            # Let the base class default method raise the TypeError
                            return JSONEncoder.default(self, o)

       pki.encoder.decode_cert(data)
              base64 decode X.509 certificate

              Parameters
                     data (str, bytes) -- data as bytes or ASCII text

              Return type
                     bytes

       pki.encoder.encode_cert(data)
              base64 encode X.509 certificate

              Python 3's base64.b64encode() doesn't support ASCII text.

              Parameters
                     data (str, bytes) -- data as bytes or ASCII text

              Return type
                     bytes

   key Module
       Module containing the Python client classes for the KeyClient  and  KeyRequestClient  REST
       API on a DRM

       class          pki.key.AsymKeyGenerationRequest(client_key_id=None,         key_size=None,
       key_algorithm=None, key_usages=None, trans_wrapped_session_key=None, realm=None)
              Bases: ResourceMessage

              Class representing  the  data  sent  to  the  DRM  when  generating  and  archiving
              asymmetric keys in the DRM.

              DECRYPT_USAGE = 'decrypt'

              DERIVE_USAGE = 'derive'

              ENCRYPT_USAGE = 'encrypt'

              SIGN_RECOVER_USAGE = 'sign_recover'

              SIGN_USAGE = 'sign'

              UNWRAP_USAGE = 'unwrap'

              VERIFY_RECOVER_USAGE = 'verify_recover'

              VERIFY_USAGE = 'verify'

              WRAP_USAGE = 'wrap'

       class pki.key.Key(key_data)
              Bases: object

              An  instance  of  this  class  stores  the  decoded encrypted secret present in the
              KeyData object passed in the constructor.  All the key  retrieval  requests  return
              this object.

       class            pki.key.KeyArchivalRequest(client_key_id=None,            data_type=None,
       wrapped_private_data=None,    trans_wrapped_session_key=None,    pki_archive_options=None,
       algorithm_oid=None, symkey_params=None, key_algorithm=None, key_size=None, realm=None)
              Bases: ResourceMessage

              Class representing the object sent to the DRM when archiving a secret.

       class pki.key.KeyClient(connection, crypto, transport_cert_nick=None, info_client=None)
              Bases: object

              Class   that  encapsulates  and  mirrors  the  functions  in  the  KeyResource  and
              KeyRequestResource Java classes in the DRM REST API.

              AES_ALGORITHM = 'AES'

              ASYMMETRIC_KEY_TYPE = 'asymmetricKey'

              DES3_ALGORITHM = 'DES3'

              DESEDE_ALGORITHM = 'DESede'

              DES_ALGORITHM = 'DES'

              DSA_ALGORITHM = 'DSA'

              KEY_STATUS_ACTIVE = 'active'

              KEY_STATUS_INACTIVE = 'inactive'

              PASS_PHRASE_TYPE = 'passPhrase'

              RC2_ALGORITHM = 'RC2'

              RC4_ALGORITHM = 'RC4'

              RSA_ALGORITHM = 'RSA'

              SYMMETRIC_KEY_TYPE = 'symmetricKey'

              approve_request(request_id)
                     Approve a secret recovery request

              archive_encrypted_data(client_key_id,          data_type,           encrypted_data,
              wrapped_session_key,    algorithm_oid=None,    nonce_iv=None,   key_algorithm=None,
              key_size=None, realm=None)
                     Archive a secret (symmetric key or passphrase) on the DRM.

                     Refer  to  archive_key()  comments  for  a  description  of   client_key_id,
                     data_type, key_algorithm and key_size.

                     The following parameters are also required:

                            • encrypted_data  - which is the data encrypted by a session key (168
                              bit 3DES symmetric key)

                            • wrapped_session_key - the above session  key  wrapped  by  the  DRM
                              transport certificate public key.

                            • the algorithm_oid string for the symmetric key wrap

                            • the nonce_iv for the symmetric key wrap

                     This  function is useful if the caller wants to do their own wrapping of the
                     secret, or if the secret was generated on a separate client machine and  the
                     wrapping was done there.

                     The function returns a KeyRequestResponse object containing a KeyRequestInfo
                     object with details about the archival request and key archived.

              archive_key(client_key_id,     data_type,     private_data,     key_algorithm=None,
              key_size=None, realm=None)
                     Archive a secret (symmetric key or passphrase) on the DRM.

                     Requires a user-supplied client ID.  There can be only one active key with a
                     specified client ID.  If a record for  a  duplicate  active  key  exists,  a
                     BadRequestException is thrown.

                     data_type can be one of the following:
                            KeyClient.SYMMETRIC_KEY_TYPE,          KeyClient.ASYMMETRIC_KEY_TYPE,
                            KeyClient.PASS_PHRASE_TYPE

                     key_algorithm and key_size are applicable to  symmetric  keys  only.   If  a
                     symmetric key is being archived, these parameters are required.

                     private_data  is the raw secret to be archived.  It will be wrapped and sent
                     to the DRM.

                     The function returns a KeyRequestResponse object containing a KeyRequestInfo
                     object with details about the archival request and key archived.

              archive_pki_options(client_key_id,          data_type,         pki_archive_options,
              key_algorithm=None, key_size=None, realm=None)
                     Archive a secret (symmetric key or passphrase) on the DRM.

                     Refer  to  archive_key()  comments  for  a  description  of   client_key_id,
                     data_type, key_algorithm and key_size.

                     pki_archive_options   is   the   data   to   be   archived   wrapped   in  a
                     PKIArchiveOptions structure,

                     The function returns a KeyRequestResponse object containing a KeyRequestInfo
                     object with details about the archival request and key archived.

              cancel_request(request_id)
                     Cancel a secret recovery request

              generate_asymmetric_key(client_key_id,  algorithm=None, key_size=None, usages=None,
              trans_wrapped_session_key=None, realm=None)
                     Generate and archive asymmetric keys in the DRM.   Supports  algorithms  RSA
                     and  DSA.  Valid key size for RSA = 256 + (16 * n), where n: 0-496 Valid key
                     size for DSA = 512, 768, 1024. p,q,g params are not supported.

                     Return a KeyRequestResponse which  contains  a  KeyRequestInfo  object  that
                     describes the URL for the request and generated keys.

              generate_symmetric_key(client_key_id,   algorithm=None,   size=None,   usages=None,
              trans_wrapped_session_key=None, realm=None)
                     Generate and archive a symmetric key on the DRM.

                     Return a KeyRequestResponse which  contains  a  KeyRequestInfo  object  that
                     describes the URL for the request and generated key.

              get_active_key_info(client_key_id)
                     Get the info in the KeyRecord for the active secret in the DRM.

              get_client_keyset()

              get_key_info(key_id)
                     Get the info in the KeyRecord for a specific secret in the DRM.

              get_request_info(request_id)
                     Return a KeyRequestInfo object for a specific request.

              get_server_keyset()

              list_keys(client_key_id=None,    status=None,    max_results=None,   max_time=None,
              start=None, size=None, realm=None)
                     List/Search archived secrets in the DRM.

                     See  KRAClient.list_keys  for  the  valid  values  of  status.   Returns   a
                     KeyInfoCollection object.

              list_requests(request_state=None,       request_type=None,      client_key_id=None,
              start=None, page_size=None, max_results=None, max_time=None, realm=None)
                     List/Search key requests in the DRM.

                     See KRAClient.list_requests  for  the  valid  values  of  request_state  and
                     request_type.  Returns a KeyRequestInfoCollection object.

              modify_key_status(key_id, status)
                     Modify the status of a key

              process_returned_key(key, session_key)
                     Decrypt the returned key and place in key.data

                     The  data  will either by encrypted using an encryption algorithm - in which
                     case, the key data will contain an encryption algorithm OID, or it  will  be
                     key  wrapped - in which case, the key data will contain a key wrap mechanism
                     name.

                     Only one of these should be present.  If we are talking to an older  server,
                     and none is present, we will assume encryption.

              recover_key(key_id,        request_id=None,        session_wrapped_passphrase=None,
              trans_wrapped_session_key=None, b64certificate=None, nonce_data=None)
                     Create a request to recover a secret.

                     To retrieve a symmetric key  or  passphrase,  the  only  parameter  that  is
                     required  is  the  keyId.   It is possible (but not required) to pass in the
                     session keys/passphrase and nonceData for the retrieval at this time.  Those
                     parameters are documented in the docstring for retrieve_key below.

                     To  retrieve  an  asymmetric  key,  the  keyId  and  the the base-64 encoded
                     certificate is required.

              reject_request(request_id)
                     Reject a secret recovery request.

              retrieve_key(key_id=None, trans_wrapped_session_key=None, request_id=None)
                     Retrieve a secret (passphrase or symmetric key) from the DRM.

                     This method will retrieve a key from the KRA given the key_id or  request_id
                     (one  of which must be specified).  The data is returned as a KeyData object
                     (which is recast to a Key object).

                     If request_id is specified, then the value of key_id is ignored.  Exceptions
                     will  be  thrown  if the caller is not the originator of the request, or the
                     request is not approved.

                     If key_id is specified instead, the following behavior applies:

                     • If the key can be retrieved synchronously - ie. only one agent's  approval
                       is required, then the KeyData will include the secret.

                     • If  the  key  cannot  be  retrieved  synchronously  - ie. if more than one
                       approval is needed, then the KeyData object will include  the  request  ID
                       for  a recovery request that was created on the server.  When that request
                       is approved, callers can retrieve the key using retrieve_key() and setting
                       the request_id.

                     To ensure data security in transit, the data will be returned encrypted by a
                     session  key  (168  bit  3DES  symmetric  key)  -  which  is  first  wrapped
                     (encrypted)  by the public key of the DRM transport certificate before being
                     sent to the DRM.  The parameter  trans_wrapped_session_key  refers  to  this
                     wrapped session key.

                     If  the trans_wrapped_session_key is not provided by caller, the method will
                     call CryptoProvider methods to generate  and  wrap  the  session  key.   The
                     function  will return the KeyData object with a private_data attribute which
                     stores the unwrapped key information.

                     If the trans_wrapped_session_key is provided by the caller, the method  will
                     simply  pass  the data to the KRA, and will return the secret wrapped in the
                     session key.  The secret will still need to be unwrapped by the caller.  The
                     function  will  return  the  KeyData  object,  where  the  KeyData structure
                     includes the wrapped secret and some nonce data to be used as  a  salt  when
                     unwrapping.

              retrieve_key_by_passphrase(key_id=None,      request_id=None,      passphrase=None,
              trans_wrapped_session_key=None, session_wrapped_passphrase=None, nonce_data=None)
                     Retrieve a secret (passphrase  or  symmetric  key)  from  the  DRM  using  a
                     passphrase.

                     This  function  generates a key recovery request, approves it, and retrieves
                     the secret referred to by key_id.  This assumes that only  one  approval  is
                     required to authorize the recovery.

                     The  secret  is  secured in transit by wrapping the secret with a passphrase
                     using PBE encryption.

                     There are two ways of using this function:

                     1. A passphrase is provided by the caller.

                        In this case, CryptoProvider methods will be called to create the data to
                        securely send the passphrase to the DRM.  Basically, three pieces of data
                        will be sent:

                        • the passphrase wrapped by a 168 bit 3DES  symmetric  key  (the  session
                          key).  This is referred to as the parameter session_wrapped_passphrase.

                        • the  session  key  wrapped  with  the  public  key in the DRM transport
                          certificate.  This is referred to as the trans_wrapped_session_key.

                        • ivps nonce data, referred to as nonce_data

                        The function will return the tuple (KeyData, unwrapped_secret)

                     2. The      caller       provides       the       trans_wrapped_session_key,
                        session_wrapped_passphrase and nonce_data.

                        In  this  case,  the data will simply be passed to the DRM.  The function
                        will return the secret encrypted by the passphrase using PBE  Encryption.
                        The secret will still need to be decrypted by the caller.

                        The function will return the tuple (KeyData, None)

              retrieve_key_by_pkcs12(key_id, certificate, passphrase)
                     Retrieve an asymmetric private key and return it as PKCS12 data.

                     This  function  generates a key recovery request, approves it, and retrieves
                     the secret referred to by key_id in a PKCS12 file.  This assumes  that  only
                     one approval is required to authorize the recovery.

                     This  function  requires  the following parameters: - key_id : the ID of the
                     key - certificate:  the  certificate  associated  with  the  private  key  -
                     passphrase: A passphrase for the pkcs12 file.

                     The function returns a KeyData object.

              retrieve_key_data(data)
                     Retrieve a secret from the DRM.

                     @param: data - a KeyRecoveryRequest containing the keyId of the secret being
                     retrieved, the request_id of the approved recovery request  and  a  wrapping
                     mechanism.  More details at KRAClient.retrieve_key.

                     Returns a KeyData object containing the wrapped secret.

              set_crypto_algorithms()

              set_transport_cert(transport_cert_nick)
                     Set the transport certificate for crypto operations

              submit_request(request)
                     Submit an archival, recovery or key generation request to the DRM.

                     @param   request   -  is  either  a  KeyArchivalRequest,  KeyRecoverRequest,
                     SymKeyGenerationRequest or AsymKeyGenerationRequest.

                     returns a KeyRequestResponse object.

       class pki.key.KeyData
              Bases: object

              This is the object that contains the encoded wrapped secret  when  that  secret  is
              retrieved.  It  is  used  by  the  DRM  to  send  information of the key in the key
              retrieval requests.

              classmethod from_json(attr_list)
                     Return a KeyData object from a JSON dict

              json_attribute_names     =     {'encryptAlgorithmOID':     'encrypt_algorithm_oid',
              'nonceData':  'nonce_data',  'publicKey':  'public_key', 'requestID': 'request_id',
              'wrapAlgorithm': 'wrap_algorithm', 'wrappedPrivateData': 'wrapped_private_data'}

       class pki.key.KeyInfo
              Bases: object

              This is the object that contains information stored in the database record  for  an
              archived secret.  It does not contain the secret itself.

              classmethod from_json(attr_list)
                     Return KeyInfo from JSON dict

              get_key_id()
                     Return the key ID as parsed from key URL

              json_attribute_names   =   {'clientKeyID':  'client_key_id',  'keyURL':  'key_url',
              'ownerName': 'owner_name', 'publicKey': 'public_key'}

       class pki.key.KeyInfoCollection
              Bases: object

              This class represents data  returned  when  searching  the  DRM  archived  secrets.
              Essentially, its a list of KeyInfo objects.

              classmethod from_json(json_value)
                     Return a KeyInfoCollection object from its JSON representation

       class               pki.key.KeyRecoveryRequest(key_id=None,               request_id=None,
       trans_wrapped_session_key=None,     session_wrapped_passphrase=None,      nonce_data=None,
       certificate=None,               passphrase=None,               payload_wrapping_name=None,
       payload_encryption_oid=None)
              Bases: ResourceMessage

              Class representing the data sent to the DRM when either creating a request for  the
              recovery of a secret, or, once the request is approved, retrieving the secret.

       class pki.key.KeyRequestInfo
              Bases: object

              This  class  represents data about key requests (archival, recovery, key generation
              etc.) in the DRM.

              classmethod from_json(attr_list)
                     Return a KeyRequestInfo object from a JSON dict.

              get_key_id()
                     Return the ID of the secret referred to by this request.

              get_request_id()
                     Return the request ID by parsing the request URL.

              json_attribute_names =  {'keyURL':  'key_url',  'requestStatus':  'request_status',
              'requestType': 'request_type', 'requestURL': 'request_url'}

       class pki.key.KeyRequestInfoCollection
              Bases: object

              This class represents the data returned when searching the key requests in the DRM.
              Essentially, its a list of KeyRequestInfo objects.

              classmethod from_json(json_value)
                     Return a KeyRequestInfoCollection object from its JSON representation.

       class pki.key.KeyRequestResponse
              Bases: object

              This class is returned when an archival, recovery  or  key  generation  request  is
              created.   It  includes  a KeyRequestInfo object with information about the created
              request, and a KeyData  structure  which  contains  the  wrapped  secret  (if  that
              operation is supported).

              classmethod from_json(json_value)
                     Return a KeyRequestResponse object from its JSON representation.

              get_key_id()
                     Return the id for the key archived, recovered or generated

              get_request_id()
                     Return the id for the created request

       class pki.key.RequestId(req_id)
              Bases: object

              Class representing a Request ID

       class          pki.key.SymKeyGenerationRequest(client_key_id=None,          key_size=None,
       key_algorithm=None, key_usages=None, trans_wrapped_session_key=None, realm=None)
              Bases: ResourceMessage

              Class representing the data sent  to  the  DRM  when  generating  and  archiving  a
              symmetric key in the DRM.

              DECRYPT_USAGE = 'decrypt'

              ENCRYPT_USAGE = 'encrypt'

              SIGN_USAGE = 'sign'

              UNWRAP_USAGE = 'unwrap'

              VERIFY_USAGE = 'verify'

              WRAP_USAGE = 'wrap'

       pki.key.main()
              Some unit tests - basically printing different types of requests

   kra Module
       Module  containing  KRAClient  class.   This  class  should  be  used by Python clients to
       interact with the DRM to expose the functionality of the KeyClient and  KeyRequestResource
       REST APIs.

       class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
              Bases: object

              Client  class that models interactions with a KRA using the Key and KeyRequest REST
              APIs.

   profile Module
       class     pki.profile.Descriptor(syntax=None,      constraint=None,      description=None,
       default_value=None)
              Bases: object

              This class represents the description of a ProfileAttribute.  It stores information
              such as the syntax, constraint and default value of a profile attribute.

              classmethod from_json(attr_list)

              json_attribute_names     =     {'Constraint':     'constraint',     'DefaultValue':
              'default_value', 'Description': 'description', 'Syntax': 'syntax'}

       class     pki.profile.PolicyConstraint(name=None,     description=None,     class_id=None,
       policy_constraint_values=None)
              Bases: object

              An object of this class contains the policy constraints applied to  a  ProfileInput
              used by a certificate enrollment request.

              add_constraint_value(policy_constraint_value)
                     Add a PolicyConstraintValue to the policy_constraint_values list.

              classmethod from_json(attr_list)

              get_constraint_value(policy_constraint_value_name)
                     Returns  a PolicyConstraintValue object with the given name.  None, if there
                     is no match.

              json_attribute_names      =       {'classId':       'class_id',       'constraint':
              'policy_constraint_values', 'id': 'name'}

              remove_constraint_value(policy_constraint_value_name)
                     Removes   a   PolicyConstraintValue   with   the   given   name   form   the
                     policy_constraint_values list.

       class pki.profile.PolicyConstraintValue(name=None, value=None, descriptor=None)
              Bases: object

              Represents a PolicyConstraintValue

              classmethod from_json(attr_list)

              property name

       class      pki.profile.PolicyDefault(name=None,      class_id=None,      description=None,
       policy_attributes=None, policy_params=None)
              Bases: object

              An  object  of  this  class contains information of the default usage of a specific
              ProfileInput.

              add_attribute(policy_attribute)
                     Add a policy attribute to the attribute list.  @param policy_attribute  -  A
                     ProfileAttribute object

              add_parameter(policy_parameter)
                     Add a profile parameter to the parameters list.  @param policy_parameter - A
                     ProfileParameter object.

              classmethod from_json(attr_list)

              get_attribute(policy_attribute_name)
                     Fetch the policy attribute with the given name from the attributes list.

              get_parameter(profile_parameter_name)
                     Fetch a profile parameter with the given name from the parameters list.

              json_attribute_names   =   {'classId':   'class_id',   'id':   'name',    'params':
              'policy_params', 'policyAttribute': 'policy_attributes'}

              remove_attribute(policy_attribute_name)
                     Remove a policy attribute with the given name from the attributes list.

              remove_parameter(profile_parameter_name)
                     Remove a profile parameter with the given name from the parameters list.

       class pki.profile.PolicySet(name=None, policy_list=None)
              Bases: object

              An  object  of  this  class  contains  a name value pair of the policy name and the
              ProfilePolicy object.

              add_policy(profile_policy)
                     Add a ProfilePolicy object to the policy_list

              classmethod from_json(attr_list)

              get_policy(policy_id)
                     Returns a ProfilePolicy object with the given profile id.

              json_attribute_names = {'id': 'name', 'value': 'policy_list'}

              remove_policy(policy_id)
                     Removes a ProfilePolicy with the given ID from the PolicySet.

       class pki.profile.PolicySetList(policy_sets=None)
              Bases: object

              An object of this class stores a list of ProfileSet objects.

              add_policy_set(policy_set)
                     Add a PolicySet object to the policy_sets list.

              classmethod from_json(attr_list)

              get_policy_set(policy_set_name)
                     Fetch the PolicySet object for the given name.  Returns None, if not found.

              property policy_sets

              remove_policy_set(policy_set_name)
                     Remove a PolicySet object with the given name from the policy_sets list.

       class  pki.profile.Profile(profile_id=None,  class_id=None,  name=None,  description=None,
       enabled=None,         visible=None,         enabled_by=None,        authenticator_id=None,
       authorization_acl=None,   renewal=None,   xml_output=None,   inputs=None,    outputs=None,
       policy_set_list=None, link=None)
              Bases: object

              This class represents an enrollment profile.

              add_input(profile_input)
                     Add a ProfileInput object to the inputs list of the Profile.

              add_output(profile_output)
                     Add a ProfileOutput object to the outputs list of the Profile.

              add_policy_set(policy_set)
                     Add a PolicySet object to the policy_sets list of the Profile.

              classmethod from_json(attr_list)

              get_input(profile_input_id)
                     Fetches  a  ProfileInput  with  the given ProfileInput id.  Returns None, if
                     there is no matching input.

              get_output(profile_output_id)
                     Fetches a ProfileOutput with the given ProfileOutput id.  Returns  None,  if
                     there is no matching output.

              get_policy_set(policy_set_name)
                     Fetches  a  ProfileInput  with  the given ProfileInput id.  Returns None, if
                     there is no matching input.

              static get_profile_data_from_file(path_to_file)
                     Reads the file for the serialized Profile object.  Currently  supports  only
                     data format in json.

              json_attribute_names  =  {'Input':  'inputs',  'Output':  'outputs',  'PolicySets':
              'policy_set_list',     'authenticatorId':      'authenticator_id',      'authzAcl':
              'authorization_acl',   'classId':   'class_id',  'enabledBy':  'enabled_by',  'id':
              'profile_id', 'xmlOutput': 'xml_output'}

              remove_input(profile_input_id)
                     Remove a ProfileInput from the inputs list of the Profile.

              remove_output(profile_output_id)
                     Remove a ProfileOutput from the outputs list of the Profile.

              remove_policy_set(policy_set_name)
                     Remove a PolicySet from the policy_sets list of the Profile.

       class pki.profile.ProfileAttribute(name=None, value=None, descriptor=None)
              Bases: object

              Represents a profile attribute of a ProfileInput.

              classmethod from_json(attr_list)

              json_attribute_names = {'Descriptor': 'descriptor', 'Value': 'value'}

       class pki.profile.ProfileClient(connection)
              Bases: object

              This class consists of methods for accessing the ProfileResource.

              create_profile(profile_data)
                     Create a new profile for the given Profile object.

              create_profile_from_file(path_to_file)
                     Reads the file for the serialized  Profile  object.   Performs  the  profile
                     create operation.  Currently supports only data format in json.

              delete_profile(profile_id)
                     Delete a profile with the given Profile Id.

              disable_profile(profile_id)
                     Disables a profile.

              enable_profile(profile_id)
                     Enables a profile.

              get_profile(profile_id)
                     Fetches  information  for  the  profile for the given profile id.  Returns a
                     ProfileData object.

              list_profiles(start=None, size=None)
                     Fetches the  list  of  profiles.   The  start  and  size  arguments  provide
                     pagination support.  Returns a ProfileDataInfoCollection object.

              modify_profile(profile_data)
                     Modify an existing profile with the given Profile object.

              modify_profile_from_file(path_to_file)
                     Reads  the  file  for  the  serialized Profile object.  Performs the profile
                     modify operation.  Currently supports only data format in json.

       class pki.profile.ProfileDataInfo
              Bases: object

              Stores information about a profile

              classmethod from_json(attr_list)

              json_attribute_names = {'profileDescription':  'profile_description',  'profileId':
              'profile_id', 'profileName': 'profile_name', 'profileURL': 'profile_url'}

       class pki.profile.ProfileDataInfoCollection
              Bases: object

              Represents  a  collection  of ProfileDataInfo objects.  Also encapsulates the links
              for the list of the objects stored.

              classmethod from_json(attr_list)

       class pki.profile.ProfileInput(profile_input_id=None, class_id=None, name=None, text=None,
       attributes=None, config_attributes=None)
              Bases: object

              This  class  encapsulates  all  the  attributes of a profile to generate a specific
              property of a certificate.  Ex. Subject name, Requestor Information etc.

              add_attribute(profile_attribute)
                     Add a ProfileAttribute object to the attributes list.

              add_config_attribute(profile_attribute)
                     Add a ProfileAttribute object to the config_attributes list.

              classmethod from_json(attr_list)

              get_attribute(profile_attribute_name)
                     Returns a ProfileAttribute object for the given name.  None, if no match.

              get_config_attribute(config_attribute_name)
                     Returns a ProfileAttribute object with the given name.  None, if there is no
                     match in the config_attributes list.

              json_attribute_names   =   {'Attribute':   'attributes',   'ClassID':   'class_id',
              'ConfigAttribute':  'config_attributes',  'Name':  'name',  'Text':  'text',  'id':
              'profile_input_id'}

              remove_attribute(profile_attribute_name)
                     Remove  a  ProfileAttribute  object  with the given name from the attributes
                     list.

              remove_config_attribute(config_attribute_name)
                     Remove  a  ProfileAttribute  object   with   the   given   name   from   the
                     config_attributes list.

       class      pki.profile.ProfileOutput(profile_output_id=None,     name=None,     text=None,
       class_id=None, attributes=None)
              Bases: object

              This class defines the output of a certificate enrollment request using a profile.

              add_attribute(profile_attribute)
                     Add a ProfileAttribute object to the attributes list.

              classmethod from_json(attr_list)

              get_attribute(profile_attribute_name)
                     Returns a ProfileAttribute object for the given name.  None, if no match.

              json_attribute_names = {'classId': 'class_id', 'id': 'profile_output_id'}

              remove_attribute(profile_attribute_name)
                     Remove a ProfileAttribute object with the given  name  from  the  attributes
                     list.

       class pki.profile.ProfileParameter(name=None, value=None)
              Bases: object

              classmethod from_json(attr_list)

       class            pki.profile.ProfilePolicy(policy_id=None,            policy_default=None,
       policy_constraint=None)
              Bases: object

              This class represents the policy a profile adheres to.  An  object  of  this  class
              stores  the default values for profile and the constraints present on the values of
              the attributes of the profile submitted for an enrollment request.

              classmethod from_json(attr_list)

              json_attribute_names = {'constraint': 'policy_constraint', 'def': 'policy_default',
              'id': 'policy_id'}

       class pki.profile.ProfilePolicySet
              Bases: object

              Stores a list of ProfilePolicy objects.

              classmethod from_json(attr_list)

       pki.profile.main()

   system Module
       class pki.system.AdminSetupRequest
              Bases: object

       class pki.system.AdminSetupResponse
              Bases: object

       class pki.system.CertificateSetupRequest
              Bases: object

       class pki.system.CertificateSetupResponse
              Bases: object

       class pki.system.DomainInfo
              Bases: object

              Class  representing  the  entire  security  domain.   This is essentially a list of
              SecurityDomainSubsystem components.

              classmethod from_json(json_value)
                     Create a DomainInfo object from JSON.

                     Parameters
                            json_value (str) -- JSON representation of a security domain.

                     Returns
                            DomainInfo

              property systems

       class pki.system.InstallToken
              Bases: object

              classmethod from_json(json_value)

       class pki.system.SecurityDomainClient(connection)
              Bases: object

              Client used to get the security domain from a security domain CA.   The  connection
              details  for the security domain CA are specified in a PKIConnection object used to
              construct this client.

              get_domain_info()
                     Contact the security domain CA specified in the connection  object  used  to
                     construct this client and get the security domain using the REST API.

                     Returns
                            pki.system.DomainInfo

              get_install_token(hostname, subsystem)

                     Returns
                            pki.system.InstallToken

              get_old_domain_info()
                     Contact  the  security  domain CA specified in the connection object used to
                     construct  this  client  and  get  the  security  domain   using   the   old
                     servlet-based  interface.  This method is useful when contacting old servers
                     which do not provide the REST API.

                     Returns
                            pki.system.DomainInfo

              get_security_domain_info()

       class pki.system.SecurityDomainHost
              Bases: object

              Class representing a security domain host.

              classmethod from_json(json_value)
                     Constructs a SecurityDomainHost object from JSON.

                     Parameters
                            json_value (str) -- JSON string representing a security domain host.

                     Returns
                            SecurityDomainHost

       class pki.system.SecurityDomainSubsystem
              Bases: object

              Class representing a security domain subsystem.  This  is  essentially  a  list  of
              SecurityDomainHost  objects  of  a  particular  subsystem  type (ca, kra, tps, tks,
              ocsp).

              classmethod from_json(json_value)
                     Constructs a SecurityDomainSubsystem from a JSON representation.

                     Parameters
                            json_value (str)  --  JSON  representation  of  the  Security  Domain
                            Subsystem

                     Returns
                            SecurityDomainSubsystem

              get_host(hostname, secure_port)

       class pki.system.SystemCertData
              Bases: object

              Class  used  to  represent  the data for a system certificate, which is used in the
              data passed into and  returned  from  the  Java  installation  servlet  during  the
              execution of pkispawn.

              This     class     is    the    python    equivalent    of    the    Java    class:
              com.netscape.certsrv.system.SystemCertData

       class pki.system.SystemConfigClient(connection, subsystem=None)
              Bases: object

              Client used to interact with the Java configuration servlet to configure  a  Dogtag
              subsystem during the execution of pkispawn.

              The  connection  details  for  the  system  being  configured  are  passed  in  the
              PKIConnection object used when constructing this object.

              createCert(request)
                     Create certificate.

                     Parameters
                            request (CertificateSetupRequest) -- Certificate setup request

                     Returns
                            SystemCertData

              createCertID(request)
                     Create certificate ID.

                     Parameters
                            request (CertificateSetupRequest) -- Certificate setup request

                     Returns
                            SystemCertData

              createRequestID(request)
                     Create certificate request ID.

                     Parameters
                            request (CertificateSetupRequest) -- Certificate setup request

                     Returns
                            SystemCertData

              initSubsystem(request)
                     Initialize subsystem.

                     Parameters
                            request (CertificateSetupRequest) -- Certificate setup request

       class pki.system.SystemStatusClient(connection, subsystem=None)
              Bases: object

              Client used to check the status of a Dogtag subsystem.

              get_status(timeout=None)
                     Checks the status of the subsystem by calling the getStatus() servlet.  This
                     is  used  to  determine if the server is up and ready to receive and process
                     requests.

                     Returns
                            str - getStatus response

   systemcert Module
       Module containing the Python client classes for the SystemCert REST API

       class pki.systemcert.SystemCertClient(connection, subsystem=None)
              Bases: object

              Class encapsulating and mirroring the functionality in the SystemCertResource  Java
              interface class defining the REST API for system certificate resources.

              get_transport_cert()
                     Return transport certificate.

                     Returns
                            pki.cert.CertData -- transport certificate data

   upgrade Module
       class pki.upgrade.PKIUpgradeScriptlet
              Bases: object

              backup(path)

              get_backup_dir()

              upgrade_system()

       class         pki.upgrade.PKIUpgradeTracker(name,         filename,         delimiter='=',
       version_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
              Bases: object

              get_index()

              get_version()

              remove()

              remove_index()

              remove_version()

              set(version)

              set_index(index)

              set_version(version)

              show()

       class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade')
              Bases: object

              all_versions()

              backup(scriptlet, path)

              copydirs(source, dest, force=False)

              copyfile(source, dest, force=False)

              get_current_version()

              get_target_version()

              get_tracker()

              init_scriptlet(scriptlet)

              is_complete()

              makedirs(path, exist_ok=False)

              record(scriptlet, path)

              remove_tracker()

              reset_tracker()

              revert()

              revert_scriptlet(scriptlet)

              revert_version(version)

              run_scriptlet(scriptlet)

              scriptlets(version)

              set_tracker(version)

              show_tracker()

              status()

              touch(path)

              update_tracker(scriptlet)

              upgrade()

              upgrade_version(version)

              validate()

              version_dir(version)

              versions()

   util Module
       Module containing utility functions and classes for the Dogtag python code

       class pki.util.Version(obj)
              Bases: object

       pki.util.chmod(path, mode)
              Change permissions of a file, link, or folder recursively.

       pki.util.chown(path, uid, gid)
              Change ownership of a file, link, or folder recursively.

       pki.util.copy(source, dest, uid=-1, gid=-1, dir_mode=None, file_mode=None, force=False)
              Copy a file or a folder and its contents.

       pki.util.copydirs(source, dest, uid=-1, gid=-1, mode=None, force=False)
              Copy a folder and  its  parents  (without  the  contents)  while  preserving  their
              attributes.

       pki.util.copyfile(source,  dest,  slots=None,  params=None, uid=None, gid=None, mode=None,
       force=False)
              Copy a file or link while preserving its attributes.

       pki.util.copytree(src, dst, symlinks=False, ignore=None)
              Recursively copy a directory tree using copy2().

              PATCH: This code was copied from 'shutil.py' and patched to
                     allow 'The destination directory to already exist.'

              If exception(s) occur, an Error is raised with a list of reasons.

              If the optional symlinks flag is true, symbolic links in the source tree result  in
              symbolic  links  in the destination tree; if it is false, the contents of the files
              pointed to by symbolic links are copied.

              The optional ignore argument is a callable. If given, it is  called  with  the  src
              parameter,  which  is the directory being visited by copytree(), and names which is
              the list of src contents, as returned by os.listdir():
                 callable(src, names) -> ignored_names

              Since copytree() is called recursively, the callable will be called once  for  each
              directory  that is copied. It returns a list of names relative to the src directory
              that should not be copied.

              Consider this example code rather than the ultimate tool.

       pki.util.customize_file(input_file, output_file, params)
              Customize a file with specified parameters.

       pki.util.load_properties(filename, properties)

       pki.util.makedirs(path, mode=511, exist_ok=False, uid=-1, gid=-1, force=False)

       pki.util.read_environment_files(env_file_list=None)

       pki.util.read_text(message,       options=None,        default=None,        delimiter=':',
       case_sensitive=True, password=False, required=False)
              Get  an  input from the user. This is used, for example, in pkispawn and pkidestroy
              to obtain user input.

              Parametersmessage (str) -- prompt to display to the user

                     • options (list) -- list of possible inputs by the user.

                     • default (str) -- default value of parameter being prompted.

                     • delimiter (str) -- delimiter to be used at the end of the prompt.

                     • case_sensitive  (boolean  --  True/False)  --  Allow  input  to  be   case
                       sensitive.

                     • password  (boolean  --  True/False) -- Input is a password. Don't show the
                       value.

                     • required (boolean -- True/False) -- Input must be non-empty.

              Returns
                     str -- value obtained from user input.

       pki.util.remove(path, force=False)

       pki.util.replace_params(line, params=None)
              Replace all occurrences of [param] in the line with the value of the parameter.

       pki.util.rmtree(path, force=False)

       pki.util.set_property(properties, name, value)

       pki.util.store_properties(filename, properties)

       pki.util.symlink(source, dest, uid=-1, gid=-1, force=False)

       pki.util.unlink(link, force=False)IndexModule IndexSearch Page

AUTHOR

       Dogtag PKI Project Team

COPYRIGHT

       2023, Dogtag PKI Team

@APPLICATION_VERSION@                      Feb 10, 2023                      PKI-PYTHON-CLIENT(1)