1PKI-PYTHON-CLIENT(1) Dogtag Certificate System PKI-PYTHON-CLIENT(1)
2
6 pki-python-client - Dogtag Python Client API
7 Dogtag is an enterprise software system designed to manage enterprise
9 Public Key Infrastructure (PKI) deployments. These pages document the
10 Python client API that can be used to interact with Dogtag's REST API
11 to request and issue certificates, store secrets in the KRA etc.
12
14 pki Package
15 This module contains top-level classes and functions used by the Dogtag
16 project.
17 class pki.Attribute(name, value)
19 Bases: object
20 Class representing a key/value pair.
22 This object is the basis of the representation of a ResourceMes‐
24 sage.
25 class pki.AttributeList
27 Bases: object
28 Class representing a list of attributes.
30 This class is needed because of a JavaMapper used in the REST
32 API.
33 exception pki.BadRequestException(message, exception=None, code=None,
35 class_name=None)
36 Bases: pki.PKIException
37 Bad Request Exception: return code = 400
39 exception pki.CertNotFoundException(message, exception=None, code=None,
41 class_name=None)
42 Bases: pki.ResourceNotFoundException
43 Cert Not Found Exception: return code = 404
45 exception pki.ConflictingOperationException(message, exception=None,
47 code=None, class_name=None)
48 Bases: pki.PKIException
49 Conflicting Operation Exception: return code = 409
51 class pki.FIPS
53 Bases: object
54 static is_enabled()
56 exception pki.ForbiddenException(message, exception=None, code=None,
58 class_name=None)
59 Bases: pki.PKIException
60 Forbidden Exception: return code = 403
62 exception pki.GroupNotFoundException(message, exception=None,
64 code=None, class_name=None)
65 Bases: pki.ResourceNotFoundException
66 Group Not Found Exception: return code = 404
68 exception pki.HTTPGoneException(message, exception=None, code=None,
70 class_name=None)
71 Bases: pki.PKIException
72 Gone Exception: return code = 410
74 exception pki.KeyNotFoundException(message, exception=None, code=None,
76 class_name=None)
77 Bases: pki.ResourceNotFoundException
78 Key Not Found Exception: return code 404
80 class pki.Link
82 Bases: object
83 Stores the information of the resteasy's Link object sent by
85 the server for a resource.
86 classmethod from_json(attr_list)
88 Generate Link from JSON
89 Parameters
91 attr_list (str) -- JSON representation of Link
92 Returns
94 pki.Link
95 exception pki.PKIException(message, exception=None, code=None,
97 class_name=None)
98 Bases: Exception, pki.ResourceMessage
99 Base exception class for REST Interface
101 classmethod from_json(json_value)
103 Construct PKIException from JSON. :param json_value:
104 JSON representation of the exception. :type json_value:
105 str :return: pki.PKIException
106 exception pki.ProfileNotFoundException(message, exception=None,
108 code=None, class_name=None)
109 Bases: pki.ResourceNotFoundException
110 Profile Not Found Exception: return code = 404
112 class pki.PropertyFile(filename, delimiter='=')
114 Bases: object
115 Class to manage property files The contents of the property
117 file are maintained internally as a list of properties.
118 Properties are strings of the format <name> <delimiter> <value>
120 where '=' is the default delimiter.
121 get(name)
123 Get the value of the specified property.
124 Parameters
126 name (str) -- name of property to be fetched.
127 Returns
129 str -- value of property
130 index(name)
132 Find the index (position) of a property in a property
133 file.
134 Parameters
136 name (str) -- name of property
137 Returns
139 int -- index of property.
140 insert_line(index, line)
142 Insert property into the list of properties maintained by
143 this object at the specified location (index).
144 Parameters
146 • index (int) -- point at which to insert value.
148 • line (str) -- value to be inserted.
150 Returns
152 None
153 read() Read from property file into the list of properties main‐
155 tained by this object.
156 Returns
158 None
159 remove(name)
161 Remove property from list of properties maintained by
162 this object.
163 Parameters
165 name (str) -- name of property to be removed.
166 Returns
168 None
169 remove_line(index)
171 Remove property at specified index from the properties
172 list.
173 Parameters
175 index (int) -- location of property to be removed.
176 Returns
178 None
179 set(name, value, index=None)
181 Set value of specified property.
182 Parameters
184 • name (str) -- name of property to set.
186 • value (str) -- value to set
188 • index (int) -- (optional) position of property
190 Returns
192 None
193 show() Print the contents of the list of properties maintained
195 by this object to STDOUT.
196 Returns
198 None
199 write()
201 Write the list of properties maintained by this object to
202 the property file.
203 Returns
205 None
206 exception pki.RequestNotFoundException(message, exception=None,
208 code=None, class_name=None)
209 Bases: pki.ResourceNotFoundException
210 Request Not Found Exception: return code = 404
212 class pki.ResourceMessage(class_name)
214 Bases: object
215 This class is the basis for the various types of key requests.
217 It is essentially a list of attributes.
218 add_attribute(name, value)
220 Add an attribute to the list.
221 Parameters
223 • name (str) -- name of attribute to add
225 • value (str) -- value to add
227 Returns
229 None
230 get_attribute_value(name)
232 Get the value of a given attribute.
233 Parameters
235 name (str) -- name of attribute to retrieve
236 Returns
238 str -- value of parameter
239 exception pki.ResourceNotFoundException(message, exception=None,
241 code=None, class_name=None)
242 Bases: pki.PKIException
243 Not Found Exception: return code = 404
245 exception pki.UnauthorizedException(message, exception=None, code=None,
247 class_name=None)
248 Bases: pki.PKIException
249 Unauthorized Exception: return code = 401
251 exception pki.UserNotFoundException(message, exception=None, code=None,
253 class_name=None)
254 Bases: pki.ResourceNotFoundException
255 User Not Found Exception: return code = 404
257 pki.convert_x509_name_to_dn(name)
259 Convert X.509 Name into NSS-style DN string.
260 See also: -
262 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.Name
263 -
264 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.RelativeDistinguishedName
265 -
266 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.NameAttribute
267 -
268 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.ObjectIdentifier
269 Parameters
271 name (cryptography.x509.Name) -- X.509 Name
272 Returns
274 str -- DN string.
275 pki.generate_password(charset='0123456789abcdefghijklmnopqrstuvwxyz‐
277 ABCDEFGHIJKLMNOPQRSTUVWXYZ!#*+,-./:;^_|~', length=12)
278 This function generates FIPS-compliant password.
279 See sftk_newPinCheck() in the following file:
281 https://dxr.mozilla.org/nss/source/nss/lib/softoken/fipstokn.c
282 The minimum password length is FIPS_MIN_PIN Unicode characters.
284 The password must contain at least 3 character classes:
286 • digits (string.digits)
288 • ASCII lowercase letters (string.ascii_lowercase)
290 • ASCII uppercase letters (string.ascii_uppercase)
292 • ASCII non-alphanumeric characters (PUNCTUATIONS)
294 • non-ASCII characters
296 If an ASCII uppercase letter is the first character of the pass‐
298 word, the uppercase letter is not counted toward its character
299 class.
300 If a digit is the last character of the password, the digit is
302 not counted toward its character class.
303 The FIPS_MIN_PIN is defined in the following file:
305 https://dxr.mozilla.org/nss/source/nss/lib/softoken/pkcs11i.h
306 #define FIPS_MIN_PIN 7
308 pki.get_info(name)
310 pki.handle_exceptions()
312 Decorator handling exceptions from REST methods.
313 pki.implementation_version()
315 Return implementation version.
316 Returns
318 str -- implementation version
319 pki.specification_version()
321 Return specification version.
322 Returns
324 str -- specification version
325 account Module
327 class pki.account.AccountClient(connection, subsystem=None)
328 Bases: object
329 Class used to associate an authentication session variable with
331 a connection.
332 To use this class:
334 • set the authentication credentials with the connection,
336 • create an AccountClient and then call login().
338 • further operations in this session will use the same
340 authentication credentials without re-authentication.
341 • call logout() to invalidate the session.
343 login()
345 Login to account REST interface. If login is successful,
346 an authentication session variable is associated with the
347 connection.
348 Returns
350 None
351 logout()
353 Logs out of the session. Authentication session vari‐
354 ables are invalidated for the connection
355 Returns
357 None
358 cert Module
360 class pki.cert.CertClient(connection)
361 Bases: object
362 Class encapsulating and mirroring the functionality in the
364 CertResource Java interface class defining the REST API for Cer‐
365 tificate resources.
366 approve_request(request_id, cert_review_response=None)
368 Approves a certificate enrollment request. If cert_re‐
369 view_response is None, a review request operation is per‐
370 formed to fetch the CertReviewResponse object. Requires
371 as agent level authentication.
372 assign_request(request_id, cert_review_response)
374 Assigns a certificate enrollment request. If cert_re‐
375 view_response is None, a review request operation is per‐
376 formed to fetch the CertReviewResponse object. Requires
377 as agent level authentication.
378 cancel_request(request_id, cert_review_response=None)
380 Cancels a certificate enrollment request. If cert_re‐
381 view_response is None, a review request operation is per‐
382 formed to fetch the CertReviewResponse object. Requires
383 as agent level authentication.
384 create_enrollment_request(profile_id, inputs)
386 Fetches the enrollment request object for the given pro‐
387 file and sets values to its attributes using the values
388 provided in the inputs dictionary. Returns the CertEn‐
389 rollmentRequest object, which can be submitted to enroll
390 a certificate.
391 enroll_cert(profile_id, inputs, authority=None)
393 A convenience method for enrolling a certificate for a
394 given profile id. The inputs parameter should be a dic‐
395 tionary with values for the profile attributes for an en‐
396 rollment request.
397 Calling this method with valid arguments, creates an en‐
399 rollment request, submits it to the server, approves the
400 certificate requests generated for the enrollment and re‐
401 turns a list of CertData objects for all the certificates
402 generated as part of this enrollment.
403 Note: This method supports only certificate enrollment
405 where only one agent approval is sufficient.
406 Requires an agent level authentication. Returns a list
408 of CertEnrollmentResult objects.
409 get_cert(cert_serial_number)
411 Return a CertData object for a particular certificate.
412 get_enrollment_template(profile_id)
414 Fetch the enrollment template for the given profile id.
415 For the first time, the request is sent to the server.
416 The retrieved CertEnrollmentRequest object is then cached
417 locally for future requests. Returns a CerEnrollmentRe‐
418 quest object.
419 get_request(request_id)
421 Get information of a certificate request with the given
422 request ID. Returns a CertRequestInfo object.
423 hold_cert(cert_serial_number, comments=None, authority=None)
425 Places a certificate on-hold. Calls the revoke_cert
426 method with reason - CertRevokeRequest.REASON_CERTIFI‐
427 CATE_HOLD. Returns a CertRequestInfo object. This
428 method requires an agent's authentication cert in the
429 connection object.
430 list_certs(max_results=None, max_time=None, start=None,
432 size=None, **cert_search_params)
433 Return a CertDataInfoCollection object with a information
434 about all the certificates that satisfy the search crite‐
435 ria. If cert_search_request=None, returns all the cer‐
436 tificates.
437 list_enrollment_templates(start=None, size=None)
439 Gets the list of profile templates supported by the CA.
440 The values for start and size arguments determine the
441 starting point and the length of the list. Returns a
442 ProfileDataInfoCollection object.
443 list_requests(request_status=None, request_type=None, from_re‐
445 quest_id=None, size=None, max_results=None, max_time=None)
446 Query for a list of certificates using the arguments
447 passed. Returns a CertRequestInfoCollection object.
448 reject_request(request_id, cert_review_response=None)
450 Rejects a certificate enrollment request. If cert_re‐
451 view_response is None, a review request operation is per‐
452 formed to fetch the CertReviewResponse object. Requires
453 as agent level authentication.
454 review_cert(cert_serial_number)
456 Reviews a certificate. Returns a CertData object with a
457 nonce. This method requires an agent's authentication
458 cert in the connection object.
459 review_request(request_id)
461 Reviews a certificate enrollment request. Returns a
462 CertReviewResponse object which contains the nonce from
463 the server needed to perform an action on the request.
464 revoke_ca_cert(cert_serial_number, revocation_reason=None, inva‐
466 lidity_date=None, comments=None, nonce=None, authority=None)
467 Revokes a CA certificate. Returns a CertRequestInfo ob‐
468 ject with information about the request. This method re‐
469 quires an agent's authentication cert in the connection
470 object.
471 revoke_cert(cert_serial_number, revocation_reason=None, invalid‐
473 ity_date=None, comments=None, nonce=None, authority=None)
474 Revokes a certificate. Returns a CertRequestInfo object
475 with information about the request. This method requires
476 an agent's authentication cert in the connection object.
477 submit_enrollment_request(enrollment_request, authority=None)
479 Submits the CertEnrollmentRequest object to the server.
480 Returns a CertRequestInfoCollection object with informa‐
481 tion about the certificate requests enrolled at the CA.
482 unassign_request(request_id, cert_review_response)
484 Un-assigns a certificate enrollment request. If cert_re‐
485 view_response is None, a review request operation is per‐
486 formed to fetch the CertReviewResponse object. Requires
487 as agent level authentication.
488 unrevoke_cert(cert_serial_number, authority=None)
490 Un-revokes a revoked certificate. Returns a CertRe‐
491 questInfo object. This method requires an agent's au‐
492 thentication cert in the connection object.
493 update_request(request_id, cert_review_response)
495 Updates a certificate enrollment request. If cert_re‐
496 view_response is None, a review request operation is per‐
497 formed to fetch the CertReviewResponse object. Requires
498 as agent level authentication.
499 validate_request(request_id, cert_review_response)
501 Validates a certificate enrollment request. If cert_re‐
502 view_response is None, a review request operation is per‐
503 formed to fetch the CertReviewResponse object. Requires
504 as agent level authentication.
505 class pki.cert.CertData
507 Bases: object
508 Class containing certificate data as returned from getCert()
510 classmethod from_json(attr_list)
512 Return CertData object from JSON dict
513 json_attribute_names = {'Encoded': 'encoded', 'IssuerDN': 'is‐
515 suer_dn', 'Link': 'link', 'Nonce': 'nonce', 'NotAfter': 'not_af‐
516 ter', 'NotBefore': 'not_before', 'PKCS7CertChain':
517 'pkcs7_cert_chain', 'PrettyPrint': 'pretty_repr', 'Status':
518 'status', 'SubjectDN': 'subject_dn', 'id': 'serial_number'}
519 class pki.cert.CertDataInfo
521 Bases: object
522 Class containing information contained in a CertRecord on the
524 CA. This data is returned when searching/listing certificate
525 records.
526 classmethod from_json(attr_list)
528 Return CertDataInfo object from JSON dict
529 json_attribute_names = {'IssuedBy': 'issued_by', 'IssuedOn':
531 'issued_on', 'KeyAlgorithmOID': 'key_algorithm_oid',
532 'KeyLength': 'key_length', 'Link': 'link', 'NotValidAfter':
533 'not_valid_after', 'NotValidBefore': 'not_valid_before', 'Sta‐
534 tus': 'status', 'SubjectDN': 'subject_dn', 'Type': 'type', 'Ver‐
535 sion': 'version', 'id': 'serial_number'}
536 class pki.cert.CertDataInfoCollection
538 Bases: object
539 Class containing list of CertDataInfo objects and their respec‐
541 tive link objects. This data is returned when searching/listing
542 certificate records in the CA.
543 classmethod from_json(json_value)
545 Populate object from JSON input
546 class pki.cert.CertEnrollmentRequest(profile_id=None, renewal=False,
548 serial_number=None, remote_host=None, remote_address=None, inputs=None,
549 outputs=None)
550 Bases: object
551 This class encapsulates the parameters required for a certifi‐
553 cate
554 enrollment request.
555 add_input(profile_input)
557 add_output(profile_output)
559 classmethod from_json(attr_list)
561 get_input(profile_input_name)
563 get_output(profile_output_name)
565 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
567 'ProfileID': 'profile_id', 'RemoteAddress': 'remote_address',
568 'RemoteHost': 'remote_host', 'Renewal': 'renewal', 'SerialNum‐
569 ber': 'serial_number'}
570 remove_input(profile_input_name)
572 remove_output(profile_output_name)
574 class pki.cert.CertEnrollmentResult(request, cert)
576 Bases: object
577 Class containing results of an enrollment request.
579 This structure contains information about the cert request gen‐
581 erated and any certificates issued.
582 class pki.cert.CertRequestInfo
584 Bases: object
585 An object of this class stores represents a certificate request.
587 classmethod from_json(attr_list)
589 json_attribute_names = {'certId': 'cert_id', 'certRequestType':
591 'cert_request_type', 'certURL': 'cert_url', 'errorMessage': 'er‐
592 ror_message', 'operationResult': 'operation_result', 'request‐
593 Status': 'request_status', 'requestType': 'request_type', 're‐
594 questURL': 'request_url'}
595 class pki.cert.CertRequestInfoCollection
597 Bases: object
598 Class containing list of CertRequestInfo objects. This data is
600 returned when listing certificate request records in the CA.
601 classmethod from_json(json_value)
603 Populate object from JSON input
604 class pki.cert.CertRequestStatus
606 Bases: object
607 Class containing valid cert statuses.
609 CANCELED = 'canceled'
611 COMPLETE = 'complete'
613 PENDING = 'pending'
615 REJECTED = 'rejected'
617 class pki.cert.CertReviewResponse(profile_id=None, renewal=False, se‐
619 rial_number=None, remote_host=None, remote_address=None, inputs=None,
620 outputs=None, nonce=None, request_id=None, request_type=None, re‐
621 quest_status=None, request_owner=None, request_creation_time=None, re‐
622 quest_modification_time=None, request_notes=None, profile_ap‐
623 proval_by=None, profile_set_id=None, profile_is_visible=None, pro‐
624 file_name=None, profile_description=None, profile_remote_host=None,
625 profile_remote_address=None, policy_sets=None)
626 Bases: pki.cert.CertEnrollmentRequest
627 An object of this class represent the response from the server
629 when reviewing a certificate enrollment request. It contains a
630 nonce required to perform action on the request.
631 classmethod from_json(attr_list)
633 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
635 'ProfileID': 'profile_id', 'ProfilePolicySet': 'policy_sets',
636 'RemoteAddress': 'remote_address', 'RemoteHost': 'remote_host',
637 'Renewal': 'renewal', 'SerialNumber': 'serial_number', 'pro‐
638 fileApprovedBy': 'profile_approved_by', 'profileDescription':
639 'profile_description', 'profileIsVisible': 'profile_is_visible',
640 'profileName': 'profile_name', 'profileRemoteAddr': 'profile_re‐
641 mote_address', 'profileRemoteHost': 'profile_remote_host', 'pro‐
642 fileSetId': 'profile_set_id', 'requestCreationTime': 're‐
643 quest_creation_time', 'requestId': 'request_id', 'requestModifi‐
644 cationTime': 'request_modification_time', 'requestNotes': 're‐
645 quest_notes', 'requestOwner': 'request_owner', 'requestStatus':
646 'request_status', 'requestType': 'request_type'}
647 class pki.cert.CertRevokeRequest(nonce, reason=None, invalid‐
649 ity_date=None, comments=None)
650 Bases: object
651 An object of this class encapsulates all the parameters required
653 for revoking a certificate.
654 Valid values for reasons for revoking a request are:
656 'Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affil‐
657 iation_Changed', 'Superseded', 'Cessation_of_Operation',
658 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_With‐
659 drawn', 'AA_Compromise'
660 reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise',
662 'Affiliation_Changed', 'Superseded', 'Cessation_of_Operation',
663 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_Withdrawn',
664 'AA_Compromise']
665 class pki.cert.CertSearchRequest(**cert_search_params)
667 Bases: object
668 An object of this class is used to store the search parameters
670 and send them to server.
671 search_params = {'cert_type_secure_email': 'certTypeSe‐
673 cureEmail', 'cert_type_ssl_client': 'certTypeSSLClient',
674 'cert_type_ssl_server': 'certTypeSSLServer',
675 'cert_type_sub_email_ca': 'certTypeSubEmailCA',
676 'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'common_name': 'com‐
677 monName', 'country': 'country', 'email': 'eMail', 'issued_by':
678 'issuedBy', 'issued_on_from': 'issuedOnFrom', 'issued_on_to':
679 'issuedOnTo', 'locality': 'locality', 'match_exactly': 'matchEx‐
680 actly', 'org': 'org', 'org_unit': 'orgUnit', 'revocation_rea‐
681 son': 'revocationReason', 'revoked_by': 'revokedBy', 're‐
682 voked_on_from': 'revokedOnFrom', 'revoked_on_to': 'revokedOnTo',
683 'serial_from': 'serialFrom', 'serial_to': 'serialTo', 'state':
684 'state', 'status': 'status', 'user_id': 'userID', 'valid_not_af‐
685 ter_from': 'validNotAfterFrom', 'valid_not_after_to': 'validNo‐
686 tAfterTo', 'valid_not_before_from': 'validNotBeforeFrom',
687 'valid_not_before_to': 'validNotBeforeTo', 'validity_count':
688 'validityCount', 'validity_operation': 'validityOperation', 'va‐
689 lidity_unit': 'validityUnit'}
690 pki.cert.main()
692 client Module
694 class pki.client.PKIConnection(protocol='http', hostname='localhost',
695 port='8080', subsystem=None, accept='application/json', trust_env=None,
696 verify=True, cert_paths=None)
697 Bases: object
698 Class to encapsulate the connection between the client and a
700 Dogtag subsystem.
701 authenticate(username=None, password=None)
703 Set the parameters used for authentication if user‐
704 name/password is to be used. Both username and password
705 must not be None. Note that this method only sets the
706 parameters. Actual authentication occurs when the con‐
707 nection is attempted,
708 Parameters
710 • username -- username to authenticate connection
712 • password -- password to authenticate connection
714 Returns
716 None
717 delete(path, headers=None, use_root_uri=False)
719 Uses python-requests to issue a DEL request to the
720 server.
721 Parameters
723 • path (str) -- path URI for the DEL request
725 • headers (dict) -- headers for the DEL request
727 • use_root_uri (boolean) -- use root URI instead
729 of subsystem URI as base
730 Returns
732 request.response -- response from the server
733 Raises Exception from python-requests in case the DEL was
735 not successful, or returns an error code.
736 get(path, headers=None, params=None, payload=None,
738 use_root_uri=False, timeout=None)
739 Uses python-requests to issue a GET request to the
740 server.
741 Parameters
743 • path (str) -- path URI for the GET request
745 • headers (dict) -- headers for the GET request
747 • params (dict or bytes) -- Query parameters for
749 the GET request
750 • payload (dict, bytes, file-like object) -- data
752 to be sent in the body of the request
753 • use_root_uri (boolean) -- use root URI instead
755 of subsystem URI as base
756 Returns
758 request.response -- response from the server
759 Raises Exception from python-requests in case the GET was
761 not successful, or returns an error code.
762 post(path, payload, headers=None, params=None,
764 use_root_uri=False)
765 Uses python-requests to issue a POST request to the
766 server.
767 Parameters
769 • path (str) -- path URI for the POST request
771 • payload (dict, bytes, file-like object) -- data
773 to be sent in the body of the request
774 • headers (dict) -- headers for the POST request
776 • params (dict or bytes) -- Query parameters for
778 the POST request
779 • use_root_uri (boolean) -- use root URI instead
781 of subsystem URI as base
782 Returns
784 request.response -- response from the server
785 Raises Exception from python-requests in case the POST
787 was not successful, or returns an error code.
788 put(path, payload, headers=None, use_root_uri=False)
790 Uses python-requests to issue a PUT request to the
791 server.
792 Parameters
794 • path (str) -- path URI for the PUT request
796 • payload (dict, bytes, file-like object) -- data
798 to be sent in the body of the request
799 • headers (dict) -- headers for the PUT request
801 • use_root_uri (boolean) -- use root URI instead
803 of subsystem URI as base
804 Returns
806 request.response -- response from the server
807 Raises Exception from python-requests in case the PUT was
809 not successful, or returns an error code.
810 set_authentication_cert(pem_cert_path, pem_key_path=None)
812 Set the path to the PEM file containing the certificate
813 and private key for the client certificate to be used for
814 authentication to the server, when client certificate au‐
815 thentication is required. The private key may optionally
816 be stored in a different path.
817 Parameters
819 • pem_cert_path (str) -- path to the PEM file
821 • pem_key_path (str) -- path to the PEM-formatted
823 private key file
824 Returns
826 None
827 Raises Exception if path is empty or None.
829 class pki.client.SSLContextAdapter(pool_connections=10, pool_max‐
831 size=10, max_retries=0, pool_block=False, verify=True, cert_paths=None)
832 Bases: requests.adapters.HTTPAdapter
833 Custom SSLContext Adapter for requests
835 init_poolmanager(connections, maxsize, block=False,
837 **pool_kwargs)
838 Initializes a urllib3 PoolManager.
839 This method should not be called from user code, and is
841 only exposed for use when subclassing the HTTPAdapter.
842 Parameters
844 • connections -- The number of urllib3 connection
846 pools to cache.
847 • maxsize -- The maximum number of connections to
849 save in the pool.
850 • block -- Block when no free connections are
852 available.
853 • pool_kwargs -- Extra keyword arguments used to
855 initialize the Pool Manager.
856 pki.client.catch_insecure_warning(func)
858 Temporary silence InsecureRequestWarning
859 PKIConnection is not able to verify HTTPS connections yet. This
861 decorator catches the warning.
862 See https://fedorahosted.org/pki/ticket/1253
864 pki.client.main()
866 Test code for the PKIConnection class. :return: None
867 crypto Module
869 Module containing crypto classes.
870 class pki.crypto.CryptoProvider
872 Bases: object
873 Abstract class containing methods to do cryptographic opera‐
875 tions.
876 abstract asymmetric_wrap(data, wrapping_cert, mechanism=None)
878 encrypt a symmetric key with the public key of a trans‐
879 port cert.
880 The mechanism is the type of symmetric key, which de‐
882 faults to a 56 bit DES3 key.
883 abstract generate_nonce_iv(mechanism)
885 Create a random initialization vector
886 abstract generate_session_key()
888 Generate a session key to be used for wrapping data to
889 the DRM This must return a 3DES 168 bit key
890 abstract generate_symmetric_key(mechanism=None, size=0)
892 Generate and return a symmetric key
893 abstract get_cert(cert_nick)
895 Get the certificate for the specified cert_nick.
896 abstract get_supported_algorithm_keyset()
898 returns highest supported algorithm keyset
899 abstract initialize()
901 Initialization code
902 abstract key_unwrap(mechanism, data, wrapping_key, nonce_iv)
904 Unwrap data that has been key wrapped using AES KeyWrap
905 abstract set_algorithm_keyset(level)
907 sets required keyset
908 abstract symmetric_unwrap(data, wrapping_key, mechanism=None,
910 nonce_iv=None)
911 decrypt data originally encrypted with symmetric key
912 (wrapping key)
913 We expect the data and nonce_iv values to be base64 en‐
915 coded. The mechanism is the type of key used to do the
916 wrapping. It defaults to a 56 bit DES3 key.
917 abstract symmetric_wrap(data, wrapping_key, mechanism=None,
919 nonce_iv=None)
920 encrypt data using a symmetric key (wrapping key)
921 class pki.crypto.CryptographyCryptoProvider(transport_cert_nick, trans‐
923 port_cert, backend=<OpenSSLBackend(version: OpenSSL 3.0.0 7 sep 2021,
924 FIPS: False)>)
925 Bases: pki.crypto.CryptoProvider
926 Class that defines python-cryptography implementation of Crypto‐
928 Provider. Requires a PEM file containing the agent cert to be
929 initialized.
930 Note that all inputs and outputs are unencoded.
932 asymmetric_wrap(data, wrapping_cert, mechanism=None)
934 :param data Data to be wrapped :param wrap‐
935 ping_cert Public key to wrap data :param mechanism
936 algorithm of symmetric key to be wrapped
937 Wrap (encrypt) data using the supplied asymmetric key
939 generate_nonce_iv(mechanism='AES')
941 Create a random initialization vector
942 generate_session_key()
944 Returns a session key to be used when wrapping secrets
945 for the DRM.
946 generate_symmetric_key(mechanism=None, size=0)
948 Returns a symmetric key.
949 get_cert(cert_nick)
951 :param cert_nick Nickname for the certificate to be re‐
952 turned.
953 get_supported_algorithm_keyset()
955 returns highest supported algorithm keyset
956 initialize()
958 Any operations here that need to be performed before
959 crypto operations.
960 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
962 :param mechanism key wrapping mechanism :param
963 data: data to unwrap :param wrapping_key:
964 AES key used to wrap data :param nonce_iv Nonce
965 data :return: unwrapped data
966 Unwrap the encrypted data which has been wrapped using a
968 KeyWrap mechanism.
969 set_algorithm_keyset(level)
971 sets required keyset
972 symmetric_unwrap(data, wrapping_key, mechanism=None,
974 nonce_iv=None)
975 :param data Data to be unwrapped :param wrap‐
976 ping_key Symmetric key to unwrap data :param mechanism
977 Mechanism to use when unwrapping :param nonce_iv
978 iv data
979 Unwrap (decrypt) data using the supplied symmetric key
981 symmetric_wrap(data, wrapping_key, mechanism=None,
983 nonce_iv=None)
984 :param data Data to be wrapped :param wrap‐
985 ping_key Symmetric key to wrap data :param mechanism
986 Mechanism to use for wrapping key :param nonce_iv
987 Nonce for initialization vector
988 Wrap (encrypt) data using the supplied symmetric key
990 encoder Module
992 pki.encoder.CustomTypeDecoder(dct)
993 class pki.encoder.CustomTypeEncoder(*, skipkeys=False, en‐
995 sure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False,
996 indent=None, separators=None, default=None)
997 Bases: json.encoder.JSONEncoder
998 A custom JSONEncoder class that knows how to encode core custom
1000 objects.
1001 Custom objects are encoded as JSON object literals (ie, dicts)
1003 with one key, 'TypeName' where 'TypeName' is the actual name of
1004 the type to which the object belongs. That single key maps to
1005 another object literal which is just the __dict__ of the object
1006 encoded.
1007 Reason for ignoring the error: E0202 - An attribute affected in
1009 json.encoder line 157 hide this method reported by pylint:
1010 The error is in json.encoder.JSONEncoder class. There is a de‐
1012 fault method (which is overridden here) and also a class attri‐
1013 bute self.default initialized in the init method of the class.
1014 The intention of such usage being that a custom default method
1015 object can be passed to init when creating an instance of JSO‐
1016 NEncoder, which is then assigned to class's default method.
1017 (which is valid) But pylint raises an issue due to the usage of
1018 same name for a method and an attribute in which case the attri‐
1019 bute definition hides the method. The reason and example for
1020 the issue: (top rated comment)
1021 http://stackoverflow.com/questions/12949064/python-what-happens-
1022 when-instance-variable-name-is-same-as-method-name
1023 static attr_name_conversion(attr_dict, object_class)
1025 default(o)
1027 Implement this method in a subclass such that it returns
1028 a serializable object for o, or calls the base implemen‐
1029 tation (to raise a TypeError).
1030 For example, to support arbitrary iterators, you could
1032 implement default like this:
1033 def default(self, o):
1035 try:
1036 iterable = iter(o)
1037 except TypeError:
1038 pass
1039 else:
1040 return list(iterable)
1041 # Let the base class default method raise the TypeError
1042 return JSONEncoder.default(self, o)
1043 pki.encoder.decode_cert(data)
1045 base64 decode X.509 certificate
1046 Parameters
1048 data (str, bytes) -- data as bytes or ASCII text
1049 Return type
1051 bytes
1052 pki.encoder.encode_cert(data)
1054 base64 encode X.509 certificate
1055 Python 3's base64.b64encode() doesn't support ASCII text.
1057 Parameters
1059 data (str, bytes) -- data as bytes or ASCII text
1060 Return type
1062 bytes
1063 key Module
1065 Module containing the Python client classes for the KeyClient and
1066 KeyRequestClient REST API on a DRM
1067 class pki.key.AsymKeyGenerationRequest(client_key_id=None,
1069 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1070 sion_key=None, realm=None)
1071 Bases: pki.ResourceMessage
1072 Class representing the data sent to the DRM when generating and
1074 archiving asymmetric keys in the DRM.
1075 DECRYPT_USAGE = 'decrypt'
1077 DERIVE_USAGE = 'derive'
1079 ENCRYPT_USAGE = 'encrypt'
1081 SIGN_RECOVER_USAGE = 'sign_recover'
1083 SIGN_USAGE = 'sign'
1085 UNWRAP_USAGE = 'unwrap'
1087 VERIFY_RECOVER_USAGE = 'verify_recover'
1089 VERIFY_USAGE = 'verify'
1091 WRAP_USAGE = 'wrap'
1093 class pki.key.Key(key_data)
1095 Bases: object
1096 An instance of this class stores the decoded encrypted secret
1098 present in the KeyData object passed in the constructor. All
1099 the key retrieval requests return this object.
1100 class pki.key.KeyArchivalRequest(client_key_id=None, data_type=None,
1102 wrapped_private_data=None, trans_wrapped_session_key=None, pki_ar‐
1103 chive_options=None, algorithm_oid=None, symkey_params=None, key_algo‐
1104 rithm=None, key_size=None, realm=None)
1105 Bases: pki.ResourceMessage
1106 Class representing the object sent to the DRM when archiving a
1108 secret.
1109 class pki.key.KeyClient(connection, crypto, transport_cert_nick=None,
1111 info_client=None)
1112 Bases: object
1113 Class that encapsulates and mirrors the functions in the KeyRe‐
1115 source and KeyRequestResource Java classes in the DRM REST API.
1116 AES_ALGORITHM = 'AES'
1118 ASYMMETRIC_KEY_TYPE = 'asymmetricKey'
1120 DES3_ALGORITHM = 'DES3'
1122 DESEDE_ALGORITHM = 'DESede'
1124 DES_ALGORITHM = 'DES'
1126 DSA_ALGORITHM = 'DSA'
1128 KEY_STATUS_ACTIVE = 'active'
1130 KEY_STATUS_INACTIVE = 'inactive'
1132 PASS_PHRASE_TYPE = 'passPhrase'
1134 RC2_ALGORITHM = 'RC2'
1136 RC4_ALGORITHM = 'RC4'
1138 RSA_ALGORITHM = 'RSA'
1140 SYMMETRIC_KEY_TYPE = 'symmetricKey'
1142 approve_request(request_id)
1144 Approve a secret recovery request
1145 archive_encrypted_data(client_key_id, data_type, encrypted_data,
1147 wrapped_session_key, algorithm_oid=None, nonce_iv=None, key_al‐
1148 gorithm=None, key_size=None, realm=None)
1149 Archive a secret (symmetric key or passphrase) on the
1150 DRM.
1151 Refer to archive_key() comments for a description of
1153 client_key_id, data_type, key_algorithm and key_size.
1154 The following parameters are also required:
1156 • encrypted_data - which is the data encrypted by
1158 a session key (168 bit 3DES symmetric key)
1159 • wrapped_session_key - the above session key
1161 wrapped by the DRM transport certificate public
1162 key.
1163 • the algorithm_oid string for the symmetric key
1165 wrap
1166 • the nonce_iv for the symmetric key wrap
1168 This function is useful if the caller wants to do their
1170 own wrapping of the secret, or if the secret was gener‐
1171 ated on a separate client machine and the wrapping was
1172 done there.
1173 The function returns a KeyRequestResponse object contain‐
1175 ing a KeyRequestInfo object with details about the
1176 archival request and key archived.
1177 archive_key(client_key_id, data_type, private_data, key_algo‐
1179 rithm=None, key_size=None, realm=None)
1180 Archive a secret (symmetric key or passphrase) on the
1181 DRM.
1182 Requires a user-supplied client ID. There can be only
1184 one active key with a specified client ID. If a record
1185 for a duplicate active key exists, a BadRequestException
1186 is thrown.
1187 data_type can be one of the following:
1189 KeyClient.SYMMETRIC_KEY_TYPE, KeyClient.ASYMMET‐
1190 RIC_KEY_TYPE, KeyClient.PASS_PHRASE_TYPE
1191 key_algorithm and key_size are applicable to symmetric
1193 keys only. If a symmetric key is being archived, these
1194 parameters are required.
1195 private_data is the raw secret to be archived. It will
1197 be wrapped and sent to the DRM.
1198 The function returns a KeyRequestResponse object contain‐
1200 ing a KeyRequestInfo object with details about the
1201 archival request and key archived.
1202 archive_pki_options(client_key_id, data_type, pki_archive_op‐
1204 tions, key_algorithm=None, key_size=None, realm=None)
1205 Archive a secret (symmetric key or passphrase) on the
1206 DRM.
1207 Refer to archive_key() comments for a description of
1209 client_key_id, data_type, key_algorithm and key_size.
1210 pki_archive_options is the data to be archived wrapped in
1212 a PKIArchiveOptions structure,
1213 The function returns a KeyRequestResponse object contain‐
1215 ing a KeyRequestInfo object with details about the
1216 archival request and key archived.
1217 cancel_request(request_id)
1219 Cancel a secret recovery request
1220 generate_asymmetric_key(client_key_id, algorithm=None,
1222 key_size=None, usages=None, trans_wrapped_session_key=None,
1223 realm=None)
1224 Generate and archive asymmetric keys in the DRM. Sup‐
1225 ports algorithms RSA and DSA. Valid key size for RSA =
1226 256 + (16 * n), where n: 0-496 Valid key size for DSA =
1227 512, 768, 1024. p,q,g params are not supported.
1228 Return a KeyRequestResponse which contains a KeyRe‐
1230 questInfo object that describes the URL for the request
1231 and generated keys.
1232 generate_symmetric_key(client_key_id, algorithm=None, size=None,
1234 usages=None, trans_wrapped_session_key=None, realm=None)
1235 Generate and archive a symmetric key on the DRM.
1236 Return a KeyRequestResponse which contains a KeyRe‐
1238 questInfo object that describes the URL for the request
1239 and generated key.
1240 get_active_key_info(client_key_id)
1242 Get the info in the KeyRecord for the active secret in
1243 the DRM.
1244 get_client_keyset()
1246 get_key_info(key_id)
1248 Get the info in the KeyRecord for a specific secret in
1249 the DRM.
1250 get_request_info(request_id)
1252 Return a KeyRequestInfo object for a specific request.
1253 get_server_keyset()
1255 list_keys(client_key_id=None, status=None, max_results=None,
1257 max_time=None, start=None, size=None, realm=None)
1258 List/Search archived secrets in the DRM.
1259 See KRAClient.list_keys for the valid values of status.
1261 Returns a KeyInfoCollection object.
1262 list_requests(request_state=None, request_type=None,
1264 client_key_id=None, start=None, page_size=None, max_re‐
1265 sults=None, max_time=None, realm=None)
1266 List/Search key requests in the DRM.
1267 See KRAClient.list_requests for the valid values of re‐
1269 quest_state and request_type. Returns a KeyRequestInfo‐
1270 Collection object.
1271 modify_key_status(key_id, status)
1273 Modify the status of a key
1274 process_returned_key(key, session_key)
1276 Decrypt the returned key and place in key.data
1277 The data will either by encrypted using an encryption al‐
1279 gorithm - in which case, the key data will contain an en‐
1280 cryption algorithm OID, or it will be key wrapped - in
1281 which case, the key data will contain a key wrap mecha‐
1282 nism name.
1283 Only one of these should be present. If we are talking
1285 to an older server, and none is present, we will assume
1286 encryption.
1287 recover_key(key_id, request_id=None, ses‐
1289 sion_wrapped_passphrase=None, trans_wrapped_session_key=None,
1290 b64certificate=None, nonce_data=None)
1291 Create a request to recover a secret.
1292 To retrieve a symmetric key or passphrase, the only pa‐
1294 rameter that is required is the keyId. It is possible
1295 (but not required) to pass in the session keys/passphrase
1296 and nonceData for the retrieval at this time. Those pa‐
1297 rameters are documented in the docstring for retrieve_key
1298 below.
1299 To retrieve an asymmetric key, the keyId and the the
1301 base-64 encoded certificate is required.
1302 reject_request(request_id)
1304 Reject a secret recovery request.
1305 retrieve_key(key_id=None, trans_wrapped_session_key=None, re‐
1307 quest_id=None)
1308 Retrieve a secret (passphrase or symmetric key) from the
1309 DRM.
1310 This method will retrieve a key from the KRA given the
1312 key_id or request_id (one of which must be specified).
1313 The data is returned as a KeyData object (which is recast
1314 to a Key object).
1315 If request_id is specified, then the value of key_id is
1317 ignored. Exceptions will be thrown if the caller is not
1318 the originator of the request, or the request is not ap‐
1319 proved.
1320 If key_id is specified instead, the following behavior
1322 applies:
1323 • If the key can be retrieved synchronously - ie. only
1325 one agent's approval is required, then the KeyData will
1326 include the secret.
1327 • If the key cannot be retrieved synchronously - ie. if
1329 more than one approval is needed, then the KeyData ob‐
1330 ject will include the request ID for a recovery request
1331 that was created on the server. When that request is
1332 approved, callers can retrieve the key using re‐
1333 trieve_key() and setting the request_id.
1334 To ensure data security in transit, the data will be re‐
1336 turned encrypted by a session key (168 bit 3DES symmetric
1337 key) - which is first wrapped (encrypted) by the public
1338 key of the DRM transport certificate before being sent to
1339 the DRM. The parameter trans_wrapped_session_key refers
1340 to this wrapped session key.
1341 If the trans_wrapped_session_key is not provided by
1343 caller, the method will call CryptoProvider methods to
1344 generate and wrap the session key. The function will re‐
1345 turn the KeyData object with a private_data attribute
1346 which stores the unwrapped key information.
1347 If the trans_wrapped_session_key is provided by the
1349 caller, the method will simply pass the data to the KRA,
1350 and will return the secret wrapped in the session key.
1351 The secret will still need to be unwrapped by the caller.
1352 The function will return the KeyData object, where the
1353 KeyData structure includes the wrapped secret and some
1354 nonce data to be used as a salt when unwrapping.
1355 retrieve_key_by_passphrase(key_id=None, request_id=None,
1357 passphrase=None, trans_wrapped_session_key=None, ses‐
1358 sion_wrapped_passphrase=None, nonce_data=None)
1359 Retrieve a secret (passphrase or symmetric key) from the
1360 DRM using a passphrase.
1361 This function generates a key recovery request, approves
1363 it, and retrieves the secret referred to by key_id. This
1364 assumes that only one approval is required to authorize
1365 the recovery.
1366 The secret is secured in transit by wrapping the secret
1368 with a passphrase using PBE encryption.
1369 There are two ways of using this function:
1371 1. A passphrase is provided by the caller.
1373 In this case, CryptoProvider methods will be called to
1375 create the data to securely send the passphrase to the
1376 DRM. Basically, three pieces of data will be sent:
1377 • the passphrase wrapped by a 168 bit 3DES symmetric
1379 key (the session key). This is referred to as the
1380 parameter session_wrapped_passphrase.
1381 • the session key wrapped with the public key in the
1383 DRM transport certificate. This is referred to as
1384 the trans_wrapped_session_key.
1385 • ivps nonce data, referred to as nonce_data
1387 The function will return the tuple (KeyData, un‐
1389 wrapped_secret)
1390 2. The caller provides the trans_wrapped_session_key,
1392 session_wrapped_passphrase and nonce_data.
1393 In this case, the data will simply be passed to the
1395 DRM. The function will return the secret encrypted by
1396 the passphrase using PBE Encryption. The secret will
1397 still need to be decrypted by the caller.
1398 The function will return the tuple (KeyData, None)
1400 retrieve_key_by_pkcs12(key_id, certificate, passphrase)
1402 Retrieve an asymmetric private key and return it as
1403 PKCS12 data.
1404 This function generates a key recovery request, approves
1406 it, and retrieves the secret referred to by key_id in a
1407 PKCS12 file. This assumes that only one approval is re‐
1408 quired to authorize the recovery.
1409 This function requires the following parameters: - key_id
1411 : the ID of the key - certificate: the certificate asso‐
1412 ciated with the private key - passphrase: A passphrase
1413 for the pkcs12 file.
1414 The function returns a KeyData object.
1416 retrieve_key_data(data)
1418 Retrieve a secret from the DRM.
1419 @param: data - a KeyRecoveryRequest containing the keyId
1421 of the secret being retrieved, the request_id of the ap‐
1422 proved recovery request and a wrapping mechanism. More
1423 details at KRAClient.retrieve_key.
1424 Returns a KeyData object containing the wrapped secret.
1426 set_crypto_algorithms()
1428 set_transport_cert(transport_cert_nick)
1430 Set the transport certificate for crypto operations
1431 submit_request(request)
1433 Submit an archival, recovery or key generation request to
1434 the DRM.
1435 @param request - is either a KeyArchivalRequest, KeyRe‐
1437 coverRequest, SymKeyGenerationRequest or AsymKeyGenera‐
1438 tionRequest.
1439 returns a KeyRequestResponse object.
1441 class pki.key.KeyData
1443 Bases: object
1444 This is the object that contains the encoded wrapped secret when
1446 that secret is retrieved. It is used by the DRM to send informa‐
1447 tion of the key in the key retrieval requests.
1448 classmethod from_json(attr_list)
1450 Return a KeyData object from a JSON dict
1451 json_attribute_names = {'encryptAlgorithmOID': 'encrypt_algo‐
1453 rithm_oid', 'nonceData': 'nonce_data', 'publicKey': 'pub‐
1454 lic_key', 'requestID': 'request_id', 'wrapAlgorithm': 'wrap_al‐
1455 gorithm', 'wrappedPrivateData': 'wrapped_private_data'}
1456 class pki.key.KeyInfo
1458 Bases: object
1459 This is the object that contains information stored in the data‐
1461 base record for an archived secret. It does not contain the se‐
1462 cret itself.
1463 classmethod from_json(attr_list)
1465 Return KeyInfo from JSON dict
1466 get_key_id()
1468 Return the key ID as parsed from key URL
1469 json_attribute_names = {'clientKeyID': 'client_key_id',
1471 'keyURL': 'key_url', 'ownerName': 'owner_name', 'publicKey':
1472 'public_key'}
1473 class pki.key.KeyInfoCollection
1475 Bases: object
1476 This class represents data returned when searching the DRM
1478 archived secrets. Essentially, its a list of KeyInfo objects.
1479 classmethod from_json(json_value)
1481 Return a KeyInfoCollection object from its JSON represen‐
1482 tation
1483 class pki.key.KeyRecoveryRequest(key_id=None, request_id=None,
1485 trans_wrapped_session_key=None, session_wrapped_passphrase=None,
1486 nonce_data=None, certificate=None, passphrase=None, payload_wrap‐
1487 ping_name=None, payload_encryption_oid=None)
1488 Bases: pki.ResourceMessage
1489 Class representing the data sent to the DRM when either creating
1491 a request for the recovery of a secret, or, once the request is
1492 approved, retrieving the secret.
1493 class pki.key.KeyRequestInfo
1495 Bases: object
1496 This class represents data about key requests (archival, recov‐
1498 ery, key generation etc.) in the DRM.
1499 classmethod from_json(attr_list)
1501 Return a KeyRequestInfo object from a JSON dict.
1502 get_key_id()
1504 Return the ID of the secret referred to by this request.
1505 get_request_id()
1507 Return the request ID by parsing the request URL.
1508 json_attribute_names = {'keyURL': 'key_url', 'requestStatus':
1510 'request_status', 'requestType': 'request_type', 'requestURL':
1511 'request_url'}
1512 class pki.key.KeyRequestInfoCollection
1514 Bases: object
1515 This class represents the data returned when searching the key
1517 requests in the DRM. Essentially, its a list of KeyRequestInfo
1518 objects.
1519 classmethod from_json(json_value)
1521 Return a KeyRequestInfoCollection object from its JSON
1522 representation.
1523 class pki.key.KeyRequestResponse
1525 Bases: object
1526 This class is returned when an archival, recovery or key genera‐
1528 tion request is created. It includes a KeyRequestInfo object
1529 with information about the created request, and a KeyData struc‐
1530 ture which contains the wrapped secret (if that operation is
1531 supported).
1532 classmethod from_json(json_value)
1534 Return a KeyRequestResponse object from its JSON repre‐
1535 sentation.
1536 get_key_id()
1538 Return the id for the key archived, recovered or gener‐
1539 ated
1540 get_request_id()
1542 Return the id for the created request
1543 class pki.key.RequestId(req_id)
1545 Bases: object
1546 Class representing a Request ID
1548 class pki.key.SymKeyGenerationRequest(client_key_id=None,
1550 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1551 sion_key=None, realm=None)
1552 Bases: pki.ResourceMessage
1553 Class representing the data sent to the DRM when generating and
1555 archiving a symmetric key in the DRM.
1556 DECRYPT_USAGE = 'decrypt'
1558 ENCRYPT_USAGE = 'encrypt'
1560 SIGN_USAGE = 'sign'
1562 UNWRAP_USAGE = 'unwrap'
1564 VERIFY_USAGE = 'verify'
1566 WRAP_USAGE = 'wrap'
1568 pki.key.main()
1570 Some unit tests - basically printing different types of requests
1571 kra Module
1573 Module containing KRAClient class. This class should be used by Python
1574 clients to interact with the DRM to expose the functionality of the
1575 KeyClient and KeyRequestResource REST APIs.
1576 class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
1578 Bases: object
1579 Client class that models interactions with a KRA using the Key
1581 and KeyRequest REST APIs.
1582 profile Module
1584 class pki.profile.Descriptor(syntax=None, constraint=None, descrip‐
1585 tion=None, default_value=None)
1586 Bases: object
1587 This class represents the description of a ProfileAttribute. It
1589 stores information such as the syntax, constraint and default
1590 value of a profile attribute.
1591 classmethod from_json(attr_list)
1593 json_attribute_names = {'Constraint': 'constraint', 'Default‐
1595 Value': 'default_value', 'Description': 'description', 'Syntax':
1596 'syntax'}
1597 class pki.profile.PolicyConstraint(name=None, description=None,
1599 class_id=None, policy_constraint_values=None)
1600 Bases: object
1601 An object of this class contains the policy constraints applied
1603 to a ProfileInput used by a certificate enrollment request.
1604 add_constraint_value(policy_constraint_value)
1606 Add a PolicyConstraintValue to the policy_constraint_val‐
1607 ues list.
1608 classmethod from_json(attr_list)
1610 get_constraint_value(policy_constraint_value_name)
1612 Returns a PolicyConstraintValue object with the given
1613 name. None, if there is no match.
1614 json_attribute_names = {'classId': 'class_id', 'constraint':
1616 'policy_constraint_values', 'id': 'name'}
1617 remove_constraint_value(policy_constraint_value_name)
1619 Removes a PolicyConstraintValue with the given name form
1620 the policy_constraint_values list.
1621 class pki.profile.PolicyConstraintValue(name=None, value=None, descrip‐
1623 tor=None)
1624 Bases: object
1625 Represents a PolicyConstraintValue
1627 classmethod from_json(attr_list)
1629 property name
1631 class pki.profile.PolicyDefault(name=None, class_id=None, descrip‐
1633 tion=None, policy_attributes=None, policy_params=None)
1634 Bases: object
1635 An object of this class contains information of the default us‐
1637 age of a specific ProfileInput.
1638 add_attribute(policy_attribute)
1640 Add a policy attribute to the attribute list. @param
1641 policy_attribute - A ProfileAttribute object
1642 add_parameter(policy_parameter)
1644 Add a profile parameter to the parameters list. @param
1645 policy_parameter - A ProfileParameter object.
1646 classmethod from_json(attr_list)
1648 get_attribute(policy_attribute_name)
1650 Fetch the policy attribute with the given name from the
1651 attributes list.
1652 get_parameter(profile_parameter_name)
1654 Fetch a profile parameter with the given name from the
1655 parameters list.
1656 json_attribute_names = {'classId': 'class_id', 'id': 'name',
1658 'params': 'policy_params', 'policyAttribute': 'policy_at‐
1659 tributes'}
1660 remove_attribute(policy_attribute_name)
1662 Remove a policy attribute with the given name from the
1663 attributes list.
1664 remove_parameter(profile_parameter_name)
1666 Remove a profile parameter with the given name from the
1667 parameters list.
1668 class pki.profile.PolicySet(name=None, policy_list=None)
1670 Bases: object
1671 An object of this class contains a name value pair of the policy
1673 name and the ProfilePolicy object.
1674 add_policy(profile_policy)
1676 Add a ProfilePolicy object to the policy_list
1677 classmethod from_json(attr_list)
1679 get_policy(policy_id)
1681 Returns a ProfilePolicy object with the given profile id.
1682 json_attribute_names = {'id': 'name', 'value': 'policy_list'}
1684 remove_policy(policy_id)
1686 Removes a ProfilePolicy with the given ID from the Poli‐
1687 cySet.
1688 class pki.profile.PolicySetList(policy_sets=None)
1690 Bases: object
1691 An object of this class stores a list of ProfileSet objects.
1693 add_policy_set(policy_set)
1695 Add a PolicySet object to the policy_sets list.
1696 classmethod from_json(attr_list)
1698 get_policy_set(policy_set_name)
1700 Fetch the PolicySet object for the given name. Returns
1701 None, if not found.
1702 property policy_sets
1704 remove_policy_set(policy_set_name)
1706 Remove a PolicySet object with the given name from the
1707 policy_sets list.
1708 class pki.profile.Profile(profile_id=None, class_id=None, name=None,
1710 description=None, enabled=None, visible=None, enabled_by=None, authen‐
1711 ticator_id=None, authorization_acl=None, renewal=None, xml_output=None,
1712 inputs=None, outputs=None, policy_set_list=None, link=None)
1713 Bases: object
1714 This class represents an enrollment profile.
1716 add_input(profile_input)
1718 Add a ProfileInput object to the inputs list of the Pro‐
1719 file.
1720 add_output(profile_output)
1722 Add a ProfileOutput object to the outputs list of the
1723 Profile.
1724 add_policy_set(policy_set)
1726 Add a PolicySet object to the policy_sets list of the
1727 Profile.
1728 classmethod from_json(attr_list)
1730 get_input(profile_input_id)
1732 Fetches a ProfileInput with the given ProfileInput id.
1733 Returns None, if there is no matching input.
1734 get_output(profile_output_id)
1736 Fetches a ProfileOutput with the given ProfileOutput id.
1737 Returns None, if there is no matching output.
1738 get_policy_set(policy_set_name)
1740 Fetches a ProfileInput with the given ProfileInput id.
1741 Returns None, if there is no matching input.
1742 static get_profile_data_from_file(path_to_file)
1744 Reads the file for the serialized Profile object. Cur‐
1745 rently supports only data format in json.
1746 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
1748 'PolicySets': 'policy_set_list', 'authenticatorId': 'authentica‐
1749 tor_id', 'authzAcl': 'authorization_acl', 'classId': 'class_id',
1750 'enabledBy': 'enabled_by', 'id': 'profile_id', 'xmlOutput':
1751 'xml_output'}
1752 remove_input(profile_input_id)
1754 Remove a ProfileInput from the inputs list of the Pro‐
1755 file.
1756 remove_output(profile_output_id)
1758 Remove a ProfileOutput from the outputs list of the Pro‐
1759 file.
1760 remove_policy_set(policy_set_name)
1762 Remove a PolicySet from the policy_sets list of the Pro‐
1763 file.
1764 class pki.profile.ProfileAttribute(name=None, value=None, descrip‐
1766 tor=None)
1767 Bases: object
1768 Represents a profile attribute of a ProfileInput.
1770 classmethod from_json(attr_list)
1772 json_attribute_names = {'Descriptor': 'descriptor', 'Value':
1774 'value'}
1775 class pki.profile.ProfileClient(connection)
1777 Bases: object
1778 This class consists of methods for accessing the ProfileRe‐
1780 source.
1781 create_profile(profile_data)
1783 Create a new profile for the given Profile object.
1784 create_profile_from_file(path_to_file)
1786 Reads the file for the serialized Profile object. Per‐
1787 forms the profile create operation. Currently supports
1788 only data format in json.
1789 delete_profile(profile_id)
1791 Delete a profile with the given Profile Id.
1792 disable_profile(profile_id)
1794 Disables a profile.
1795 enable_profile(profile_id)
1797 Enables a profile.
1798 get_profile(profile_id)
1800 Fetches information for the profile for the given profile
1801 id. Returns a ProfileData object.
1802 list_profiles(start=None, size=None)
1804 Fetches the list of profiles. The start and size argu‐
1805 ments provide pagination support. Returns a Profile‐
1806 DataInfoCollection object.
1807 modify_profile(profile_data)
1809 Modify an existing profile with the given Profile object.
1810 modify_profile_from_file(path_to_file)
1812 Reads the file for the serialized Profile object. Per‐
1813 forms the profile modify operation. Currently supports
1814 only data format in json.
1815 class pki.profile.ProfileDataInfo
1817 Bases: object
1818 Stores information about a profile
1820 classmethod from_json(attr_list)
1822 json_attribute_names = {'profileDescription': 'profile_descrip‐
1824 tion', 'profileId': 'profile_id', 'profileName': 'profile_name',
1825 'profileURL': 'profile_url'}
1826 class pki.profile.ProfileDataInfoCollection
1828 Bases: object
1829 Represents a collection of ProfileDataInfo objects. Also encap‐
1831 sulates the links for the list of the objects stored.
1832 classmethod from_json(attr_list)
1834 class pki.profile.ProfileInput(profile_input_id=None, class_id=None,
1836 name=None, text=None, attributes=None, config_attributes=None)
1837 Bases: object
1838 This class encapsulates all the attributes of a profile to gen‐
1840 erate a specific property of a certificate. Ex. Subject name,
1841 Requestor Information etc.
1842 add_attribute(profile_attribute)
1844 Add a ProfileAttribute object to the attributes list.
1845 add_config_attribute(profile_attribute)
1847 Add a ProfileAttribute object to the config_attributes
1848 list.
1849 classmethod from_json(attr_list)
1851 get_attribute(profile_attribute_name)
1853 Returns a ProfileAttribute object for the given name.
1854 None, if no match.
1855 get_config_attribute(config_attribute_name)
1857 Returns a ProfileAttribute object with the given name.
1858 None, if there is no match in the config_attributes list.
1859 json_attribute_names = {'Attribute': 'attributes', 'ClassID':
1861 'class_id', 'ConfigAttribute': 'config_attributes', 'Name':
1862 'name', 'Text': 'text', 'id': 'profile_input_id'}
1863 remove_attribute(profile_attribute_name)
1865 Remove a ProfileAttribute object with the given name from
1866 the attributes list.
1867 remove_config_attribute(config_attribute_name)
1869 Remove a ProfileAttribute object with the given name from
1870 the config_attributes list.
1871 class pki.profile.ProfileOutput(profile_output_id=None, name=None,
1873 text=None, class_id=None, attributes=None)
1874 Bases: object
1875 This class defines the output of a certificate enrollment re‐
1877 quest using a profile.
1878 add_attribute(profile_attribute)
1880 Add a ProfileAttribute object to the attributes list.
1881 classmethod from_json(attr_list)
1883 get_attribute(profile_attribute_name)
1885 Returns a ProfileAttribute object for the given name.
1886 None, if no match.
1887 json_attribute_names = {'classId': 'class_id', 'id': 'pro‐
1889 file_output_id'}
1890 remove_attribute(profile_attribute_name)
1892 Remove a ProfileAttribute object with the given name from
1893 the attributes list.
1894 class pki.profile.ProfileParameter(name=None, value=None)
1896 Bases: object
1897 classmethod from_json(attr_list)
1899 class pki.profile.ProfilePolicy(policy_id=None, policy_default=None,
1901 policy_constraint=None)
1902 Bases: object
1903 This class represents the policy a profile adheres to. An ob‐
1905 ject of this class stores the default values for profile and the
1906 constraints present on the values of the attributes of the pro‐
1907 file submitted for an enrollment request.
1908 classmethod from_json(attr_list)
1910 json_attribute_names = {'constraint': 'policy_constraint',
1912 'def': 'policy_default', 'id': 'policy_id'}
1913 class pki.profile.ProfilePolicySet
1915 Bases: object
1916 Stores a list of ProfilePolicy objects.
1918 classmethod from_json(attr_list)
1920 pki.profile.main()
1922 system Module
1924 class pki.system.AdminSetupRequest
1925 Bases: object
1926 class pki.system.AdminSetupResponse
1928 Bases: object
1929 class pki.system.CertificateSetupRequest
1931 Bases: object
1932 class pki.system.CertificateSetupResponse
1934 Bases: object
1935 class pki.system.DomainInfo
1937 Bases: object
1938 Class representing the entire security domain. This is essen‐
1940 tially a list of SecurityDomainSubsystem components.
1941 classmethod from_json(json_value)
1943 Create a DomainInfo object from JSON.
1944 Parameters
1946 json_value (str) -- JSON representation of a secu‐
1947 rity domain.
1948 Returns
1950 DomainInfo
1951 property systems
1953 class pki.system.InstallToken
1955 Bases: object
1956 classmethod from_json(json_value)
1958 class pki.system.SecurityDomainClient(connection)
1960 Bases: object
1961 Client used to get the security domain from a security domain
1963 CA. The connection details for the security domain CA are spec‐
1964 ified in a PKIConnection object used to construct this client.
1965 get_domain_info()
1967 Contact the security domain CA specified in the connec‐
1968 tion object used to construct this client and get the se‐
1969 curity domain using the REST API.
1970 Returns
1972 pki.system.DomainInfo
1973 get_install_token(hostname, subsystem)
1975 Returns
1977 pki.system.InstallToken
1978 get_old_domain_info()
1980 Contact the security domain CA specified in the connec‐
1981 tion object used to construct this client and get the se‐
1982 curity domain using the old servlet-based interface.
1983 This method is useful when contacting old servers which
1984 do not provide the REST API.
1985 Returns
1987 pki.system.DomainInfo
1988 get_security_domain_info()
1990 class pki.system.SecurityDomainHost
1992 Bases: object
1993 Class representing a security domain host.
1995 classmethod from_json(json_value)
1997 Constructs a SecurityDomainHost object from JSON.
1998 Parameters
2000 json_value (str) -- JSON string representing a se‐
2001 curity domain host.
2002 Returns
2004 SecurityDomainHost
2005 class pki.system.SecurityDomainSubsystem
2007 Bases: object
2008 Class representing a security domain subsystem. This is essen‐
2010 tially a list of SecurityDomainHost objects of a particular sub‐
2011 system type (ca, kra, tps, tks, ocsp).
2012 classmethod from_json(json_value)
2014 Constructs a SecurityDomainSubsystem from a JSON repre‐
2015 sentation.
2016 Parameters
2018 json_value (str) -- JSON representation of the Se‐
2019 curity Domain Subsystem
2020 Returns
2022 SecurityDomainSubsystem
2023 get_host(hostname, secure_port)
2025 class pki.system.SystemCertData
2027 Bases: object
2028 Class used to represent the data for a system certificate, which
2030 is used in the data passed into and returned from the Java in‐
2031 stallation servlet during the execution of pkispawn.
2032 This class is the python equivalent of the Java class: com.net‐
2034 scape.certsrv.system.SystemCertData
2035 class pki.system.SystemConfigClient(connection, subsystem=None)
2037 Bases: object
2038 Client used to interact with the Java configuration servlet to
2040 configure a Dogtag subsystem during the execution of pkispawn.
2041 The connection details for the system being configured are
2043 passed in the PKIConnection object used when constructing this
2044 object.
2045 initSubsystem(request)
2047 Initialize subsystem.
2048 Parameters
2050 request (CertificateSetupRequest) -- Certificate
2051 setup request
2052 loadCert(request)
2054 Load existing certificate.
2055 Parameters
2057 request (CertificateSetupRequest) -- Certificate
2058 setup request
2059 Returns
2061 SystemCertData
2062 setupAdmin(request)
2064 Set up admin.
2065 Parameters
2067 request (CertificateSetupRequest) -- Admin setup
2068 request
2069 Returns
2071 SystemCertData
2072 setupCert(request)
2074 Set up certificate.
2075 Parameters
2077 request (CertificateSetupRequest) -- Certificate
2078 setup request
2079 Returns
2081 SystemCertData
2082 class pki.system.SystemStatusClient(connection, subsystem=None)
2084 Bases: object
2085 Client used to check the status of a Dogtag subsystem.
2087 get_status(timeout=None)
2089 Checks the status of the subsystem by calling the getSta‐
2090 tus() servlet. This is used to determine if the server
2091 is up and ready to receive and process requests.
2092 Returns
2094 str - getStatus response
2095 systemcert Module
2097 Module containing the Python client classes for the SystemCert REST API
2098 class pki.systemcert.SystemCertClient(connection, subsystem=None)
2100 Bases: object
2101 Class encapsulating and mirroring the functionality in the Sys‐
2103 temCertResource Java interface class defining the REST API for
2104 system certificate resources.
2105 get_transport_cert()
2107 Return transport certificate.
2108 Returns
2110 pki.cert.CertData -- transport certificate data
2111 upgrade Module
2113 class pki.upgrade.PKIUpgradeScriptlet
2114 Bases: object
2115 backup(path)
2117 get_backup_dir()
2119 upgrade_system()
2121 class pki.upgrade.PKIUpgradeTracker(name, filename, delimiter='=', ver‐
2123 sion_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
2124 Bases: object
2125 get_index()
2127 get_version()
2129 remove()
2131 remove_index()
2133 remove_version()
2135 set(version)
2137 set_index(index)
2139 set_version(version)
2141 show()
2143 class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade')
2145 Bases: object
2146 all_versions()
2148 backup(scriptlet, path)
2150 copydirs(source, dest, force=False)
2152 copyfile(source, dest, force=False)
2154 get_current_version()
2156 get_target_version()
2158 get_tracker()
2160 init_scriptlet(scriptlet)
2162 is_complete()
2164 makedirs(path, exist_ok=False)
2166 record(scriptlet, path)
2168 remove_tracker()
2170 reset_tracker()
2172 revert()
2174 revert_scriptlet(scriptlet)
2176 revert_version(version)
2178 run_scriptlet(scriptlet)
2180 scriptlets(version)
2182 set_tracker(version)
2184 show_tracker()
2186 status()
2188 touch(path)
2190 update_tracker(scriptlet)
2192 upgrade()
2194 upgrade_version(version)
2196 validate()
2198 version_dir(version)
2200 versions()
2202 util Module
2204 Module containing utility functions and classes for the Dogtag python
2205 code
2206 class pki.util.Version(obj)
2208 Bases: object
2209 pki.util.chmod(path, mode)
2211 Change permissions of a file, link, or folder recursively.
2212 pki.util.chown(path, uid, gid)
2214 Change ownership of a file, link, or folder recursively.
2215 pki.util.copy(source, dest, uid=- 1, gid=- 1, dir_mode=None,
2217 file_mode=None, force=False)
2218 Copy a file or a folder and its contents.
2219 pki.util.copydirs(source, dest, uid=- 1, gid=- 1, mode=None,
2221 force=False)
2222 Copy a folder and its parents (without the contents) while pre‐
2223 serving their attributes.
2224 pki.util.copyfile(source, dest, slots=None, params=None, uid=None,
2226 gid=None, mode=None, force=False)
2227 Copy a file or link while preserving its attributes.
2228 pki.util.copytree(src, dst, symlinks=False, ignore=None)
2230 Recursively copy a directory tree using copy2().
2231 PATCH: This code was copied from 'shutil.py' and patched to
2233 allow 'The destination directory to already exist.'
2234 If exception(s) occur, an Error is raised with a list of rea‐
2236 sons.
2237 If the optional symlinks flag is true, symbolic links in the
2239 source tree result in symbolic links in the destination tree; if
2240 it is false, the contents of the files pointed to by symbolic
2241 links are copied.
2242 The optional ignore argument is a callable. If given, it is
2244 called with the src parameter, which is the directory being vis‐
2245 ited by copytree(), and names which is the list of src contents,
2246 as returned by os.listdir():
2247 callable(src, names) -> ignored_names
2248 Since copytree() is called recursively, the callable will be
2250 called once for each directory that is copied. It returns a list
2251 of names relative to the src directory that should not be
2252 copied.
2253 Consider this example code rather than the ultimate tool.
2255 pki.util.customize_file(input_file, output_file, params)
2257 Customize a file with specified parameters.
2258 pki.util.load_properties(filename, properties)
2260 pki.util.makedirs(path, mode=511, exist_ok=False, uid=- 1, gid=- 1,
2262 force=False)
2263 pki.util.read_environment_files(env_file_list=None)
2265 pki.util.read_text(message, options=None, default=None, delimiter=':',
2267 case_sensitive=True, password=False, required=False)
2268 Get an input from the user. This is used, for example, in
2269 pkispawn and pkidestroy to obtain user input.
2270 Parameters
2272 • message (str) -- prompt to display to the user
2274 • options (list) -- list of possible inputs by the user.
2276 • default (str) -- default value of parameter being
2278 prompted.
2279 • delimiter (str) -- delimiter to be used at the end of
2281 the prompt.
2282 • case_sensitive (boolean -- True/False) -- Allow input
2284 to be case sensitive.
2285 • password (boolean -- True/False) -- Input is a pass‐
2287 word. Don't show the value.
2288 • required (boolean -- True/False) -- Input must be
2290 non-empty.
2291 Returns
2293 str -- value obtained from user input.
2294 pki.util.remove(path, force=False)
2296 pki.util.replace_params(line, params=None)
2298 Replace all occurrences of [param] in the line with the value of
2299 the parameter.
2300 pki.util.rmtree(path, force=False)
2302 pki.util.set_property(properties, name, value)
2304 pki.util.store_properties(filename, properties)
2306 pki.util.symlink(source, dest, uid=- 1, gid=- 1, force=False)
2308 pki.util.unlink(link, force=False)
2310 • genindex
2312 • modindex
2314 • search
2316
2318 Dogtag PKI Project Team
2319
2321 2022, Dogtag PKI Team
2322@APPLICATION_VERSION@ Feb 14, 2022 PKI-PYTHON-CLIENT(1)