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: PKIException
37 Bad Request Exception: return code = 400
39 exception pki.CertNotFoundException(message, exception=None, code=None,
41 class_name=None)
42 Bases: ResourceNotFoundException
43 Cert Not Found Exception: return code = 404
45 exception pki.ConflictingOperationException(message, exception=None,
47 code=None, class_name=None)
48 Bases: 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: PKIException
60 Forbidden Exception: return code = 403
62 exception pki.GroupNotFoundException(message, exception=None,
64 code=None, class_name=None)
65 Bases: ResourceNotFoundException
66 Group Not Found Exception: return code = 404
68 exception pki.HTTPGoneException(message, exception=None, code=None,
70 class_name=None)
71 Bases: PKIException
72 Gone Exception: return code = 410
74 exception pki.KeyNotFoundException(message, exception=None, code=None,
76 class_name=None)
77 Bases: ResourceNotFoundException
78 Key Not Found Exception: return code 404
80 exception pki.PKIException(message, exception=None, code=None,
82 class_name=None)
83 Bases: Exception, ResourceMessage
84 Base exception class for REST Interface
86 classmethod from_json(json_value)
88 Construct PKIException from JSON. :param json_value:
89 JSON representation of the exception. :type json_value:
90 str :return: pki.PKIException
91 exception pki.ProfileNotFoundException(message, exception=None,
93 code=None, class_name=None)
94 Bases: ResourceNotFoundException
95 Profile Not Found Exception: return code = 404
97 class pki.PropertyFile(filename, delimiter='=')
99 Bases: object
100 Class to manage property files The contents of the property
102 file are maintained internally as a list of properties.
103 Properties are strings of the format <name> <delimiter> <value>
105 where '=' is the default delimiter.
106 get(name)
108 Get the value of the specified property.
109 Parameters
111 name (str) -- name of property to be fetched.
112 Returns
114 str -- value of property
115 index(name)
117 Find the index (position) of a property in a property
118 file.
119 Parameters
121 name (str) -- name of property
122 Returns
124 int -- index of property.
125 insert_line(index, line)
127 Insert property into the list of properties maintained by
128 this object at the specified location (index).
129 Parameters
131 • index (int) -- point at which to insert value.
133 • line (str) -- value to be inserted.
135 Returns
137 None
138 read() Read from property file into the list of properties main‐
140 tained by this object.
141 Returns
143 None
144 remove(name)
146 Remove property from list of properties maintained by
147 this object.
148 Parameters
150 name (str) -- name of property to be removed.
151 Returns
153 None
154 remove_line(index)
156 Remove property at specified index from the properties
157 list.
158 Parameters
160 index (int) -- location of property to be removed.
161 Returns
163 None
164 set(name, value, index=None)
166 Set value of specified property.
167 Parameters
169 • name (str) -- name of property to set.
171 • value (str) -- value to set
173 • index (int) -- (optional) position of property
175 Returns
177 None
178 show() Print the contents of the list of properties maintained
180 by this object to STDOUT.
181 Returns
183 None
184 write()
186 Write the list of properties maintained by this object to
187 the property file.
188 Returns
190 None
191 exception pki.RequestNotFoundException(message, exception=None,
193 code=None, class_name=None)
194 Bases: ResourceNotFoundException
195 Request Not Found Exception: return code = 404
197 class pki.ResourceMessage(class_name)
199 Bases: object
200 This class is the basis for the various types of key requests.
202 It is essentially a list of attributes.
203 add_attribute(name, value)
205 Add an attribute to the list.
206 Parameters
208 • name (str) -- name of attribute to add
210 • value (str) -- value to add
212 Returns
214 None
215 get_attribute_value(name)
217 Get the value of a given attribute.
218 Parameters
220 name (str) -- name of attribute to retrieve
221 Returns
223 str -- value of parameter
224 exception pki.ResourceNotFoundException(message, exception=None,
226 code=None, class_name=None)
227 Bases: PKIException
228 Not Found Exception: return code = 404
230 exception pki.UnauthorizedException(message, exception=None, code=None,
232 class_name=None)
233 Bases: PKIException
234 Unauthorized Exception: return code = 401
236 exception pki.UserNotFoundException(message, exception=None, code=None,
238 class_name=None)
239 Bases: ResourceNotFoundException
240 User Not Found Exception: return code = 404
242 pki.convert_x509_name_to_dn(name)
244 Convert X.509 Name into NSS-style DN string.
245 See also: -
247 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.Name
248 -
249 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.RelativeDistinguishedName
250 -
251 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.NameAttribute
252 -
253 https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.ObjectIdentifier
254 Parameters
256 name (cryptography.x509.Name) -- X.509 Name
257 Returns
259 str -- DN string.
260 pki.generate_password(charset='0123456789abcdefghijklmnopqrstuvwxyz‐
262 ABCDEFGHIJKLMNOPQRSTUVWXYZ!#*+,-./:;^_|~', length=12)
263 This function generates FIPS-compliant password.
264 See sftk_newPinCheck() in the following file:
266 https://dxr.mozilla.org/nss/source/nss/lib/softoken/fipstokn.c
267 The minimum password length is FIPS_MIN_PIN Unicode characters.
269 The password must contain at least 3 character classes:
271 • digits (string.digits)
273 • ASCII lowercase letters (string.ascii_lowercase)
275 • ASCII uppercase letters (string.ascii_uppercase)
277 • ASCII non-alphanumeric characters (PUNCTUATIONS)
279 • non-ASCII characters
281 If an ASCII uppercase letter is the first character of the pass‐
283 word, the uppercase letter is not counted toward its character
284 class.
285 If a digit is the last character of the password, the digit is
287 not counted toward its character class.
288 The FIPS_MIN_PIN is defined in the following file:
290 https://dxr.mozilla.org/nss/source/nss/lib/softoken/pkcs11i.h
291 #define FIPS_MIN_PIN 7
293 pki.get_info(name)
295 pki.handle_exceptions()
297 Decorator handling exceptions from REST methods.
298 pki.implementation_version()
300 Return implementation version.
301 Returns
303 str -- implementation version
304 pki.specification_version()
306 Return specification version.
307 Returns
309 str -- specification version
310 account Module
312 class pki.account.AccountClient(connection, subsystem=None)
313 Bases: object
314 Class used to associate an authentication session variable with
316 a connection.
317 To use this class:
319 • set the authentication credentials with the connection,
321 • create an AccountClient and then call login().
323 • further operations in this session will use the same
325 authentication credentials without re-authentication.
326 • call logout() to invalidate the session.
328 login()
330 Login to account REST interface. If login is successful,
331 an authentication session variable is associated with the
332 connection.
333 Returns
335 None
336 logout()
338 Logs out of the session. Authentication session vari‐
339 ables are invalidated for the connection
340 Returns
342 None
343 cert Module
345 class pki.cert.CertClient(connection)
346 Bases: object
347 Class encapsulating and mirroring the functionality in the
349 CertResource Java interface class defining the REST API for Cer‐
350 tificate resources.
351 approve_request(request_id, cert_review_response=None)
353 Approves a certificate enrollment request. If cert_re‐
354 view_response is None, a review request operation is per‐
355 formed to fetch the CertReviewResponse object. Requires
356 as agent level authentication.
357 assign_request(request_id, cert_review_response)
359 Assigns a certificate enrollment request. If cert_re‐
360 view_response is None, a review request operation is per‐
361 formed to fetch the CertReviewResponse object. Requires
362 as agent level authentication.
363 cancel_request(request_id, cert_review_response=None)
365 Cancels a certificate enrollment request. If cert_re‐
366 view_response is None, a review request operation is per‐
367 formed to fetch the CertReviewResponse object. Requires
368 as agent level authentication.
369 create_enrollment_request(profile_id, inputs)
371 Fetches the enrollment request object for the given pro‐
372 file and sets values to its attributes using the values
373 provided in the inputs dictionary. Returns the CertEn‐
374 rollmentRequest object, which can be submitted to enroll
375 a certificate.
376 enroll_cert(profile_id, inputs, authority=None)
378 A convenience method for enrolling a certificate for a
379 given profile id. The inputs parameter should be a dic‐
380 tionary with values for the profile attributes for an en‐
381 rollment request.
382 Calling this method with valid arguments, creates an en‐
384 rollment request, submits it to the server, approves the
385 certificate requests generated for the enrollment and re‐
386 turns a list of CertData objects for all the certificates
387 generated as part of this enrollment.
388 Note: This method supports only certificate enrollment
390 where only one agent approval is sufficient.
391 Requires an agent level authentication. Returns a list
393 of CertEnrollmentResult objects.
394 get_cert(cert_serial_number)
396 Return a CertData object for a particular certificate.
397 get_enrollment_template(profile_id)
399 Fetch the enrollment template for the given profile id.
400 For the first time, the request is sent to the server.
401 The retrieved CertEnrollmentRequest object is then cached
402 locally for future requests. Returns a CerEnrollmentRe‐
403 quest object.
404 get_request(request_id)
406 Get information of a certificate request with the given
407 request ID. Returns a CertRequestInfo object.
408 hold_cert(cert_serial_number, comments=None, authority=None)
410 Places a certificate on-hold. Calls the revoke_cert
411 method with reason - CertRevokeRequest.REASON_CERTIFI‐
412 CATE_HOLD. Returns a CertRequestInfo object. This
413 method requires an agent's authentication cert in the
414 connection object.
415 list_certs(max_results=None, max_time=None, start=None,
417 size=None, **cert_search_params)
418 Return a CertDataInfoCollection object with a information
419 about all the certificates that satisfy the search crite‐
420 ria. If cert_search_request=None, returns all the cer‐
421 tificates.
422 list_enrollment_templates(start=None, size=None)
424 Gets the list of profile templates supported by the CA.
425 The values for start and size arguments determine the
426 starting point and the length of the list. Returns a
427 ProfileDataInfoCollection object.
428 list_requests(request_status=None, request_type=None, from_re‐
430 quest_id=None, size=None, max_results=None, max_time=None)
431 Query for a list of certificates using the arguments
432 passed. Returns a CertRequestInfoCollection object.
433 reject_request(request_id, cert_review_response=None)
435 Rejects a certificate enrollment request. If cert_re‐
436 view_response is None, a review request operation is per‐
437 formed to fetch the CertReviewResponse object. Requires
438 as agent level authentication.
439 review_cert(cert_serial_number)
441 Reviews a certificate. Returns a CertData object with a
442 nonce. This method requires an agent's authentication
443 cert in the connection object.
444 review_request(request_id)
446 Reviews a certificate enrollment request. Returns a
447 CertReviewResponse object which contains the nonce from
448 the server needed to perform an action on the request.
449 revoke_ca_cert(cert_serial_number, revocation_reason=None, inva‐
451 lidity_date=None, comments=None, nonce=None, authority=None)
452 Revokes a CA certificate. Returns a CertRequestInfo ob‐
453 ject with information about the request. This method re‐
454 quires an agent's authentication cert in the connection
455 object.
456 revoke_cert(cert_serial_number, revocation_reason=None, invalid‐
458 ity_date=None, comments=None, nonce=None, authority=None)
459 Revokes a certificate. Returns a CertRequestInfo object
460 with information about the request. This method requires
461 an agent's authentication cert in the connection object.
462 submit_enrollment_request(enrollment_request, authority=None)
464 Submits the CertEnrollmentRequest object to the server.
465 Returns a CertRequestInfoCollection object with informa‐
466 tion about the certificate requests enrolled at the CA.
467 unassign_request(request_id, cert_review_response)
469 Un-assigns a certificate enrollment request. If cert_re‐
470 view_response is None, a review request operation is per‐
471 formed to fetch the CertReviewResponse object. Requires
472 as agent level authentication.
473 unrevoke_cert(cert_serial_number, authority=None)
475 Un-revokes a revoked certificate. Returns a CertRe‐
476 questInfo object. This method requires an agent's au‐
477 thentication cert in the connection object.
478 update_request(request_id, cert_review_response)
480 Updates a certificate enrollment request. If cert_re‐
481 view_response is None, a review request operation is per‐
482 formed to fetch the CertReviewResponse object. Requires
483 as agent level authentication.
484 validate_request(request_id, cert_review_response)
486 Validates a certificate enrollment request. If cert_re‐
487 view_response is None, a review request operation is per‐
488 formed to fetch the CertReviewResponse object. Requires
489 as agent level authentication.
490 class pki.cert.CertData
492 Bases: object
493 Class containing certificate data as returned from getCert()
495 classmethod from_json(attr_list)
497 Return CertData object from JSON dict
498 json_attribute_names = {'Encoded': 'encoded', 'IssuerDN': 'is‐
500 suer_dn', 'Nonce': 'nonce', 'NotAfter': 'not_after', 'NotBe‐
501 fore': 'not_before', 'PKCS7CertChain': 'pkcs7_cert_chain',
502 'PrettyPrint': 'pretty_repr', 'Status': 'status', 'SubjectDN':
503 'subject_dn', 'id': 'serial_number'}
504 class pki.cert.CertDataInfo
506 Bases: object
507 Class containing information contained in a CertRecord on the
509 CA. This data is returned when searching/listing certificate
510 records.
511 classmethod from_json(attr_list)
513 Return CertDataInfo object from JSON dict
514 json_attribute_names = {'IssuedBy': 'issued_by', 'IssuedOn':
516 'issued_on', 'KeyAlgorithmOID': 'key_algorithm_oid',
517 'KeyLength': 'key_length', 'NotValidAfter': 'not_valid_after',
518 'NotValidBefore': 'not_valid_before', 'Status': 'status', 'Sub‐
519 jectDN': 'subject_dn', 'Type': 'type', 'Version': 'version',
520 'id': 'serial_number'}
521 class pki.cert.CertDataInfoCollection
523 Bases: object
524 Class containing list of CertDataInfo objects and their respec‐
526 tive link objects. This data is returned when searching/listing
527 certificate records in the CA.
528 classmethod from_json(json_value)
530 Populate object from JSON input
531 class pki.cert.CertEnrollmentRequest(profile_id=None, renewal=False,
533 serial_number=None, remote_host=None, remote_address=None, inputs=None,
534 outputs=None)
535 Bases: object
536 This class encapsulates the parameters required for a certifi‐
538 cate
539 enrollment request.
540 add_input(profile_input)
542 add_output(profile_output)
544 classmethod from_json(attr_list)
546 get_input(profile_input_name)
548 get_output(profile_output_name)
550 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
552 'ProfileID': 'profile_id', 'RemoteAddress': 'remote_address',
553 'RemoteHost': 'remote_host', 'Renewal': 'renewal', 'SerialNum‐
554 ber': 'serial_number'}
555 remove_input(profile_input_name)
557 remove_output(profile_output_name)
559 class pki.cert.CertEnrollmentResult(request, cert)
561 Bases: object
562 Class containing results of an enrollment request.
564 This structure contains information about the cert request gen‐
566 erated and any certificates issued.
567 class pki.cert.CertRequestInfo
569 Bases: object
570 An object of this class stores represents a certificate request.
572 classmethod from_json(attr_list)
574 json_attribute_names = {'certId': 'cert_id', 'certRequestType':
576 'cert_request_type', 'certURL': 'cert_url', 'errorMessage': 'er‐
577 ror_message', 'operationResult': 'operation_result', 'request‐
578 Status': 'request_status', 'requestType': 'request_type', 're‐
579 questURL': 'request_url'}
580 class pki.cert.CertRequestInfoCollection
582 Bases: object
583 Class containing list of CertRequestInfo objects. This data is
585 returned when listing certificate request records in the CA.
586 classmethod from_json(json_value)
588 Populate object from JSON input
589 class pki.cert.CertRequestStatus
591 Bases: object
592 Class containing valid cert statuses.
594 CANCELED = 'canceled'
596 COMPLETE = 'complete'
598 PENDING = 'pending'
600 REJECTED = 'rejected'
602 class pki.cert.CertReviewResponse(profile_id=None, renewal=False, se‐
604 rial_number=None, remote_host=None, remote_address=None, inputs=None,
605 outputs=None, nonce=None, request_id=None, request_type=None, re‐
606 quest_status=None, request_owner=None, request_creation_time=None, re‐
607 quest_modification_time=None, request_notes=None, profile_ap‐
608 proval_by=None, profile_set_id=None, profile_is_visible=None, pro‐
609 file_name=None, profile_description=None, profile_remote_host=None,
610 profile_remote_address=None, policy_sets=None)
611 Bases: CertEnrollmentRequest
612 An object of this class represent the response from the server
614 when reviewing a certificate enrollment request. It contains a
615 nonce required to perform action on the request.
616 classmethod from_json(attr_list)
618 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
620 'ProfileID': 'profile_id', 'ProfilePolicySet': 'policy_sets',
621 'RemoteAddress': 'remote_address', 'RemoteHost': 'remote_host',
622 'Renewal': 'renewal', 'SerialNumber': 'serial_number', 'pro‐
623 fileApprovedBy': 'profile_approved_by', 'profileDescription':
624 'profile_description', 'profileIsVisible': 'profile_is_visible',
625 'profileName': 'profile_name', 'profileRemoteAddr': 'profile_re‐
626 mote_address', 'profileRemoteHost': 'profile_remote_host', 'pro‐
627 fileSetId': 'profile_set_id', 'requestCreationTime': 're‐
628 quest_creation_time', 'requestId': 'request_id', 'requestModifi‐
629 cationTime': 'request_modification_time', 'requestNotes': 're‐
630 quest_notes', 'requestOwner': 'request_owner', 'requestStatus':
631 'request_status', 'requestType': 'request_type'}
632 class pki.cert.CertRevokeRequest(nonce, reason=None, invalid‐
634 ity_date=None, comments=None)
635 Bases: object
636 An object of this class encapsulates all the parameters required
638 for revoking a certificate.
639 Valid values for reasons for revoking a request are:
641 'Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affil‐
642 iation_Changed', 'Superseded', 'Cessation_of_Operation',
643 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_With‐
644 drawn', 'AA_Compromise'
645 reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise',
647 'Affiliation_Changed', 'Superseded', 'Cessation_of_Operation',
648 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_Withdrawn',
649 'AA_Compromise']
650 class pki.cert.CertSearchRequest(**cert_search_params)
652 Bases: object
653 An object of this class is used to store the search parameters
655 and send them to server.
656 search_params = {'cert_type_secure_email': 'certTypeSe‐
658 cureEmail', 'cert_type_ssl_client': 'certTypeSSLClient',
659 'cert_type_ssl_server': 'certTypeSSLServer',
660 'cert_type_sub_email_ca': 'certTypeSubEmailCA',
661 'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'common_name': 'com‐
662 monName', 'country': 'country', 'email': 'eMail', 'issued_by':
663 'issuedBy', 'issued_on_from': 'issuedOnFrom', 'issued_on_to':
664 'issuedOnTo', 'locality': 'locality', 'match_exactly': 'matchEx‐
665 actly', 'org': 'org', 'org_unit': 'orgUnit', 'revocation_rea‐
666 son': 'revocationReason', 'revoked_by': 'revokedBy', 're‐
667 voked_on_from': 'revokedOnFrom', 'revoked_on_to': 'revokedOnTo',
668 'serial_from': 'serialFrom', 'serial_to': 'serialTo', 'state':
669 'state', 'status': 'status', 'user_id': 'userID', 'valid_not_af‐
670 ter_from': 'validNotAfterFrom', 'valid_not_after_to': 'validNo‐
671 tAfterTo', 'valid_not_before_from': 'validNotBeforeFrom',
672 'valid_not_before_to': 'validNotBeforeTo', 'validity_count':
673 'validityCount', 'validity_operation': 'validityOperation', 'va‐
674 lidity_unit': 'validityUnit'}
675 pki.cert.main()
677 client Module
679 class pki.client.PKIConnection(protocol='http', hostname='localhost',
680 port='8080', subsystem=None, accept='application/json', trust_env=None,
681 verify=True, cert_paths=None)
682 Bases: object
683 Class to encapsulate the connection between the client and a
685 Dogtag subsystem.
686 authenticate(username=None, password=None)
688 Set the parameters used for authentication if user‐
689 name/password is to be used. Both username and password
690 must not be None. Note that this method only sets the
691 parameters. Actual authentication occurs when the con‐
692 nection is attempted,
693 Parameters
695 • username -- username to authenticate connection
697 • password -- password to authenticate connection
699 Returns
701 None
702 delete(path, headers=None, use_root_uri=False)
704 Uses python-requests to issue a DEL request to the
705 server.
706 Parameters
708 • path (str) -- path URI for the DEL request
710 • headers (dict) -- headers for the DEL request
712 • use_root_uri (boolean) -- use root URI instead
714 of subsystem URI as base
715 Returns
717 request.response -- response from the server
718 Raises Exception from python-requests in case the DEL was
720 not successful, or returns an error code.
721 get(path, headers=None, params=None, payload=None,
723 use_root_uri=False, timeout=None)
724 Uses python-requests to issue a GET request to the
725 server.
726 Parameters
728 • path (str) -- path URI for the GET request
730 • headers (dict) -- headers for the GET request
732 • params (dict or bytes) -- Query parameters for
734 the GET request
735 • payload (dict, bytes, file-like object) -- data
737 to be sent in the body of the request
738 • use_root_uri (boolean) -- use root URI instead
740 of subsystem URI as base
741 Returns
743 request.response -- response from the server
744 Raises Exception from python-requests in case the GET was
746 not successful, or returns an error code.
747 post(path, payload, headers=None, params=None,
749 use_root_uri=False)
750 Uses python-requests to issue a POST request to the
751 server.
752 Parameters
754 • path (str) -- path URI for the POST request
756 • payload (dict, bytes, file-like object) -- data
758 to be sent in the body of the request
759 • headers (dict) -- headers for the POST request
761 • params (dict or bytes) -- Query parameters for
763 the POST request
764 • use_root_uri (boolean) -- use root URI instead
766 of subsystem URI as base
767 Returns
769 request.response -- response from the server
770 Raises Exception from python-requests in case the POST
772 was not successful, or returns an error code.
773 put(path, payload, headers=None, use_root_uri=False)
775 Uses python-requests to issue a PUT request to the
776 server.
777 Parameters
779 • path (str) -- path URI for the PUT request
781 • payload (dict, bytes, file-like object) -- data
783 to be sent in the body of the request
784 • headers (dict) -- headers for the PUT request
786 • use_root_uri (boolean) -- use root URI instead
788 of subsystem URI as base
789 Returns
791 request.response -- response from the server
792 Raises Exception from python-requests in case the PUT was
794 not successful, or returns an error code.
795 set_authentication_cert(pem_cert_path, pem_key_path=None)
797 Set the path to the PEM file containing the certificate
798 and private key for the client certificate to be used for
799 authentication to the server, when client certificate au‐
800 thentication is required. The private key may optionally
801 be stored in a different path.
802 Parameters
804 • pem_cert_path (str) -- path to the PEM file
806 • pem_key_path (str) -- path to the PEM-formatted
808 private key file
809 Returns
811 None
812 Raises Exception if path is empty or None.
814 class pki.client.SSLContextAdapter(pool_connections=10, pool_max‐
816 size=10, max_retries=0, pool_block=False, verify=True, cert_paths=None)
817 Bases: HTTPAdapter
818 Custom SSLContext Adapter for requests
820 init_poolmanager(connections, maxsize, block=False,
822 **pool_kwargs)
823 Initializes a urllib3 PoolManager.
824 This method should not be called from user code, and is
826 only exposed for use when subclassing the HTTPAdapter.
827 Parameters
829 • connections -- The number of urllib3 connection
831 pools to cache.
832 • maxsize -- The maximum number of connections to
834 save in the pool.
835 • block -- Block when no free connections are
837 available.
838 • pool_kwargs -- Extra keyword arguments used to
840 initialize the Pool Manager.
841 pki.client.catch_insecure_warning(func)
843 Temporary silence InsecureRequestWarning
844 PKIConnection is not able to verify HTTPS connections yet. This
846 decorator catches the warning.
847 See https://fedorahosted.org/pki/ticket/1253
849 pki.client.main()
851 Test code for the PKIConnection class. :return: None
852 crypto Module
854 Module containing crypto classes.
855 class pki.crypto.CryptoProvider
857 Bases: object
858 Abstract class containing methods to do cryptographic opera‐
860 tions.
861 abstract asymmetric_wrap(data, wrapping_cert, mechanism=None)
863 encrypt a symmetric key with the public key of a trans‐
864 port cert.
865 The mechanism is the type of symmetric key, which de‐
867 faults to a 56 bit DES3 key.
868 abstract generate_nonce_iv(mechanism)
870 Create a random initialization vector
871 abstract generate_session_key()
873 Generate a session key to be used for wrapping data to
874 the DRM This must return a 3DES 168 bit key
875 abstract generate_symmetric_key(mechanism=None, size=0)
877 Generate and return a symmetric key
878 abstract get_cert(cert_nick)
880 Get the certificate for the specified cert_nick.
881 abstract get_supported_algorithm_keyset()
883 returns highest supported algorithm keyset
884 abstract initialize()
886 Initialization code
887 abstract key_unwrap(mechanism, data, wrapping_key, nonce_iv)
889 Unwrap data that has been key wrapped using AES KeyWrap
890 abstract set_algorithm_keyset(level)
892 sets required keyset
893 abstract symmetric_unwrap(data, wrapping_key, mechanism=None,
895 nonce_iv=None)
896 decrypt data originally encrypted with symmetric key
897 (wrapping key)
898 We expect the data and nonce_iv values to be base64 en‐
900 coded. The mechanism is the type of key used to do the
901 wrapping. It defaults to a 56 bit DES3 key.
902 abstract symmetric_wrap(data, wrapping_key, mechanism=None,
904 nonce_iv=None)
905 encrypt data using a symmetric key (wrapping key)
906 class pki.crypto.CryptographyCryptoProvider(transport_cert_nick, trans‐
908 port_cert, backend=<OpenSSLBackend(version: OpenSSL 3.0.5 5 Jul 2022,
909 FIPS: False)>)
910 Bases: CryptoProvider
911 Class that defines python-cryptography implementation of Crypto‐
913 Provider. Requires a PEM file containing the agent cert to be
914 initialized.
915 Note that all inputs and outputs are unencoded.
917 asymmetric_wrap(data, wrapping_cert, mechanism=None)
919 :param data Data to be wrapped :param wrap‐
920 ping_cert Public key to wrap data :param mechanism
921 algorithm of symmetric key to be wrapped
922 Wrap (encrypt) data using the supplied asymmetric key
924 generate_nonce_iv(mechanism='AES')
926 Create a random initialization vector
927 generate_session_key()
929 Returns a session key to be used when wrapping secrets
930 for the DRM.
931 generate_symmetric_key(mechanism=None, size=0)
933 Returns a symmetric key.
934 get_cert(cert_nick)
936 :param cert_nick Nickname for the certificate to be re‐
937 turned.
938 get_supported_algorithm_keyset()
940 returns highest supported algorithm keyset
941 initialize()
943 Any operations here that need to be performed before
944 crypto operations.
945 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
947 :param mechanism key wrapping mechanism :param
948 data: data to unwrap :param wrapping_key:
949 AES key used to wrap data :param nonce_iv Nonce
950 data :return: unwrapped data
951 Unwrap the encrypted data which has been wrapped using a
953 KeyWrap mechanism.
954 set_algorithm_keyset(level)
956 sets required keyset
957 symmetric_unwrap(data, wrapping_key, mechanism=None,
959 nonce_iv=None)
960 :param data Data to be unwrapped :param wrap‐
961 ping_key Symmetric key to unwrap data :param mechanism
962 Mechanism to use when unwrapping :param nonce_iv
963 iv data
964 Unwrap (decrypt) data using the supplied symmetric key
966 symmetric_wrap(data, wrapping_key, mechanism=None,
968 nonce_iv=None)
969 :param data Data to be wrapped :param wrap‐
970 ping_key Symmetric key to wrap data :param mechanism
971 Mechanism to use for wrapping key :param nonce_iv
972 Nonce for initialization vector
973 Wrap (encrypt) data using the supplied symmetric key
975 encoder Module
977 pki.encoder.CustomTypeDecoder(dct)
978 class pki.encoder.CustomTypeEncoder(*, skipkeys=False, en‐
980 sure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False,
981 indent=None, separators=None, default=None)
982 Bases: JSONEncoder
983 A custom JSONEncoder class that knows how to encode core custom
985 objects.
986 Custom objects are encoded as JSON object literals (ie, dicts)
988 with one key, 'TypeName' where 'TypeName' is the actual name of
989 the type to which the object belongs. That single key maps to
990 another object literal which is just the __dict__ of the object
991 encoded.
992 Reason for ignoring the error: E0202 - An attribute affected in
994 json.encoder line 157 hide this method reported by pylint:
995 The error is in json.encoder.JSONEncoder class. There is a de‐
997 fault method (which is overridden here) and also a class attri‐
998 bute self.default initialized in the init method of the class.
999 The intention of such usage being that a custom default method
1000 object can be passed to init when creating an instance of JSO‐
1001 NEncoder, which is then assigned to class's default method.
1002 (which is valid) But pylint raises an issue due to the usage of
1003 same name for a method and an attribute in which case the attri‐
1004 bute definition hides the method. The reason and example for
1005 the issue: (top rated comment)
1006 http://stackoverflow.com/questions/12949064/python-what-happens-
1007 when-instance-variable-name-is-same-as-method-name
1008 static attr_name_conversion(attr_dict, object_class)
1010 default(o)
1012 Implement this method in a subclass such that it returns
1013 a serializable object for o, or calls the base implemen‐
1014 tation (to raise a TypeError).
1015 For example, to support arbitrary iterators, you could
1017 implement default like this:
1018 def default(self, o):
1020 try:
1021 iterable = iter(o)
1022 except TypeError:
1023 pass
1024 else:
1025 return list(iterable)
1026 # Let the base class default method raise the TypeError
1027 return JSONEncoder.default(self, o)
1028 pki.encoder.decode_cert(data)
1030 base64 decode X.509 certificate
1031 Parameters
1033 data (str, bytes) -- data as bytes or ASCII text
1034 Return type
1036 bytes
1037 pki.encoder.encode_cert(data)
1039 base64 encode X.509 certificate
1040 Python 3's base64.b64encode() doesn't support ASCII text.
1042 Parameters
1044 data (str, bytes) -- data as bytes or ASCII text
1045 Return type
1047 bytes
1048 key Module
1050 Module containing the Python client classes for the KeyClient and
1051 KeyRequestClient REST API on a DRM
1052 class pki.key.AsymKeyGenerationRequest(client_key_id=None,
1054 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1055 sion_key=None, realm=None)
1056 Bases: ResourceMessage
1057 Class representing the data sent to the DRM when generating and
1059 archiving asymmetric keys in the DRM.
1060 DECRYPT_USAGE = 'decrypt'
1062 DERIVE_USAGE = 'derive'
1064 ENCRYPT_USAGE = 'encrypt'
1066 SIGN_RECOVER_USAGE = 'sign_recover'
1068 SIGN_USAGE = 'sign'
1070 UNWRAP_USAGE = 'unwrap'
1072 VERIFY_RECOVER_USAGE = 'verify_recover'
1074 VERIFY_USAGE = 'verify'
1076 WRAP_USAGE = 'wrap'
1078 class pki.key.Key(key_data)
1080 Bases: object
1081 An instance of this class stores the decoded encrypted secret
1083 present in the KeyData object passed in the constructor. All
1084 the key retrieval requests return this object.
1085 class pki.key.KeyArchivalRequest(client_key_id=None, data_type=None,
1087 wrapped_private_data=None, trans_wrapped_session_key=None, pki_ar‐
1088 chive_options=None, algorithm_oid=None, symkey_params=None, key_algo‐
1089 rithm=None, key_size=None, realm=None)
1090 Bases: ResourceMessage
1091 Class representing the object sent to the DRM when archiving a
1093 secret.
1094 class pki.key.KeyClient(connection, crypto, transport_cert_nick=None,
1096 info_client=None)
1097 Bases: object
1098 Class that encapsulates and mirrors the functions in the KeyRe‐
1100 source and KeyRequestResource Java classes in the DRM REST API.
1101 AES_ALGORITHM = 'AES'
1103 ASYMMETRIC_KEY_TYPE = 'asymmetricKey'
1105 DES3_ALGORITHM = 'DES3'
1107 DESEDE_ALGORITHM = 'DESede'
1109 DES_ALGORITHM = 'DES'
1111 DSA_ALGORITHM = 'DSA'
1113 KEY_STATUS_ACTIVE = 'active'
1115 KEY_STATUS_INACTIVE = 'inactive'
1117 PASS_PHRASE_TYPE = 'passPhrase'
1119 RC2_ALGORITHM = 'RC2'
1121 RC4_ALGORITHM = 'RC4'
1123 RSA_ALGORITHM = 'RSA'
1125 SYMMETRIC_KEY_TYPE = 'symmetricKey'
1127 approve_request(request_id)
1129 Approve a secret recovery request
1130 archive_encrypted_data(client_key_id, data_type, encrypted_data,
1132 wrapped_session_key, algorithm_oid=None, nonce_iv=None, key_al‐
1133 gorithm=None, key_size=None, realm=None)
1134 Archive a secret (symmetric key or passphrase) on the
1135 DRM.
1136 Refer to archive_key() comments for a description of
1138 client_key_id, data_type, key_algorithm and key_size.
1139 The following parameters are also required:
1141 • encrypted_data - which is the data encrypted by
1143 a session key (168 bit 3DES symmetric key)
1144 • wrapped_session_key - the above session key
1146 wrapped by the DRM transport certificate public
1147 key.
1148 • the algorithm_oid string for the symmetric key
1150 wrap
1151 • the nonce_iv for the symmetric key wrap
1153 This function is useful if the caller wants to do their
1155 own wrapping of the secret, or if the secret was gener‐
1156 ated on a separate client machine and the wrapping was
1157 done there.
1158 The function returns a KeyRequestResponse object contain‐
1160 ing a KeyRequestInfo object with details about the
1161 archival request and key archived.
1162 archive_key(client_key_id, data_type, private_data, key_algo‐
1164 rithm=None, key_size=None, realm=None)
1165 Archive a secret (symmetric key or passphrase) on the
1166 DRM.
1167 Requires a user-supplied client ID. There can be only
1169 one active key with a specified client ID. If a record
1170 for a duplicate active key exists, a BadRequestException
1171 is thrown.
1172 data_type can be one of the following:
1174 KeyClient.SYMMETRIC_KEY_TYPE, KeyClient.ASYMMET‐
1175 RIC_KEY_TYPE, KeyClient.PASS_PHRASE_TYPE
1176 key_algorithm and key_size are applicable to symmetric
1178 keys only. If a symmetric key is being archived, these
1179 parameters are required.
1180 private_data is the raw secret to be archived. It will
1182 be wrapped and sent to the DRM.
1183 The function returns a KeyRequestResponse object contain‐
1185 ing a KeyRequestInfo object with details about the
1186 archival request and key archived.
1187 archive_pki_options(client_key_id, data_type, pki_archive_op‐
1189 tions, key_algorithm=None, key_size=None, realm=None)
1190 Archive a secret (symmetric key or passphrase) on the
1191 DRM.
1192 Refer to archive_key() comments for a description of
1194 client_key_id, data_type, key_algorithm and key_size.
1195 pki_archive_options is the data to be archived wrapped in
1197 a PKIArchiveOptions structure,
1198 The function returns a KeyRequestResponse object contain‐
1200 ing a KeyRequestInfo object with details about the
1201 archival request and key archived.
1202 cancel_request(request_id)
1204 Cancel a secret recovery request
1205 generate_asymmetric_key(client_key_id, algorithm=None,
1207 key_size=None, usages=None, trans_wrapped_session_key=None,
1208 realm=None)
1209 Generate and archive asymmetric keys in the DRM. Sup‐
1210 ports algorithms RSA and DSA. Valid key size for RSA =
1211 256 + (16 * n), where n: 0-496 Valid key size for DSA =
1212 512, 768, 1024. p,q,g params are not supported.
1213 Return a KeyRequestResponse which contains a KeyRe‐
1215 questInfo object that describes the URL for the request
1216 and generated keys.
1217 generate_symmetric_key(client_key_id, algorithm=None, size=None,
1219 usages=None, trans_wrapped_session_key=None, realm=None)
1220 Generate and archive a symmetric key on the DRM.
1221 Return a KeyRequestResponse which contains a KeyRe‐
1223 questInfo object that describes the URL for the request
1224 and generated key.
1225 get_active_key_info(client_key_id)
1227 Get the info in the KeyRecord for the active secret in
1228 the DRM.
1229 get_client_keyset()
1231 get_key_info(key_id)
1233 Get the info in the KeyRecord for a specific secret in
1234 the DRM.
1235 get_request_info(request_id)
1237 Return a KeyRequestInfo object for a specific request.
1238 get_server_keyset()
1240 list_keys(client_key_id=None, status=None, max_results=None,
1242 max_time=None, start=None, size=None, realm=None)
1243 List/Search archived secrets in the DRM.
1244 See KRAClient.list_keys for the valid values of status.
1246 Returns a KeyInfoCollection object.
1247 list_requests(request_state=None, request_type=None,
1249 client_key_id=None, start=None, page_size=None, max_re‐
1250 sults=None, max_time=None, realm=None)
1251 List/Search key requests in the DRM.
1252 See KRAClient.list_requests for the valid values of re‐
1254 quest_state and request_type. Returns a KeyRequestInfo‐
1255 Collection object.
1256 modify_key_status(key_id, status)
1258 Modify the status of a key
1259 process_returned_key(key, session_key)
1261 Decrypt the returned key and place in key.data
1262 The data will either by encrypted using an encryption al‐
1264 gorithm - in which case, the key data will contain an en‐
1265 cryption algorithm OID, or it will be key wrapped - in
1266 which case, the key data will contain a key wrap mecha‐
1267 nism name.
1268 Only one of these should be present. If we are talking
1270 to an older server, and none is present, we will assume
1271 encryption.
1272 recover_key(key_id, request_id=None, ses‐
1274 sion_wrapped_passphrase=None, trans_wrapped_session_key=None,
1275 b64certificate=None, nonce_data=None)
1276 Create a request to recover a secret.
1277 To retrieve a symmetric key or passphrase, the only pa‐
1279 rameter that is required is the keyId. It is possible
1280 (but not required) to pass in the session keys/passphrase
1281 and nonceData for the retrieval at this time. Those pa‐
1282 rameters are documented in the docstring for retrieve_key
1283 below.
1284 To retrieve an asymmetric key, the keyId and the the
1286 base-64 encoded certificate is required.
1287 reject_request(request_id)
1289 Reject a secret recovery request.
1290 retrieve_key(key_id=None, trans_wrapped_session_key=None, re‐
1292 quest_id=None)
1293 Retrieve a secret (passphrase or symmetric key) from the
1294 DRM.
1295 This method will retrieve a key from the KRA given the
1297 key_id or request_id (one of which must be specified).
1298 The data is returned as a KeyData object (which is recast
1299 to a Key object).
1300 If request_id is specified, then the value of key_id is
1302 ignored. Exceptions will be thrown if the caller is not
1303 the originator of the request, or the request is not ap‐
1304 proved.
1305 If key_id is specified instead, the following behavior
1307 applies:
1308 • If the key can be retrieved synchronously - ie. only
1310 one agent's approval is required, then the KeyData will
1311 include the secret.
1312 • If the key cannot be retrieved synchronously - ie. if
1314 more than one approval is needed, then the KeyData ob‐
1315 ject will include the request ID for a recovery request
1316 that was created on the server. When that request is
1317 approved, callers can retrieve the key using re‐
1318 trieve_key() and setting the request_id.
1319 To ensure data security in transit, the data will be re‐
1321 turned encrypted by a session key (168 bit 3DES symmetric
1322 key) - which is first wrapped (encrypted) by the public
1323 key of the DRM transport certificate before being sent to
1324 the DRM. The parameter trans_wrapped_session_key refers
1325 to this wrapped session key.
1326 If the trans_wrapped_session_key is not provided by
1328 caller, the method will call CryptoProvider methods to
1329 generate and wrap the session key. The function will re‐
1330 turn the KeyData object with a private_data attribute
1331 which stores the unwrapped key information.
1332 If the trans_wrapped_session_key is provided by the
1334 caller, the method will simply pass the data to the KRA,
1335 and will return the secret wrapped in the session key.
1336 The secret will still need to be unwrapped by the caller.
1337 The function will return the KeyData object, where the
1338 KeyData structure includes the wrapped secret and some
1339 nonce data to be used as a salt when unwrapping.
1340 retrieve_key_by_passphrase(key_id=None, request_id=None,
1342 passphrase=None, trans_wrapped_session_key=None, ses‐
1343 sion_wrapped_passphrase=None, nonce_data=None)
1344 Retrieve a secret (passphrase or symmetric key) from the
1345 DRM using a passphrase.
1346 This function generates a key recovery request, approves
1348 it, and retrieves the secret referred to by key_id. This
1349 assumes that only one approval is required to authorize
1350 the recovery.
1351 The secret is secured in transit by wrapping the secret
1353 with a passphrase using PBE encryption.
1354 There are two ways of using this function:
1356 1. A passphrase is provided by the caller.
1358 In this case, CryptoProvider methods will be called to
1360 create the data to securely send the passphrase to the
1361 DRM. Basically, three pieces of data will be sent:
1362 • the passphrase wrapped by a 168 bit 3DES symmetric
1364 key (the session key). This is referred to as the
1365 parameter session_wrapped_passphrase.
1366 • the session key wrapped with the public key in the
1368 DRM transport certificate. This is referred to as
1369 the trans_wrapped_session_key.
1370 • ivps nonce data, referred to as nonce_data
1372 The function will return the tuple (KeyData, un‐
1374 wrapped_secret)
1375 2. The caller provides the trans_wrapped_session_key,
1377 session_wrapped_passphrase and nonce_data.
1378 In this case, the data will simply be passed to the
1380 DRM. The function will return the secret encrypted by
1381 the passphrase using PBE Encryption. The secret will
1382 still need to be decrypted by the caller.
1383 The function will return the tuple (KeyData, None)
1385 retrieve_key_by_pkcs12(key_id, certificate, passphrase)
1387 Retrieve an asymmetric private key and return it as
1388 PKCS12 data.
1389 This function generates a key recovery request, approves
1391 it, and retrieves the secret referred to by key_id in a
1392 PKCS12 file. This assumes that only one approval is re‐
1393 quired to authorize the recovery.
1394 This function requires the following parameters: - key_id
1396 : the ID of the key - certificate: the certificate asso‐
1397 ciated with the private key - passphrase: A passphrase
1398 for the pkcs12 file.
1399 The function returns a KeyData object.
1401 retrieve_key_data(data)
1403 Retrieve a secret from the DRM.
1404 @param: data - a KeyRecoveryRequest containing the keyId
1406 of the secret being retrieved, the request_id of the ap‐
1407 proved recovery request and a wrapping mechanism. More
1408 details at KRAClient.retrieve_key.
1409 Returns a KeyData object containing the wrapped secret.
1411 set_crypto_algorithms()
1413 set_transport_cert(transport_cert_nick)
1415 Set the transport certificate for crypto operations
1416 submit_request(request)
1418 Submit an archival, recovery or key generation request to
1419 the DRM.
1420 @param request - is either a KeyArchivalRequest, KeyRe‐
1422 coverRequest, SymKeyGenerationRequest or AsymKeyGenera‐
1423 tionRequest.
1424 returns a KeyRequestResponse object.
1426 class pki.key.KeyData
1428 Bases: object
1429 This is the object that contains the encoded wrapped secret when
1431 that secret is retrieved. It is used by the DRM to send informa‐
1432 tion of the key in the key retrieval requests.
1433 classmethod from_json(attr_list)
1435 Return a KeyData object from a JSON dict
1436 json_attribute_names = {'encryptAlgorithmOID': 'encrypt_algo‐
1438 rithm_oid', 'nonceData': 'nonce_data', 'publicKey': 'pub‐
1439 lic_key', 'requestID': 'request_id', 'wrapAlgorithm': 'wrap_al‐
1440 gorithm', 'wrappedPrivateData': 'wrapped_private_data'}
1441 class pki.key.KeyInfo
1443 Bases: object
1444 This is the object that contains information stored in the data‐
1446 base record for an archived secret. It does not contain the se‐
1447 cret itself.
1448 classmethod from_json(attr_list)
1450 Return KeyInfo from JSON dict
1451 get_key_id()
1453 Return the key ID as parsed from key URL
1454 json_attribute_names = {'clientKeyID': 'client_key_id',
1456 'keyURL': 'key_url', 'ownerName': 'owner_name', 'publicKey':
1457 'public_key'}
1458 class pki.key.KeyInfoCollection
1460 Bases: object
1461 This class represents data returned when searching the DRM
1463 archived secrets. Essentially, its a list of KeyInfo objects.
1464 classmethod from_json(json_value)
1466 Return a KeyInfoCollection object from its JSON represen‐
1467 tation
1468 class pki.key.KeyRecoveryRequest(key_id=None, request_id=None,
1470 trans_wrapped_session_key=None, session_wrapped_passphrase=None,
1471 nonce_data=None, certificate=None, passphrase=None, payload_wrap‐
1472 ping_name=None, payload_encryption_oid=None)
1473 Bases: ResourceMessage
1474 Class representing the data sent to the DRM when either creating
1476 a request for the recovery of a secret, or, once the request is
1477 approved, retrieving the secret.
1478 class pki.key.KeyRequestInfo
1480 Bases: object
1481 This class represents data about key requests (archival, recov‐
1483 ery, key generation etc.) in the DRM.
1484 classmethod from_json(attr_list)
1486 Return a KeyRequestInfo object from a JSON dict.
1487 get_key_id()
1489 Return the ID of the secret referred to by this request.
1490 get_request_id()
1492 Return the request ID by parsing the request URL.
1493 json_attribute_names = {'keyURL': 'key_url', 'requestStatus':
1495 'request_status', 'requestType': 'request_type', 'requestURL':
1496 'request_url'}
1497 class pki.key.KeyRequestInfoCollection
1499 Bases: object
1500 This class represents the data returned when searching the key
1502 requests in the DRM. Essentially, its a list of KeyRequestInfo
1503 objects.
1504 classmethod from_json(json_value)
1506 Return a KeyRequestInfoCollection object from its JSON
1507 representation.
1508 class pki.key.KeyRequestResponse
1510 Bases: object
1511 This class is returned when an archival, recovery or key genera‐
1513 tion request is created. It includes a KeyRequestInfo object
1514 with information about the created request, and a KeyData struc‐
1515 ture which contains the wrapped secret (if that operation is
1516 supported).
1517 classmethod from_json(json_value)
1519 Return a KeyRequestResponse object from its JSON repre‐
1520 sentation.
1521 get_key_id()
1523 Return the id for the key archived, recovered or gener‐
1524 ated
1525 get_request_id()
1527 Return the id for the created request
1528 class pki.key.RequestId(req_id)
1530 Bases: object
1531 Class representing a Request ID
1533 class pki.key.SymKeyGenerationRequest(client_key_id=None,
1535 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1536 sion_key=None, realm=None)
1537 Bases: ResourceMessage
1538 Class representing the data sent to the DRM when generating and
1540 archiving a symmetric key in the DRM.
1541 DECRYPT_USAGE = 'decrypt'
1543 ENCRYPT_USAGE = 'encrypt'
1545 SIGN_USAGE = 'sign'
1547 UNWRAP_USAGE = 'unwrap'
1549 VERIFY_USAGE = 'verify'
1551 WRAP_USAGE = 'wrap'
1553 pki.key.main()
1555 Some unit tests - basically printing different types of requests
1556 kra Module
1558 Module containing KRAClient class. This class should be used by Python
1559 clients to interact with the DRM to expose the functionality of the
1560 KeyClient and KeyRequestResource REST APIs.
1561 class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
1563 Bases: object
1564 Client class that models interactions with a KRA using the Key
1566 and KeyRequest REST APIs.
1567 profile Module
1569 class pki.profile.Descriptor(syntax=None, constraint=None, descrip‐
1570 tion=None, default_value=None)
1571 Bases: object
1572 This class represents the description of a ProfileAttribute. It
1574 stores information such as the syntax, constraint and default
1575 value of a profile attribute.
1576 classmethod from_json(attr_list)
1578 json_attribute_names = {'Constraint': 'constraint', 'Default‐
1580 Value': 'default_value', 'Description': 'description', 'Syntax':
1581 'syntax'}
1582 class pki.profile.PolicyConstraint(name=None, description=None,
1584 class_id=None, policy_constraint_values=None)
1585 Bases: object
1586 An object of this class contains the policy constraints applied
1588 to a ProfileInput used by a certificate enrollment request.
1589 add_constraint_value(policy_constraint_value)
1591 Add a PolicyConstraintValue to the policy_constraint_val‐
1592 ues list.
1593 classmethod from_json(attr_list)
1595 get_constraint_value(policy_constraint_value_name)
1597 Returns a PolicyConstraintValue object with the given
1598 name. None, if there is no match.
1599 json_attribute_names = {'classId': 'class_id', 'constraint':
1601 'policy_constraint_values', 'id': 'name'}
1602 remove_constraint_value(policy_constraint_value_name)
1604 Removes a PolicyConstraintValue with the given name form
1605 the policy_constraint_values list.
1606 class pki.profile.PolicyConstraintValue(name=None, value=None, descrip‐
1608 tor=None)
1609 Bases: object
1610 Represents a PolicyConstraintValue
1612 classmethod from_json(attr_list)
1614 property name
1616 class pki.profile.PolicyDefault(name=None, class_id=None, descrip‐
1618 tion=None, policy_attributes=None, policy_params=None)
1619 Bases: object
1620 An object of this class contains information of the default us‐
1622 age of a specific ProfileInput.
1623 add_attribute(policy_attribute)
1625 Add a policy attribute to the attribute list. @param
1626 policy_attribute - A ProfileAttribute object
1627 add_parameter(policy_parameter)
1629 Add a profile parameter to the parameters list. @param
1630 policy_parameter - A ProfileParameter object.
1631 classmethod from_json(attr_list)
1633 get_attribute(policy_attribute_name)
1635 Fetch the policy attribute with the given name from the
1636 attributes list.
1637 get_parameter(profile_parameter_name)
1639 Fetch a profile parameter with the given name from the
1640 parameters list.
1641 json_attribute_names = {'classId': 'class_id', 'id': 'name',
1643 'params': 'policy_params', 'policyAttribute': 'policy_at‐
1644 tributes'}
1645 remove_attribute(policy_attribute_name)
1647 Remove a policy attribute with the given name from the
1648 attributes list.
1649 remove_parameter(profile_parameter_name)
1651 Remove a profile parameter with the given name from the
1652 parameters list.
1653 class pki.profile.PolicySet(name=None, policy_list=None)
1655 Bases: object
1656 An object of this class contains a name value pair of the policy
1658 name and the ProfilePolicy object.
1659 add_policy(profile_policy)
1661 Add a ProfilePolicy object to the policy_list
1662 classmethod from_json(attr_list)
1664 get_policy(policy_id)
1666 Returns a ProfilePolicy object with the given profile id.
1667 json_attribute_names = {'id': 'name', 'value': 'policy_list'}
1669 remove_policy(policy_id)
1671 Removes a ProfilePolicy with the given ID from the Poli‐
1672 cySet.
1673 class pki.profile.PolicySetList(policy_sets=None)
1675 Bases: object
1676 An object of this class stores a list of ProfileSet objects.
1678 add_policy_set(policy_set)
1680 Add a PolicySet object to the policy_sets list.
1681 classmethod from_json(attr_list)
1683 get_policy_set(policy_set_name)
1685 Fetch the PolicySet object for the given name. Returns
1686 None, if not found.
1687 property policy_sets
1689 remove_policy_set(policy_set_name)
1691 Remove a PolicySet object with the given name from the
1692 policy_sets list.
1693 class pki.profile.Profile(profile_id=None, class_id=None, name=None,
1695 description=None, enabled=None, visible=None, enabled_by=None, authen‐
1696 ticator_id=None, authorization_acl=None, renewal=None, xml_output=None,
1697 inputs=None, outputs=None, policy_set_list=None, link=None)
1698 Bases: object
1699 This class represents an enrollment profile.
1701 add_input(profile_input)
1703 Add a ProfileInput object to the inputs list of the Pro‐
1704 file.
1705 add_output(profile_output)
1707 Add a ProfileOutput object to the outputs list of the
1708 Profile.
1709 add_policy_set(policy_set)
1711 Add a PolicySet object to the policy_sets list of the
1712 Profile.
1713 classmethod from_json(attr_list)
1715 get_input(profile_input_id)
1717 Fetches a ProfileInput with the given ProfileInput id.
1718 Returns None, if there is no matching input.
1719 get_output(profile_output_id)
1721 Fetches a ProfileOutput with the given ProfileOutput id.
1722 Returns None, if there is no matching output.
1723 get_policy_set(policy_set_name)
1725 Fetches a ProfileInput with the given ProfileInput id.
1726 Returns None, if there is no matching input.
1727 static get_profile_data_from_file(path_to_file)
1729 Reads the file for the serialized Profile object. Cur‐
1730 rently supports only data format in json.
1731 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
1733 'PolicySets': 'policy_set_list', 'authenticatorId': 'authentica‐
1734 tor_id', 'authzAcl': 'authorization_acl', 'classId': 'class_id',
1735 'enabledBy': 'enabled_by', 'id': 'profile_id', 'xmlOutput':
1736 'xml_output'}
1737 remove_input(profile_input_id)
1739 Remove a ProfileInput from the inputs list of the Pro‐
1740 file.
1741 remove_output(profile_output_id)
1743 Remove a ProfileOutput from the outputs list of the Pro‐
1744 file.
1745 remove_policy_set(policy_set_name)
1747 Remove a PolicySet from the policy_sets list of the Pro‐
1748 file.
1749 class pki.profile.ProfileAttribute(name=None, value=None, descrip‐
1751 tor=None)
1752 Bases: object
1753 Represents a profile attribute of a ProfileInput.
1755 classmethod from_json(attr_list)
1757 json_attribute_names = {'Descriptor': 'descriptor', 'Value':
1759 'value'}
1760 class pki.profile.ProfileClient(connection)
1762 Bases: object
1763 This class consists of methods for accessing the ProfileRe‐
1765 source.
1766 create_profile(profile_data)
1768 Create a new profile for the given Profile object.
1769 create_profile_from_file(path_to_file)
1771 Reads the file for the serialized Profile object. Per‐
1772 forms the profile create operation. Currently supports
1773 only data format in json.
1774 delete_profile(profile_id)
1776 Delete a profile with the given Profile Id.
1777 disable_profile(profile_id)
1779 Disables a profile.
1780 enable_profile(profile_id)
1782 Enables a profile.
1783 get_profile(profile_id)
1785 Fetches information for the profile for the given profile
1786 id. Returns a ProfileData object.
1787 list_profiles(start=None, size=None)
1789 Fetches the list of profiles. The start and size argu‐
1790 ments provide pagination support. Returns a Profile‐
1791 DataInfoCollection object.
1792 modify_profile(profile_data)
1794 Modify an existing profile with the given Profile object.
1795 modify_profile_from_file(path_to_file)
1797 Reads the file for the serialized Profile object. Per‐
1798 forms the profile modify operation. Currently supports
1799 only data format in json.
1800 class pki.profile.ProfileDataInfo
1802 Bases: object
1803 Stores information about a profile
1805 classmethod from_json(attr_list)
1807 json_attribute_names = {'profileDescription': 'profile_descrip‐
1809 tion', 'profileId': 'profile_id', 'profileName': 'profile_name',
1810 'profileURL': 'profile_url'}
1811 class pki.profile.ProfileDataInfoCollection
1813 Bases: object
1814 Represents a collection of ProfileDataInfo objects. Also encap‐
1816 sulates the links for the list of the objects stored.
1817 classmethod from_json(attr_list)
1819 class pki.profile.ProfileInput(profile_input_id=None, class_id=None,
1821 name=None, text=None, attributes=None, config_attributes=None)
1822 Bases: object
1823 This class encapsulates all the attributes of a profile to gen‐
1825 erate a specific property of a certificate. Ex. Subject name,
1826 Requestor Information etc.
1827 add_attribute(profile_attribute)
1829 Add a ProfileAttribute object to the attributes list.
1830 add_config_attribute(profile_attribute)
1832 Add a ProfileAttribute object to the config_attributes
1833 list.
1834 classmethod from_json(attr_list)
1836 get_attribute(profile_attribute_name)
1838 Returns a ProfileAttribute object for the given name.
1839 None, if no match.
1840 get_config_attribute(config_attribute_name)
1842 Returns a ProfileAttribute object with the given name.
1843 None, if there is no match in the config_attributes list.
1844 json_attribute_names = {'Attribute': 'attributes', 'ClassID':
1846 'class_id', 'ConfigAttribute': 'config_attributes', 'Name':
1847 'name', 'Text': 'text', 'id': 'profile_input_id'}
1848 remove_attribute(profile_attribute_name)
1850 Remove a ProfileAttribute object with the given name from
1851 the attributes list.
1852 remove_config_attribute(config_attribute_name)
1854 Remove a ProfileAttribute object with the given name from
1855 the config_attributes list.
1856 class pki.profile.ProfileOutput(profile_output_id=None, name=None,
1858 text=None, class_id=None, attributes=None)
1859 Bases: object
1860 This class defines the output of a certificate enrollment re‐
1862 quest using a profile.
1863 add_attribute(profile_attribute)
1865 Add a ProfileAttribute object to the attributes list.
1866 classmethod from_json(attr_list)
1868 get_attribute(profile_attribute_name)
1870 Returns a ProfileAttribute object for the given name.
1871 None, if no match.
1872 json_attribute_names = {'classId': 'class_id', 'id': 'pro‐
1874 file_output_id'}
1875 remove_attribute(profile_attribute_name)
1877 Remove a ProfileAttribute object with the given name from
1878 the attributes list.
1879 class pki.profile.ProfileParameter(name=None, value=None)
1881 Bases: object
1882 classmethod from_json(attr_list)
1884 class pki.profile.ProfilePolicy(policy_id=None, policy_default=None,
1886 policy_constraint=None)
1887 Bases: object
1888 This class represents the policy a profile adheres to. An ob‐
1890 ject of this class stores the default values for profile and the
1891 constraints present on the values of the attributes of the pro‐
1892 file submitted for an enrollment request.
1893 classmethod from_json(attr_list)
1895 json_attribute_names = {'constraint': 'policy_constraint',
1897 'def': 'policy_default', 'id': 'policy_id'}
1898 class pki.profile.ProfilePolicySet
1900 Bases: object
1901 Stores a list of ProfilePolicy objects.
1903 classmethod from_json(attr_list)
1905 pki.profile.main()
1907 system Module
1909 class pki.system.AdminSetupRequest
1910 Bases: object
1911 class pki.system.AdminSetupResponse
1913 Bases: object
1914 class pki.system.CertificateSetupRequest
1916 Bases: object
1917 class pki.system.CertificateSetupResponse
1919 Bases: object
1920 class pki.system.DomainInfo
1922 Bases: object
1923 Class representing the entire security domain. This is essen‐
1925 tially a list of SecurityDomainSubsystem components.
1926 classmethod from_json(json_value)
1928 Create a DomainInfo object from JSON.
1929 Parameters
1931 json_value (str) -- JSON representation of a secu‐
1932 rity domain.
1933 Returns
1935 DomainInfo
1936 property systems
1938 class pki.system.InstallToken
1940 Bases: object
1941 classmethod from_json(json_value)
1943 class pki.system.SecurityDomainClient(connection)
1945 Bases: object
1946 Client used to get the security domain from a security domain
1948 CA. The connection details for the security domain CA are spec‐
1949 ified in a PKIConnection object used to construct this client.
1950 get_domain_info()
1952 Contact the security domain CA specified in the connec‐
1953 tion object used to construct this client and get the se‐
1954 curity domain using the REST API.
1955 Returns
1957 pki.system.DomainInfo
1958 get_install_token(hostname, subsystem)
1960 Returns
1962 pki.system.InstallToken
1963 get_old_domain_info()
1965 Contact the security domain CA specified in the connec‐
1966 tion object used to construct this client and get the se‐
1967 curity domain using the old servlet-based interface.
1968 This method is useful when contacting old servers which
1969 do not provide the REST API.
1970 Returns
1972 pki.system.DomainInfo
1973 get_security_domain_info()
1975 class pki.system.SecurityDomainHost
1977 Bases: object
1978 Class representing a security domain host.
1980 classmethod from_json(json_value)
1982 Constructs a SecurityDomainHost object from JSON.
1983 Parameters
1985 json_value (str) -- JSON string representing a se‐
1986 curity domain host.
1987 Returns
1989 SecurityDomainHost
1990 class pki.system.SecurityDomainSubsystem
1992 Bases: object
1993 Class representing a security domain subsystem. This is essen‐
1995 tially a list of SecurityDomainHost objects of a particular sub‐
1996 system type (ca, kra, tps, tks, ocsp).
1997 classmethod from_json(json_value)
1999 Constructs a SecurityDomainSubsystem from a JSON repre‐
2000 sentation.
2001 Parameters
2003 json_value (str) -- JSON representation of the Se‐
2004 curity Domain Subsystem
2005 Returns
2007 SecurityDomainSubsystem
2008 get_host(hostname, secure_port)
2010 class pki.system.SystemCertData
2012 Bases: object
2013 Class used to represent the data for a system certificate, which
2015 is used in the data passed into and returned from the Java in‐
2016 stallation servlet during the execution of pkispawn.
2017 This class is the python equivalent of the Java class: com.net‐
2019 scape.certsrv.system.SystemCertData
2020 class pki.system.SystemConfigClient(connection, subsystem=None)
2022 Bases: object
2023 Client used to interact with the Java configuration servlet to
2025 configure a Dogtag subsystem during the execution of pkispawn.
2026 The connection details for the system being configured are
2028 passed in the PKIConnection object used when constructing this
2029 object.
2030 createCert(request)
2032 Create certificate.
2033 Parameters
2035 request (CertificateSetupRequest) -- Certificate
2036 setup request
2037 Returns
2039 SystemCertData
2040 createCertID(request)
2042 Create certificate ID.
2043 Parameters
2045 request (CertificateSetupRequest) -- Certificate
2046 setup request
2047 Returns
2049 SystemCertData
2050 createRequestID(request)
2052 Create certificate request ID.
2053 Parameters
2055 request (CertificateSetupRequest) -- Certificate
2056 setup request
2057 Returns
2059 SystemCertData
2060 initSubsystem(request)
2062 Initialize subsystem.
2063 Parameters
2065 request (CertificateSetupRequest) -- Certificate
2066 setup request
2067 class pki.system.SystemStatusClient(connection, subsystem=None)
2069 Bases: object
2070 Client used to check the status of a Dogtag subsystem.
2072 get_status(timeout=None)
2074 Checks the status of the subsystem by calling the getSta‐
2075 tus() servlet. This is used to determine if the server
2076 is up and ready to receive and process requests.
2077 Returns
2079 str - getStatus response
2080 systemcert Module
2082 Module containing the Python client classes for the SystemCert REST API
2083 class pki.systemcert.SystemCertClient(connection, subsystem=None)
2085 Bases: object
2086 Class encapsulating and mirroring the functionality in the Sys‐
2088 temCertResource Java interface class defining the REST API for
2089 system certificate resources.
2090 get_transport_cert()
2092 Return transport certificate.
2093 Returns
2095 pki.cert.CertData -- transport certificate data
2096 upgrade Module
2098 class pki.upgrade.PKIUpgradeScriptlet
2099 Bases: object
2100 backup(path)
2102 get_backup_dir()
2104 upgrade_system()
2106 class pki.upgrade.PKIUpgradeTracker(name, filename, delimiter='=', ver‐
2108 sion_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
2109 Bases: object
2110 get_index()
2112 get_version()
2114 remove()
2116 remove_index()
2118 remove_version()
2120 set(version)
2122 set_index(index)
2124 set_version(version)
2126 show()
2128 class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade')
2130 Bases: object
2131 all_versions()
2133 backup(scriptlet, path)
2135 copydirs(source, dest, force=False)
2137 copyfile(source, dest, force=False)
2139 get_current_version()
2141 get_target_version()
2143 get_tracker()
2145 init_scriptlet(scriptlet)
2147 is_complete()
2149 makedirs(path, exist_ok=False)
2151 record(scriptlet, path)
2153 remove_tracker()
2155 reset_tracker()
2157 revert()
2159 revert_scriptlet(scriptlet)
2161 revert_version(version)
2163 run_scriptlet(scriptlet)
2165 scriptlets(version)
2167 set_tracker(version)
2169 show_tracker()
2171 status()
2173 touch(path)
2175 update_tracker(scriptlet)
2177 upgrade()
2179 upgrade_version(version)
2181 validate()
2183 version_dir(version)
2185 versions()
2187 util Module
2189 Module containing utility functions and classes for the Dogtag python
2190 code
2191 class pki.util.Version(obj)
2193 Bases: object
2194 pki.util.chmod(path, mode)
2196 Change permissions of a file, link, or folder recursively.
2197 pki.util.chown(path, uid, gid)
2199 Change ownership of a file, link, or folder recursively.
2200 pki.util.copy(source, dest, uid=- 1, gid=- 1, dir_mode=None,
2202 file_mode=None, force=False)
2203 Copy a file or a folder and its contents.
2204 pki.util.copydirs(source, dest, uid=- 1, gid=- 1, mode=None,
2206 force=False)
2207 Copy a folder and its parents (without the contents) while pre‐
2208 serving their attributes.
2209 pki.util.copyfile(source, dest, slots=None, params=None, uid=None,
2211 gid=None, mode=None, force=False)
2212 Copy a file or link while preserving its attributes.
2213 pki.util.copytree(src, dst, symlinks=False, ignore=None)
2215 Recursively copy a directory tree using copy2().
2216 PATCH: This code was copied from 'shutil.py' and patched to
2218 allow 'The destination directory to already exist.'
2219 If exception(s) occur, an Error is raised with a list of rea‐
2221 sons.
2222 If the optional symlinks flag is true, symbolic links in the
2224 source tree result in symbolic links in the destination tree; if
2225 it is false, the contents of the files pointed to by symbolic
2226 links are copied.
2227 The optional ignore argument is a callable. If given, it is
2229 called with the src parameter, which is the directory being vis‐
2230 ited by copytree(), and names which is the list of src contents,
2231 as returned by os.listdir():
2232 callable(src, names) -> ignored_names
2233 Since copytree() is called recursively, the callable will be
2235 called once for each directory that is copied. It returns a list
2236 of names relative to the src directory that should not be
2237 copied.
2238 Consider this example code rather than the ultimate tool.
2240 pki.util.customize_file(input_file, output_file, params)
2242 Customize a file with specified parameters.
2243 pki.util.load_properties(filename, properties)
2245 pki.util.makedirs(path, mode=511, exist_ok=False, uid=- 1, gid=- 1,
2247 force=False)
2248 pki.util.read_environment_files(env_file_list=None)
2250 pki.util.read_text(message, options=None, default=None, delimiter=':',
2252 case_sensitive=True, password=False, required=False)
2253 Get an input from the user. This is used, for example, in
2254 pkispawn and pkidestroy to obtain user input.
2255 Parameters
2257 • message (str) -- prompt to display to the user
2259 • options (list) -- list of possible inputs by the user.
2261 • default (str) -- default value of parameter being
2263 prompted.
2264 • delimiter (str) -- delimiter to be used at the end of
2266 the prompt.
2267 • case_sensitive (boolean -- True/False) -- Allow input
2269 to be case sensitive.
2270 • password (boolean -- True/False) -- Input is a pass‐
2272 word. Don't show the value.
2273 • required (boolean -- True/False) -- Input must be
2275 non-empty.
2276 Returns
2278 str -- value obtained from user input.
2279 pki.util.remove(path, force=False)
2281 pki.util.replace_params(line, params=None)
2283 Replace all occurrences of [param] in the line with the value of
2284 the parameter.
2285 pki.util.rmtree(path, force=False)
2287 pki.util.set_property(properties, name, value)
2289 pki.util.store_properties(filename, properties)
2291 pki.util.symlink(source, dest, uid=- 1, gid=- 1, force=False)
2293 pki.util.unlink(link, force=False)
2295 • Index
2297 • Module Index
2299 • Search Page
2301
2303 Dogtag PKI Project Team
2304
2306 2022, Dogtag PKI Team
2307@APPLICATION_VERSION@ Jul 29, 2022 PKI-PYTHON-CLIENT(1)