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
369 cert_review_response is None, a review request operation
370 is performed to fetch the CertReviewResponse object.
371 Requires as agent level authentication.
372 assign_request(request_id, cert_review_response)
374 Assigns a certificate enrollment request. If
375 cert_review_response is None, a review request operation
376 is performed to fetch the CertReviewResponse object.
377 Requires as agent level authentication.
378 cancel_request(request_id, cert_review_response=None)
380 Cancels a certificate enrollment request. If
381 cert_review_response is None, a review request operation
382 is performed to fetch the CertReviewResponse object.
383 Requires 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
396 enrollment request.
397 Calling this method with valid arguments, creates an
399 enrollment request, submits it to the server, approves
400 the certificate requests generated for the enrollment and
401 returns a list of CertData objects for all the certifi‐
402 cates 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,
445 from_request_id=None, size=None, max_results=None,
446 max_time=None)
447 Query for a list of certificates using the arguments
448 passed. Returns a CertRequestInfoCollection object.
449 reject_request(request_id, cert_review_response=None)
451 Rejects a certificate enrollment request. If
452 cert_review_response is None, a review request operation
453 is performed to fetch the CertReviewResponse object.
454 Requires as agent level authentication.
455 review_cert(cert_serial_number)
457 Reviews a certificate. Returns a CertData object with a
458 nonce. This method requires an agent's authentication
459 cert in the connection object.
460 review_request(request_id)
462 Reviews a certificate enrollment request. Returns a
463 CertReviewResponse object which contains the nonce from
464 the server needed to perform an action on the request.
465 revoke_ca_cert(cert_serial_number, revocation_reason=None, inva‐
467 lidity_date=None, comments=None, nonce=None, authority=None)
468 Revokes a CA certificate. Returns a CertRequestInfo
469 object with information about the request. This method
470 requires an agent's authentication cert in the connection
471 object.
472 revoke_cert(cert_serial_number, revocation_reason=None, invalid‐
474 ity_date=None, comments=None, nonce=None, authority=None)
475 Revokes a certificate. Returns a CertRequestInfo object
476 with information about the request. This method requires
477 an agent's authentication cert in the connection object.
478 submit_enrollment_request(enrollment_request, authority=None)
480 Submits the CertEnrollmentRequest object to the server.
481 Returns a CertRequestInfoCollection object with informa‐
482 tion about the certificate requests enrolled at the CA.
483 unassign_request(request_id, cert_review_response)
485 Un-assigns a certificate enrollment request. If
486 cert_review_response is None, a review request operation
487 is performed to fetch the CertReviewResponse object.
488 Requires as agent level authentication.
489 unrevoke_cert(cert_serial_number, authority=None)
491 Un-revokes a revoked certificate. Returns a CertRe‐
492 questInfo object. This method requires an agent's
493 authentication cert in the connection object.
494 update_request(request_id, cert_review_response)
496 Updates a certificate enrollment request. If
497 cert_review_response is None, a review request operation
498 is performed to fetch the CertReviewResponse object.
499 Requires as agent level authentication.
500 validate_request(request_id, cert_review_response)
502 Validates a certificate enrollment request. If
503 cert_review_response is None, a review request operation
504 is performed to fetch the CertReviewResponse object.
505 Requires as agent level authentication.
506 class pki.cert.CertData
508 Bases: object
509 Class containing certificate data as returned from getCert()
511 classmethod from_json(attr_list)
513 Return CertData object from JSON dict
514 json_attribute_names = {'Encoded': 'encoded', 'IssuerDN':
516 'issuer_dn', 'Link': 'link', 'Nonce': 'nonce', 'NotAfter':
517 'not_after', 'NotBefore': 'not_before', 'PKCS7CertChain':
518 'pkcs7_cert_chain', 'PrettyPrint': 'pretty_repr', 'Status':
519 'status', 'SubjectDN': 'subject_dn', 'id': 'serial_number'}
520 class pki.cert.CertDataInfo
522 Bases: object
523 Class containing information contained in a CertRecord on the
525 CA. This data is returned when searching/listing certificate
526 records.
527 classmethod from_json(attr_list)
529 Return CertDataInfo object from JSON dict
530 json_attribute_names = {'IssuedBy': 'issued_by', 'IssuedOn':
532 'issued_on', 'KeyAlgorithmOID': 'key_algorithm_oid',
533 'KeyLength': 'key_length', 'Link': 'link', 'NotValidAfter':
534 'not_valid_after', 'NotValidBefore': 'not_valid_before', 'Sta‐
535 tus': 'status', 'SubjectDN': 'subject_dn', 'Type': 'type', 'Ver‐
536 sion': 'version', 'id': 'serial_number'}
537 class pki.cert.CertDataInfoCollection
539 Bases: object
540 Class containing list of CertDataInfo objects and their respec‐
542 tive link objects. This data is returned when searching/listing
543 certificate records in the CA.
544 classmethod from_json(json_value)
546 Populate object from JSON input
547 class pki.cert.CertEnrollmentRequest(profile_id=None, renewal=False,
549 serial_number=None, remote_host=None, remote_address=None, inputs=None,
550 outputs=None)
551 Bases: object
552 This class encapsulates the parameters required for a certifi‐
554 cate
555 enrollment request.
556 add_input(profile_input)
558 add_output(profile_output)
560 classmethod from_json(attr_list)
562 get_input(profile_input_name)
564 get_output(profile_output_name)
566 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
568 'ProfileID': 'profile_id', 'RemoteAddress': 'remote_address',
569 'RemoteHost': 'remote_host', 'Renewal': 'renewal', 'SerialNum‐
570 ber': 'serial_number'}
571 remove_input(profile_input_name)
573 remove_output(profile_output_name)
575 class pki.cert.CertEnrollmentResult(request, cert)
577 Bases: object
578 Class containing results of an enrollment request.
580 This structure contains information about the cert request gen‐
582 erated and any certificates issued.
583 class pki.cert.CertRequestInfo
585 Bases: object
586 An object of this class stores represents a certificate request.
588 classmethod from_json(attr_list)
590 json_attribute_names = {'certId': 'cert_id', 'certRequestType':
592 'cert_request_type', 'certURL': 'cert_url', 'errorMessage':
593 'error_message', 'operationResult': 'operation_result',
594 'requestStatus': 'request_status', 'requestType':
595 'request_type', 'requestURL': 'request_url'}
596 class pki.cert.CertRequestInfoCollection
598 Bases: object
599 Class containing list of CertRequestInfo objects. This data is
601 returned when listing certificate request records in the CA.
602 classmethod from_json(json_value)
604 Populate object from JSON input
605 class pki.cert.CertRequestStatus
607 Bases: object
608 Class containing valid cert statuses.
610 CANCELED = 'canceled'
612 COMPLETE = 'complete'
614 PENDING = 'pending'
616 REJECTED = 'rejected'
618 class pki.cert.CertReviewResponse(profile_id=None, renewal=False,
620 serial_number=None, remote_host=None, remote_address=None, inputs=None,
621 outputs=None, nonce=None, request_id=None, request_type=None,
622 request_status=None, request_owner=None, request_creation_time=None,
623 request_modification_time=None, request_notes=None, pro‐
624 file_approval_by=None, profile_set_id=None, profile_is_visible=None,
625 profile_name=None, profile_description=None, profile_remote_host=None,
626 profile_remote_address=None, policy_sets=None)
627 Bases: pki.cert.CertEnrollmentRequest
628 An object of this class represent the response from the server
630 when reviewing a certificate enrollment request. It contains a
631 nonce required to perform action on the request.
632 classmethod from_json(attr_list)
634 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
636 'ProfileID': 'profile_id', 'ProfilePolicySet': 'policy_sets',
637 'RemoteAddress': 'remote_address', 'RemoteHost': 'remote_host',
638 'Renewal': 'renewal', 'SerialNumber': 'serial_number', 'pro‐
639 fileApprovedBy': 'profile_approved_by', 'profileDescription':
640 'profile_description', 'profileIsVisible': 'profile_is_visible',
641 'profileName': 'profile_name', 'profileRemoteAddr': 'pro‐
642 file_remote_address', 'profileRemoteHost': 'pro‐
643 file_remote_host', 'profileSetId': 'profile_set_id',
644 'requestCreationTime': 'request_creation_time', 'requestId':
645 'request_id', 'requestModificationTime': 'request_modifica‐
646 tion_time', 'requestNotes': 'request_notes', 'requestOwner':
647 'request_owner', 'requestStatus': 'request_status', 'request‐
648 Type': 'request_type'}
649 class pki.cert.CertRevokeRequest(nonce, reason=None, invalid‐
651 ity_date=None, comments=None)
652 Bases: object
653 An object of this class encapsulates all the parameters required
655 for revoking a certificate.
656 Valid values for reasons for revoking a request are:
658 'Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affil‐
659 iation_Changed', 'Superseded', 'Cessation_of_Operation',
660 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_With‐
661 drawn', 'AA_Compromise'
662 reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise',
664 'Affiliation_Changed', 'Superseded', 'Cessation_of_Operation',
665 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_Withdrawn',
666 'AA_Compromise']
667 class pki.cert.CertSearchRequest(**cert_search_params)
669 Bases: object
670 An object of this class is used to store the search parameters
672 and send them to server.
673 search_params = {'cert_type_secure_email': 'certTypeSe‐
675 cureEmail', 'cert_type_ssl_client': 'certTypeSSLClient',
676 'cert_type_ssl_server': 'certTypeSSLServer',
677 'cert_type_sub_email_ca': 'certTypeSubEmailCA',
678 'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'common_name': 'com‐
679 monName', 'country': 'country', 'email': 'eMail', 'issued_by':
680 'issuedBy', 'issued_on_from': 'issuedOnFrom', 'issued_on_to':
681 'issuedOnTo', 'locality': 'locality', 'match_exactly': 'matchEx‐
682 actly', 'org': 'org', 'org_unit': 'orgUnit', 'revocation_rea‐
683 son': 'revocationReason', 'revoked_by': 'revokedBy',
684 'revoked_on_from': 'revokedOnFrom', 'revoked_on_to': 'revoke‐
685 dOnTo', 'serial_from': 'serialFrom', 'serial_to': 'serialTo',
686 'state': 'state', 'status': 'status', 'user_id': 'userID',
687 'valid_not_after_from': 'validNotAfterFrom',
688 'valid_not_after_to': 'validNotAfterTo',
689 'valid_not_before_from': 'validNotBeforeFrom',
690 'valid_not_before_to': 'validNotBeforeTo', 'validity_count':
691 'validityCount', 'validity_operation': 'validityOperation',
692 'validity_unit': 'validityUnit'}
693 pki.cert.main()
695 client Module
697 class pki.client.PKIConnection(protocol='http', hostname='localhost',
698 port='8080', subsystem=None, accept='application/json', trust_env=None,
699 verify=True, cert_paths=None)
700 Bases: object
701 Class to encapsulate the connection between the client and a
703 Dogtag subsystem.
704 authenticate(username=None, password=None)
706 Set the parameters used for authentication if user‐
707 name/password is to be used. Both username and password
708 must not be None. Note that this method only sets the
709 parameters. Actual authentication occurs when the con‐
710 nection is attempted,
711 Parameters
713 · username -- username to authenticate connection
715 · password -- password to authenticate connection
717 Returns
719 None
720 delete(path, headers=None, use_root_uri=False)
722 Uses python-requests to issue a DEL request to the
723 server.
724 Parameters
726 · path (str) -- path URI for the DEL request
728 · headers (dict) -- headers for the DEL request
730 · use_root_uri (boolean) -- use root URI instead
732 of subsystem URI as base
733 Returns
735 request.response -- response from the server
736 Raises Exception from python-requests in case the DEL was
738 not successful, or returns an error code.
739 get(path, headers=None, params=None, payload=None,
741 use_root_uri=False, timeout=None)
742 Uses python-requests to issue a GET request to the
743 server.
744 Parameters
746 · path (str) -- path URI for the GET request
748 · headers (dict) -- headers for the GET request
750 · params (dict or bytes) -- Query parameters for
752 the GET request
753 · payload (dict, bytes, file-like object) -- data
755 to be sent in the body of the request
756 · use_root_uri (boolean) -- use root URI instead
758 of subsystem URI as base
759 Returns
761 request.response -- response from the server
762 Raises Exception from python-requests in case the GET was
764 not successful, or returns an error code.
765 post(path, payload, headers=None, params=None,
767 use_root_uri=False)
768 Uses python-requests to issue a POST request to the
769 server.
770 Parameters
772 · path (str) -- path URI for the POST request
774 · payload (dict, bytes, file-like object) -- data
776 to be sent in the body of the request
777 · headers (dict) -- headers for the POST request
779 · params (dict or bytes) -- Query parameters for
781 the POST request
782 · use_root_uri (boolean) -- use root URI instead
784 of subsystem URI as base
785 Returns
787 request.response -- response from the server
788 Raises Exception from python-requests in case the POST
790 was not successful, or returns an error code.
791 put(path, payload, headers=None, use_root_uri=False)
793 Uses python-requests to issue a PUT request to the
794 server.
795 Parameters
797 · path (str) -- path URI for the PUT request
799 · payload (dict, bytes, file-like object) -- data
801 to be sent in the body of the request
802 · headers (dict) -- headers for the PUT request
804 · use_root_uri (boolean) -- use root URI instead
806 of subsystem URI as base
807 Returns
809 request.response -- response from the server
810 Raises Exception from python-requests in case the PUT was
812 not successful, or returns an error code.
813 set_authentication_cert(pem_cert_path, pem_key_path=None)
815 Set the path to the PEM file containing the certificate
816 and private key for the client certificate to be used for
817 authentication to the server, when client certificate
818 authentication is required. The private key may option‐
819 ally be stored in a different path.
820 Parameters
822 · pem_cert_path (str) -- path to the PEM file
824 · pem_key_path (str) -- path to the PEM-formatted
826 private key file
827 Returns
829 None
830 Raises Exception if path is empty or None.
832 class pki.client.SSLContextAdapter(pool_connections=10, pool_max‐
834 size=10, max_retries=0, pool_block=False, verify=True, cert_paths=None)
835 Bases: requests.adapters.HTTPAdapter
836 Custom SSLContext Adapter for requests
838 init_poolmanager(connections, maxsize, block=False,
840 **pool_kwargs)
841 Initializes a urllib3 PoolManager.
842 This method should not be called from user code, and is
844 only exposed for use when subclassing the HTTPAdapter.
845 Parameters
847 · connections -- The number of urllib3 connection
849 pools to cache.
850 · maxsize -- The maximum number of connections to
852 save in the pool.
853 · block -- Block when no free connections are
855 available.
856 · pool_kwargs -- Extra keyword arguments used to
858 initialize the Pool Manager.
859 pki.client.catch_insecure_warning(func)
861 Temporary silence InsecureRequestWarning
862 PKIConnection is not able to verify HTTPS connections yet. This
864 decorator catches the warning.
865 See https://fedorahosted.org/pki/ticket/1253
867 pki.client.main()
869 Test code for the PKIConnection class. :return: None
870 crypto Module
872 Module containing crypto classes.
873 class pki.crypto.CryptoProvider
875 Bases: object
876 Abstract class containing methods to do cryptographic opera‐
878 tions.
879 abstract asymmetric_wrap(data, wrapping_cert, mechanism=None)
881 encrypt a symmetric key with the public key of a trans‐
882 port cert.
883 The mechanism is the type of symmetric key, which
885 defaults to a 56 bit DES3 key.
886 abstract generate_nonce_iv(mechanism)
888 Create a random initialization vector
889 abstract generate_session_key()
891 Generate a session key to be used for wrapping data to
892 the DRM This must return a 3DES 168 bit key
893 abstract generate_symmetric_key(mechanism=None, size=0)
895 Generate and return a symmetric key
896 abstract get_cert(cert_nick)
898 Get the certificate for the specified cert_nick.
899 abstract get_supported_algorithm_keyset()
901 returns highest supported algorithm keyset
902 abstract initialize()
904 Initialization code
905 abstract key_unwrap(mechanism, data, wrapping_key, nonce_iv)
907 Unwrap data that has been key wrapped using AES KeyWrap
908 abstract set_algorithm_keyset(level)
910 sets required keyset
911 abstract symmetric_unwrap(data, wrapping_key, mechanism=None,
913 nonce_iv=None)
914 decrypt data originally encrypted with symmetric key
915 (wrapping key)
916 We expect the data and nonce_iv values to be base64
918 encoded. The mechanism is the type of key used to do the
919 wrapping. It defaults to a 56 bit DES3 key.
920 abstract symmetric_wrap(data, wrapping_key, mechanism=None,
922 nonce_iv=None)
923 encrypt data using a symmetric key (wrapping key)
924 class pki.crypto.CryptographyCryptoProvider(transport_cert_nick, trans‐
926 port_cert, backend=<cryptography.hazmat.backends.openssl.backend.Back‐
927 end object>)
928 Bases: pki.crypto.CryptoProvider
929 Class that defines python-cryptography implementation of Crypto‐
931 Provider. Requires a PEM file containing the agent cert to be
932 initialized.
933 Note that all inputs and outputs are unencoded.
935 asymmetric_wrap(data, wrapping_cert, mechanism=None)
937 :param data Data to be wrapped :param wrap‐
938 ping_cert Public key to wrap data :param mechanism
939 algorithm of symmetric key to be wrapped
940 Wrap (encrypt) data using the supplied asymmetric key
942 generate_nonce_iv(mechanism='AES')
944 Create a random initialization vector
945 generate_session_key()
947 Returns a session key to be used when wrapping secrets
948 for the DRM.
949 generate_symmetric_key(mechanism=None, size=0)
951 Returns a symmetric key.
952 get_cert(cert_nick)
954 :param cert_nick Nickname for the certificate to be
955 returned.
956 get_supported_algorithm_keyset()
958 returns highest supported algorithm keyset
959 initialize()
961 Any operations here that need to be performed before
962 crypto operations.
963 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
965 :param mechanism key wrapping mechanism :param
966 data: data to unwrap :param wrapping_key:
967 AES key used to wrap data :param nonce_iv Nonce
968 data :return: unwrapped data
969 Unwrap the encrypted data which has been wrapped using a
971 KeyWrap mechanism.
972 set_algorithm_keyset(level)
974 sets required keyset
975 symmetric_unwrap(data, wrapping_key, mechanism=None,
977 nonce_iv=None)
978 :param data Data to be unwrapped :param wrap‐
979 ping_key Symmetric key to unwrap data :param mechanism
980 Mechanism to use when unwrapping :param nonce_iv
981 iv data
982 Unwrap (decrypt) data using the supplied symmetric key
984 symmetric_wrap(data, wrapping_key, mechanism=None,
986 nonce_iv=None)
987 :param data Data to be wrapped :param wrap‐
988 ping_key Symmetric key to wrap data :param mechanism
989 Mechanism to use for wrapping key :param nonce_iv
990 Nonce for initialization vector
991 Wrap (encrypt) data using the supplied symmetric key
993 class pki.crypto.NSSCryptoProvider(certdb_dir, certdb_password=None,
995 password_file=None)
996 Bases: pki.crypto.CryptoProvider
997 Class that defines NSS implementation of CryptoProvider.
999 Requires an NSS database to have been set up and initialized.
1000 Note that all inputs and outputs are unencoded.
1002 asymmetric_wrap(data, wrapping_cert, mechanism=310)
1004 :param data Data to be wrapped :param wrap‐
1005 ping_cert Public key to wrap data :param mechanism
1006 algorithm of symmetric key to be wrapped
1007 Wrap (encrypt) data using the supplied asymmetric key
1009 generate_nonce_iv(mechanism=310)
1011 Create a random initialization vector
1012 generate_session_key()
1014 Returns a session key to be used when wrapping secrets
1015 for the DRM This will return a 168 bit 3DES key.
1016 generate_symmetric_key(mechanism=310, size=0)
1018 Returns a symmetric key.
1019 Note that for fixed length keys, this length should be 0.
1021 If no length is provided, then the function will either
1022 use 0 (for fixed length keys) or the maximum available
1023 length for that algorithm and the token.
1024 get_cert(cert_nick)
1026 :param cert_nick Nickname for the certificate to be
1027 returned
1028 Searches NSS database and returns SecItem object for this
1030 certificate.
1031 get_supported_algorithm_keyset()
1033 returns highest supported algorithm keyset
1034 import_cert(cert_nick, cert, trust=',,')
1036 Import a certificate into the nss database
1037 initialize()
1039 Initialize the nss db. Must be done before any crypto
1040 operations
1041 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
1043 :param mechanism Key wrapping mechanism :param
1044 data: Data to be unwrapped :param wrap‐
1045 ping_key: Wrapping Key :param nonce_iv Nonce
1046 data :return: Unwrapped data
1047 Return unwrapped data for data that has been keywrapped.
1049 For NSS, we only support 3DES - so something that has
1050 been keywrapped can be decrypted. This is precisely what
1051 we used to do before.
1052 set_algorithm_keyset(level)
1054 sets required keyset
1055 classmethod setup_contexts(mechanism, sym_key, nonce_iv)
1057 Set up contexts to do wrapping/unwrapping by symmetric
1058 keys.
1059 static setup_database(db_dir, password=None, over_write=False,
1061 password_file=None)
1062 Create an NSS database
1063 symmetric_unwrap(data, wrapping_key, mechanism=310,
1065 nonce_iv=None)
1066 :param data Data to be unwrapped :param wrap‐
1067 ping_key Symmetric key to unwrap data :param mechanism
1068 Mechanism to use when wrapping :param nonce_iv iv
1069 data
1070 Unwrap (decrypt) data using the supplied symmetric key
1072 symmetric_wrap(data, wrapping_key, mechanism=310, nonce_iv=None)
1074 :param data Data to be wrapped :param wrap‐
1075 ping_key Symmetric key to wrap data :param mechanism
1076 Mechanism to user when wrapping :param nonce_iv
1077 Nonce to use when wrapping
1078 Wrap (encrypt) data using the supplied symmetric key
1080 encoder Module
1082 pki.encoder.CustomTypeDecoder(dct)
1083 class pki.encoder.CustomTypeEncoder(*, skipkeys=False,
1085 ensure_ascii=True, check_circular=True, allow_nan=True,
1086 sort_keys=False, indent=None, separators=None, default=None)
1087 Bases: json.encoder.JSONEncoder
1088 A custom JSONEncoder class that knows how to encode core custom
1090 objects.
1091 Custom objects are encoded as JSON object literals (ie, dicts)
1093 with one key, 'TypeName' where 'TypeName' is the actual name of
1094 the type to which the object belongs. That single key maps to
1095 another object literal which is just the __dict__ of the object
1096 encoded.
1097 Reason for ignoring the error: E0202 - An attribute affected in
1099 json.encoder line 157 hide this method reported by pylint:
1100 The error is in json.encoder.JSONEncoder class. There is a
1102 default method (which is overridden here) and also a class
1103 attribute self.default initialized in the init method of the
1104 class. The intention of such usage being that a custom default
1105 method object can be passed to init when creating an instance of
1106 JSONEncoder, which is then assigned to class's default method.
1107 (which is valid) But pylint raises an issue due to the usage of
1108 same name for a method and an attribute in which case the
1109 attribute definition hides the method. The reason and example
1110 for the issue: (top rated comment)
1111 http://stackoverflow.com/questions/12949064/python-what-happens-
1112 when-instance-variable-name-is-same-as-method-name
1113 static attr_name_conversion(attr_dict, object_class)
1115 default(o)
1117 Implement this method in a subclass such that it returns
1118 a serializable object for o, or calls the base implemen‐
1119 tation (to raise a TypeError).
1120 For example, to support arbitrary iterators, you could
1122 implement default like this:
1123 def default(self, o):
1125 try:
1126 iterable = iter(o)
1127 except TypeError:
1128 pass
1129 else:
1130 return list(iterable)
1131 # Let the base class default method raise the TypeError
1132 return JSONEncoder.default(self, o)
1133 pki.encoder.decode_cert(data)
1135 base64 decode X.509 certificate
1136 Parameters
1138 data (str, bytes) -- data as bytes or ASCII text
1139 Return type
1141 bytes
1142 pki.encoder.encode_cert(data)
1144 base64 encode X.509 certificate
1145 Python 3's base64.b64encode() doesn't support ASCII text.
1147 Parameters
1149 data (str, bytes) -- data as bytes or ASCII text
1150 Return type
1152 bytes
1153 key Module
1155 Module containing the Python client classes for the KeyClient and
1156 KeyRequestClient REST API on a DRM
1157 class pki.key.AsymKeyGenerationRequest(client_key_id=None,
1159 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1160 sion_key=None, realm=None)
1161 Bases: pki.ResourceMessage
1162 Class representing the data sent to the DRM when generating and
1164 archiving asymmetric keys in the DRM.
1165 DECRYPT_USAGE = 'decrypt'
1167 DERIVE_USAGE = 'derive'
1169 ENCRYPT_USAGE = 'encrypt'
1171 SIGN_RECOVER_USAGE = 'sign_recover'
1173 SIGN_USAGE = 'sign'
1175 UNWRAP_USAGE = 'unwrap'
1177 VERIFY_RECOVER_USAGE = 'verify_recover'
1179 VERIFY_USAGE = 'verify'
1181 WRAP_USAGE = 'wrap'
1183 class pki.key.Key(key_data)
1185 Bases: object
1186 An instance of this class stores the decoded encrypted secret
1188 present in the KeyData object passed in the constructor. All
1189 the key retrieval requests return this object.
1190 class pki.key.KeyArchivalRequest(client_key_id=None, data_type=None,
1192 wrapped_private_data=None, trans_wrapped_session_key=None, pki_ar‐
1193 chive_options=None, algorithm_oid=None, symkey_params=None, key_algo‐
1194 rithm=None, key_size=None, realm=None)
1195 Bases: pki.ResourceMessage
1196 Class representing the object sent to the DRM when archiving a
1198 secret.
1199 class pki.key.KeyClient(connection, crypto, transport_cert_nick=None,
1201 info_client=None)
1202 Bases: object
1203 Class that encapsulates and mirrors the functions in the KeyRe‐
1205 source and KeyRequestResource Java classes in the DRM REST API.
1206 AES_ALGORITHM = 'AES'
1208 ASYMMETRIC_KEY_TYPE = 'asymmetricKey'
1210 DES3_ALGORITHM = 'DES3'
1212 DESEDE_ALGORITHM = 'DESede'
1214 DES_ALGORITHM = 'DES'
1216 DSA_ALGORITHM = 'DSA'
1218 KEY_STATUS_ACTIVE = 'active'
1220 KEY_STATUS_INACTIVE = 'inactive'
1222 PASS_PHRASE_TYPE = 'passPhrase'
1224 RC2_ALGORITHM = 'RC2'
1226 RC4_ALGORITHM = 'RC4'
1228 RSA_ALGORITHM = 'RSA'
1230 SYMMETRIC_KEY_TYPE = 'symmetricKey'
1232 approve_request(request_id)
1234 Approve a secret recovery request
1235 archive_encrypted_data(client_key_id, data_type, encrypted_data,
1237 wrapped_session_key, algorithm_oid=None, nonce_iv=None,
1238 key_algorithm=None, key_size=None, realm=None)
1239 Archive a secret (symmetric key or passphrase) on the
1240 DRM.
1241 Refer to archive_key() comments for a description of
1243 client_key_id, data_type, key_algorithm and key_size.
1244 The following parameters are also required:
1246 · encrypted_data - which is the data encrypted by
1248 a session key (168 bit 3DES symmetric key)
1249 · wrapped_session_key - the above session key
1251 wrapped by the DRM transport certificate public
1252 key.
1253 · the algorithm_oid string for the symmetric key
1255 wrap
1256 · the nonce_iv for the symmetric key wrap
1258 This function is useful if the caller wants to do their
1260 own wrapping of the secret, or if the secret was gener‐
1261 ated on a separate client machine and the wrapping was
1262 done there.
1263 The function returns a KeyRequestResponse object contain‐
1265 ing a KeyRequestInfo object with details about the
1266 archival request and key archived.
1267 archive_key(client_key_id, data_type, private_data, key_algo‐
1269 rithm=None, key_size=None, realm=None)
1270 Archive a secret (symmetric key or passphrase) on the
1271 DRM.
1272 Requires a user-supplied client ID. There can be only
1274 one active key with a specified client ID. If a record
1275 for a duplicate active key exists, a BadRequestException
1276 is thrown.
1277 data_type can be one of the following:
1279 KeyClient.SYMMETRIC_KEY_TYPE, KeyClient.ASYMMET‐
1280 RIC_KEY_TYPE, KeyClient.PASS_PHRASE_TYPE
1281 key_algorithm and key_size are applicable to symmetric
1283 keys only. If a symmetric key is being archived, these
1284 parameters are required.
1285 private_data is the raw secret to be archived. It will
1287 be wrapped and sent to the DRM.
1288 The function returns a KeyRequestResponse object contain‐
1290 ing a KeyRequestInfo object with details about the
1291 archival request and key archived.
1292 archive_pki_options(client_key_id, data_type, pki_ar‐
1294 chive_options, key_algorithm=None, key_size=None, realm=None)
1295 Archive a secret (symmetric key or passphrase) on the
1296 DRM.
1297 Refer to archive_key() comments for a description of
1299 client_key_id, data_type, key_algorithm and key_size.
1300 pki_archive_options is the data to be archived wrapped in
1302 a PKIArchiveOptions structure,
1303 The function returns a KeyRequestResponse object contain‐
1305 ing a KeyRequestInfo object with details about the
1306 archival request and key archived.
1307 cancel_request(request_id)
1309 Cancel a secret recovery request
1310 generate_asymmetric_key(client_key_id, algorithm=None,
1312 key_size=None, usages=None, trans_wrapped_session_key=None,
1313 realm=None)
1314 Generate and archive asymmetric keys in the DRM. Sup‐
1315 ports algorithms RSA and DSA. Valid key size for RSA =
1316 256 + (16 * n), where n: 0-496 Valid key size for DSA =
1317 512, 768, 1024. p,q,g params are not supported.
1318 Return a KeyRequestResponse which contains a KeyRe‐
1320 questInfo object that describes the URL for the request
1321 and generated keys.
1322 generate_symmetric_key(client_key_id, algorithm=None, size=None,
1324 usages=None, trans_wrapped_session_key=None, realm=None)
1325 Generate and archive a symmetric key on the DRM.
1326 Return a KeyRequestResponse which contains a KeyRe‐
1328 questInfo object that describes the URL for the request
1329 and generated key.
1330 get_active_key_info(client_key_id)
1332 Get the info in the KeyRecord for the active secret in
1333 the DRM.
1334 get_client_keyset()
1336 get_key_info(key_id)
1338 Get the info in the KeyRecord for a specific secret in
1339 the DRM.
1340 get_request_info(request_id)
1342 Return a KeyRequestInfo object for a specific request.
1343 get_server_keyset()
1345 list_keys(client_key_id=None, status=None, max_results=None,
1347 max_time=None, start=None, size=None, realm=None)
1348 List/Search archived secrets in the DRM.
1349 See KRAClient.list_keys for the valid values of status.
1351 Returns a KeyInfoCollection object.
1352 list_requests(request_state=None, request_type=None,
1354 client_key_id=None, start=None, page_size=None,
1355 max_results=None, max_time=None, realm=None)
1356 List/Search key requests in the DRM.
1357 See KRAClient.list_requests for the valid values of
1359 request_state and request_type. Returns a KeyRequestIn‐
1360 foCollection object.
1361 modify_key_status(key_id, status)
1363 Modify the status of a key
1364 process_returned_key(key, session_key)
1366 Decrypt the returned key and place in key.data
1367 The data will either by encrypted using an encryption
1369 algorithm - in which case, the key data will contain an
1370 encryption algorithm OID, or it will be key wrapped - in
1371 which case, the key data will contain a key wrap mecha‐
1372 nism name.
1373 Only one of these should be present. If we are talking
1375 to an older server, and none is present, we will assume
1376 encryption.
1377 recover_key(key_id, request_id=None, ses‐
1379 sion_wrapped_passphrase=None, trans_wrapped_session_key=None,
1380 b64certificate=None, nonce_data=None)
1381 Create a request to recover a secret.
1382 To retrieve a symmetric key or passphrase, the only
1384 parameter that is required is the keyId. It is possible
1385 (but not required) to pass in the session keys/passphrase
1386 and nonceData for the retrieval at this time. Those
1387 parameters are documented in the docstring for
1388 retrieve_key below.
1389 To retrieve an asymmetric key, the keyId and the the
1391 base-64 encoded certificate is required.
1392 reject_request(request_id)
1394 Reject a secret recovery request.
1395 retrieve_key(key_id=None, trans_wrapped_session_key=None,
1397 request_id=None)
1398 Retrieve a secret (passphrase or symmetric key) from the
1399 DRM.
1400 This method will retrieve a key from the KRA given the
1402 key_id or request_id (one of which must be specified).
1403 The data is returned as a KeyData object (which is recast
1404 to a Key object).
1405 If request_id is specified, then the value of key_id is
1407 ignored. Exceptions will be thrown if the caller is not
1408 the originator of the request, or the request is not
1409 approved.
1410 If key_id is specified instead, the following behavior
1412 applies:
1413 · If the key can be retrieved synchronously - ie. only
1415 one agent's approval is required, then the KeyData will
1416 include the secret.
1417 · If the key cannot be retrieved synchronously - ie. if
1419 more than one approval is needed, then the KeyData
1420 object will include the request ID for a recovery
1421 request that was created on the server. When that
1422 request is approved, callers can retrieve the key using
1423 retrieve_key() and setting the request_id.
1424 To ensure data security in transit, the data will be
1426 returned encrypted by a session key (168 bit 3DES symmet‐
1427 ric key) - which is first wrapped (encrypted) by the pub‐
1428 lic key of the DRM transport certificate before being
1429 sent to the DRM. The parameter trans_wrapped_session_key
1430 refers to this wrapped session key.
1431 If the trans_wrapped_session_key is not provided by call‐
1433 er, the method will call CryptoProvider methods to gener‐
1434 ate and wrap the session key. The function will return
1435 the KeyData object with a private_data attribute which
1436 stores the unwrapped key information.
1437 If the trans_wrapped_session_key is provided by the call‐
1439 er, the method will simply pass the data to the KRA, and
1440 will return the secret wrapped in the session key. The
1441 secret will still need to be unwrapped by the caller.
1442 The function will return the KeyData object, where the
1443 KeyData structure includes the wrapped secret and some
1444 nonce data to be used as a salt when unwrapping.
1445 retrieve_key_by_passphrase(key_id=None, request_id=None,
1447 passphrase=None, trans_wrapped_session_key=None, ses‐
1448 sion_wrapped_passphrase=None, nonce_data=None)
1449 Retrieve a secret (passphrase or symmetric key) from the
1450 DRM using a passphrase.
1451 This function generates a key recovery request, approves
1453 it, and retrieves the secret referred to by key_id. This
1454 assumes that only one approval is required to authorize
1455 the recovery.
1456 The secret is secured in transit by wrapping the secret
1458 with a passphrase using PBE encryption.
1459 There are two ways of using this function:
1461 1. A passphrase is provided by the caller.
1463 In this case, CryptoProvider methods will be called to
1465 create the data to securely send the passphrase to the
1466 DRM. Basically, three pieces of data will be sent:
1467 · the passphrase wrapped by a 168 bit 3DES symmetric
1469 key (the session key). This is referred to as the
1470 parameter session_wrapped_passphrase.
1471 · the session key wrapped with the public key in the
1473 DRM transport certificate. This is referred to as
1474 the trans_wrapped_session_key.
1475 · ivps nonce data, referred to as nonce_data
1477 The function will return the tuple (KeyData,
1479 unwrapped_secret)
1480 2. The caller provides the trans_wrapped_session_key,
1482 session_wrapped_passphrase and nonce_data.
1483 In this case, the data will simply be passed to the
1485 DRM. The function will return the secret encrypted by
1486 the passphrase using PBE Encryption. The secret will
1487 still need to be decrypted by the caller.
1488 The function will return the tuple (KeyData, None)
1490 retrieve_key_by_pkcs12(key_id, certificate, passphrase)
1492 Retrieve an asymmetric private key and return it as
1493 PKCS12 data.
1494 This function generates a key recovery request, approves
1496 it, and retrieves the secret referred to by key_id in a
1497 PKCS12 file. This assumes that only one approval is
1498 required to authorize the recovery.
1499 This function requires the following parameters: - key_id
1501 : the ID of the key - certificate: the certificate asso‐
1502 ciated with the private key - passphrase: A passphrase
1503 for the pkcs12 file.
1504 The function returns a KeyData object.
1506 retrieve_key_data(data)
1508 Retrieve a secret from the DRM.
1509 @param: data - a KeyRecoveryRequest containing the keyId
1511 of the secret being retrieved, the request_id of the
1512 approved recovery request and a wrapping mechanism. More
1513 details at KRAClient.retrieve_key.
1514 Returns a KeyData object containing the wrapped secret.
1516 set_crypto_algorithms()
1518 set_transport_cert(transport_cert_nick)
1520 Set the transport certificate for crypto operations
1521 submit_request(request)
1523 Submit an archival, recovery or key generation request to
1524 the DRM.
1525 @param request - is either a KeyArchivalRequest, KeyRe‐
1527 coverRequest, SymKeyGenerationRequest or AsymKeyGenera‐
1528 tionRequest.
1529 returns a KeyRequestResponse object.
1531 class pki.key.KeyData
1533 Bases: object
1534 This is the object that contains the encoded wrapped secret when
1536 that secret is retrieved. It is used by the DRM to send informa‐
1537 tion of the key in the key retrieval requests.
1538 classmethod from_json(attr_list)
1540 Return a KeyData object from a JSON dict
1541 json_attribute_names = {'encryptAlgorithmOID': 'encrypt_algo‐
1543 rithm_oid', 'nonceData': 'nonce_data', 'publicKey': 'pub‐
1544 lic_key', 'requestID': 'request_id', 'wrapAlgorithm':
1545 'wrap_algorithm', 'wrappedPrivateData': 'wrapped_private_data'}
1546 class pki.key.KeyInfo
1548 Bases: object
1549 This is the object that contains information stored in the data‐
1551 base record for an archived secret. It does not contain the
1552 secret itself.
1553 classmethod from_json(attr_list)
1555 Return KeyInfo from JSON dict
1556 get_key_id()
1558 Return the key ID as parsed from key URL
1559 json_attribute_names = {'clientKeyID': 'client_key_id',
1561 'keyURL': 'key_url', 'ownerName': 'owner_name', 'publicKey':
1562 'public_key'}
1563 class pki.key.KeyInfoCollection
1565 Bases: object
1566 This class represents data returned when searching the DRM
1568 archived secrets. Essentially, its a list of KeyInfo objects.
1569 classmethod from_json(json_value)
1571 Return a KeyInfoCollection object from its JSON represen‐
1572 tation
1573 class pki.key.KeyRecoveryRequest(key_id=None, request_id=None,
1575 trans_wrapped_session_key=None, session_wrapped_passphrase=None,
1576 nonce_data=None, certificate=None, passphrase=None, payload_wrap‐
1577 ping_name=None, payload_encryption_oid=None)
1578 Bases: pki.ResourceMessage
1579 Class representing the data sent to the DRM when either creating
1581 a request for the recovery of a secret, or, once the request is
1582 approved, retrieving the secret.
1583 class pki.key.KeyRequestInfo
1585 Bases: object
1586 This class represents data about key requests (archival, recov‐
1588 ery, key generation etc.) in the DRM.
1589 classmethod from_json(attr_list)
1591 Return a KeyRequestInfo object from a JSON dict.
1592 get_key_id()
1594 Return the ID of the secret referred to by this request.
1595 get_request_id()
1597 Return the request ID by parsing the request URL.
1598 json_attribute_names = {'keyURL': 'key_url', 'requestStatus':
1600 'request_status', 'requestType': 'request_type', 'requestURL':
1601 'request_url'}
1602 class pki.key.KeyRequestInfoCollection
1604 Bases: object
1605 This class represents the data returned when searching the key
1607 requests in the DRM. Essentially, its a list of KeyRequestInfo
1608 objects.
1609 classmethod from_json(json_value)
1611 Return a KeyRequestInfoCollection object from its JSON
1612 representation.
1613 class pki.key.KeyRequestResponse
1615 Bases: object
1616 This class is returned when an archival, recovery or key genera‐
1618 tion request is created. It includes a KeyRequestInfo object
1619 with information about the created request, and a KeyData struc‐
1620 ture which contains the wrapped secret (if that operation is
1621 supported).
1622 classmethod from_json(json_value)
1624 Return a KeyRequestResponse object from its JSON repre‐
1625 sentation.
1626 get_key_id()
1628 Return the id for the key archived, recovered or gener‐
1629 ated
1630 get_request_id()
1632 Return the id for the created request
1633 class pki.key.RequestId(req_id)
1635 Bases: object
1636 Class representing a Request ID
1638 class pki.key.SymKeyGenerationRequest(client_key_id=None,
1640 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1641 sion_key=None, realm=None)
1642 Bases: pki.ResourceMessage
1643 Class representing the data sent to the DRM when generating and
1645 archiving a symmetric key in the DRM.
1646 DECRYPT_USAGE = 'decrypt'
1648 ENCRYPT_USAGE = 'encrypt'
1650 SIGN_USAGE = 'sign'
1652 UNWRAP_USAGE = 'unwrap'
1654 VERIFY_USAGE = 'verify'
1656 WRAP_USAGE = 'wrap'
1658 pki.key.main()
1660 Some unit tests - basically printing different types of requests
1661 kra Module
1663 Module containing KRAClient class. This class should be used by Python
1664 clients to interact with the DRM to expose the functionality of the
1665 KeyClient and KeyRequestResource REST APIs.
1666 class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
1668 Bases: object
1669 Client class that models interactions with a KRA using the Key
1671 and KeyRequest REST APIs.
1672 profile Module
1674 class pki.profile.Descriptor(syntax=None, constraint=None, descrip‐
1675 tion=None, default_value=None)
1676 Bases: object
1677 This class represents the description of a ProfileAttribute. It
1679 stores information such as the syntax, constraint and default
1680 value of a profile attribute.
1681 classmethod from_json(attr_list)
1683 json_attribute_names = {'Constraint': 'constraint', 'Default‐
1685 Value': 'default_value', 'Description': 'description', 'Syntax':
1686 'syntax'}
1687 class pki.profile.PolicyConstraint(name=None, description=None,
1689 class_id=None, policy_constraint_values=None)
1690 Bases: object
1691 An object of this class contains the policy constraints applied
1693 to a ProfileInput used by a certificate enrollment request.
1694 add_constraint_value(policy_constraint_value)
1696 Add a PolicyConstraintValue to the policy_constraint_val‐
1697 ues list.
1698 classmethod from_json(attr_list)
1700 get_constraint_value(policy_constraint_value_name)
1702 Returns a PolicyConstraintValue object with the given
1703 name. None, if there is no match.
1704 json_attribute_names = {'classId': 'class_id', 'constraint':
1706 'policy_constraint_values', 'id': 'name'}
1707 remove_constraint_value(policy_constraint_value_name)
1709 Removes a PolicyConstraintValue with the given name form
1710 the policy_constraint_values list.
1711 class pki.profile.PolicyConstraintValue(name=None, value=None, descrip‐
1713 tor=None)
1714 Bases: object
1715 Represents a PolicyConstraintValue
1717 classmethod from_json(attr_list)
1719 property name
1721 class pki.profile.PolicyDefault(name=None, class_id=None, descrip‐
1723 tion=None, policy_attributes=None, policy_params=None)
1724 Bases: object
1725 An object of this class contains information of the default
1727 usage of a specific ProfileInput.
1728 add_attribute(policy_attribute)
1730 Add a policy attribute to the attribute list. @param
1731 policy_attribute - A ProfileAttribute object
1732 add_parameter(policy_parameter)
1734 Add a profile parameter to the parameters list. @param
1735 policy_parameter - A ProfileParameter object.
1736 classmethod from_json(attr_list)
1738 get_attribute(policy_attribute_name)
1740 Fetch the policy attribute with the given name from the
1741 attributes list.
1742 get_parameter(profile_parameter_name)
1744 Fetch a profile parameter with the given name from the
1745 parameters list.
1746 json_attribute_names = {'classId': 'class_id', 'id': 'name',
1748 'params': 'policy_params', 'policyAttribute': 'pol‐
1749 icy_attributes'}
1750 remove_attribute(policy_attribute_name)
1752 Remove a policy attribute with the given name from the
1753 attributes list.
1754 remove_parameter(profile_parameter_name)
1756 Remove a profile parameter with the given name from the
1757 parameters list.
1758 class pki.profile.PolicySet(name=None, policy_list=None)
1760 Bases: object
1761 An object of this class contains a name value pair of the policy
1763 name and the ProfilePolicy object.
1764 add_policy(profile_policy)
1766 Add a ProfilePolicy object to the policy_list
1767 classmethod from_json(attr_list)
1769 get_policy(policy_id)
1771 Returns a ProfilePolicy object with the given profile id.
1772 json_attribute_names = {'id': 'name', 'value': 'policy_list'}
1774 remove_policy(policy_id)
1776 Removes a ProfilePolicy with the given ID from the Poli‐
1777 cySet.
1778 class pki.profile.PolicySetList(policy_sets=None)
1780 Bases: object
1781 An object of this class stores a list of ProfileSet objects.
1783 add_policy_set(policy_set)
1785 Add a PolicySet object to the policy_sets list.
1786 classmethod from_json(attr_list)
1788 get_policy_set(policy_set_name)
1790 Fetch the PolicySet object for the given name. Returns
1791 None, if not found.
1792 property policy_sets
1794 remove_policy_set(policy_set_name)
1796 Remove a PolicySet object with the given name from the
1797 policy_sets list.
1798 class pki.profile.Profile(profile_id=None, class_id=None, name=None,
1800 description=None, enabled=None, visible=None, enabled_by=None, authen‐
1801 ticator_id=None, authorization_acl=None, renewal=None, xml_output=None,
1802 inputs=None, outputs=None, policy_set_list=None, link=None)
1803 Bases: object
1804 This class represents an enrollment profile.
1806 add_input(profile_input)
1808 Add a ProfileInput object to the inputs list of the Pro‐
1809 file.
1810 add_output(profile_output)
1812 Add a ProfileOutput object to the outputs list of the
1813 Profile.
1814 add_policy_set(policy_set)
1816 Add a PolicySet object to the policy_sets list of the
1817 Profile.
1818 classmethod from_json(attr_list)
1820 get_input(profile_input_id)
1822 Fetches a ProfileInput with the given ProfileInput id.
1823 Returns None, if there is no matching input.
1824 get_output(profile_output_id)
1826 Fetches a ProfileOutput with the given ProfileOutput id.
1827 Returns None, if there is no matching output.
1828 get_policy_set(policy_set_name)
1830 Fetches a ProfileInput with the given ProfileInput id.
1831 Returns None, if there is no matching input.
1832 static get_profile_data_from_file(path_to_file)
1834 Reads the file for the serialized Profile object. Cur‐
1835 rently supports only data format in json.
1836 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
1838 'PolicySets': 'policy_set_list', 'authenticatorId': 'authentica‐
1839 tor_id', 'authzAcl': 'authorization_acl', 'classId': 'class_id',
1840 'enabledBy': 'enabled_by', 'id': 'profile_id', 'xmlOutput':
1841 'xml_output'}
1842 remove_input(profile_input_id)
1844 Remove a ProfileInput from the inputs list of the Pro‐
1845 file.
1846 remove_output(profile_output_id)
1848 Remove a ProfileOutput from the outputs list of the Pro‐
1849 file.
1850 remove_policy_set(policy_set_name)
1852 Remove a PolicySet from the policy_sets list of the Pro‐
1853 file.
1854 class pki.profile.ProfileAttribute(name=None, value=None, descrip‐
1856 tor=None)
1857 Bases: object
1858 Represents a profile attribute of a ProfileInput.
1860 classmethod from_json(attr_list)
1862 json_attribute_names = {'Descriptor': 'descriptor', 'Value':
1864 'value'}
1865 class pki.profile.ProfileClient(connection)
1867 Bases: object
1868 This class consists of methods for accessing the ProfileRe‐
1870 source.
1871 create_profile(profile_data)
1873 Create a new profile for the given Profile object.
1874 create_profile_from_file(path_to_file)
1876 Reads the file for the serialized Profile object. Per‐
1877 forms the profile create operation. Currently supports
1878 only data format in json.
1879 delete_profile(profile_id)
1881 Delete a profile with the given Profile Id.
1882 disable_profile(profile_id)
1884 Disables a profile.
1885 enable_profile(profile_id)
1887 Enables a profile.
1888 get_profile(profile_id)
1890 Fetches information for the profile for the given profile
1891 id. Returns a ProfileData object.
1892 list_profiles(start=None, size=None)
1894 Fetches the list of profiles. The start and size argu‐
1895 ments provide pagination support. Returns a Profile‐
1896 DataInfoCollection object.
1897 modify_profile(profile_data)
1899 Modify an existing profile with the given Profile object.
1900 modify_profile_from_file(path_to_file)
1902 Reads the file for the serialized Profile object. Per‐
1903 forms the profile modify operation. Currently supports
1904 only data format in json.
1905 class pki.profile.ProfileDataInfo
1907 Bases: object
1908 Stores information about a profile
1910 classmethod from_json(attr_list)
1912 json_attribute_names = {'profileDescription': 'profile_descrip‐
1914 tion', 'profileId': 'profile_id', 'profileName': 'profile_name',
1915 'profileURL': 'profile_url'}
1916 class pki.profile.ProfileDataInfoCollection
1918 Bases: object
1919 Represents a collection of ProfileDataInfo objects. Also encap‐
1921 sulates the links for the list of the objects stored.
1922 classmethod from_json(attr_list)
1924 class pki.profile.ProfileInput(profile_input_id=None, class_id=None,
1926 name=None, text=None, attributes=None, config_attributes=None)
1927 Bases: object
1928 This class encapsulates all the attributes of a profile to gen‐
1930 erate a specific property of a certificate. Ex. Subject name,
1931 Requestor Information etc.
1932 add_attribute(profile_attribute)
1934 Add a ProfileAttribute object to the attributes list.
1935 add_config_attribute(profile_attribute)
1937 Add a ProfileAttribute object to the config_attributes
1938 list.
1939 classmethod from_json(attr_list)
1941 get_attribute(profile_attribute_name)
1943 Returns a ProfileAttribute object for the given name.
1944 None, if no match.
1945 get_config_attribute(config_attribute_name)
1947 Returns a ProfileAttribute object with the given name.
1948 None, if there is no match in the config_attributes list.
1949 json_attribute_names = {'Attribute': 'attributes', 'ClassID':
1951 'class_id', 'ConfigAttribute': 'config_attributes', 'Name':
1952 'name', 'Text': 'text', 'id': 'profile_input_id'}
1953 remove_attribute(profile_attribute_name)
1955 Remove a ProfileAttribute object with the given name from
1956 the attributes list.
1957 remove_config_attribute(config_attribute_name)
1959 Remove a ProfileAttribute object with the given name from
1960 the config_attributes list.
1961 class pki.profile.ProfileOutput(profile_output_id=None, name=None,
1963 text=None, class_id=None, attributes=None)
1964 Bases: object
1965 This class defines the output of a certificate enrollment
1967 request using a profile.
1968 add_attribute(profile_attribute)
1970 Add a ProfileAttribute object to the attributes list.
1971 classmethod from_json(attr_list)
1973 get_attribute(profile_attribute_name)
1975 Returns a ProfileAttribute object for the given name.
1976 None, if no match.
1977 json_attribute_names = {'classId': 'class_id', 'id': 'pro‐
1979 file_output_id'}
1980 remove_attribute(profile_attribute_name)
1982 Remove a ProfileAttribute object with the given name from
1983 the attributes list.
1984 class pki.profile.ProfileParameter(name=None, value=None)
1986 Bases: object
1987 classmethod from_json(attr_list)
1989 class pki.profile.ProfilePolicy(policy_id=None, policy_default=None,
1991 policy_constraint=None)
1992 Bases: object
1993 This class represents the policy a profile adheres to. An
1995 object of this class stores the default values for profile and
1996 the constraints present on the values of the attributes of the
1997 profile submitted for an enrollment request.
1998 classmethod from_json(attr_list)
2000 json_attribute_names = {'constraint': 'policy_constraint',
2002 'def': 'policy_default', 'id': 'policy_id'}
2003 class pki.profile.ProfilePolicySet
2005 Bases: object
2006 Stores a list of ProfilePolicy objects.
2008 classmethod from_json(attr_list)
2010 pki.profile.main()
2012 system Module
2014 class pki.system.AdminSetupRequest
2015 Bases: object
2016 class pki.system.AdminSetupResponse
2018 Bases: object
2019 class pki.system.CertificateSetupRequest
2021 Bases: object
2022 class pki.system.CertificateSetupResponse
2024 Bases: object
2025 class pki.system.DomainInfo
2027 Bases: object
2028 Class representing the entire security domain. This is essen‐
2030 tially a list of SecurityDomainSubsystem components.
2031 classmethod from_json(json_value)
2033 Create a DomainInfo object from JSON.
2034 Parameters
2036 json_value (str) -- JSON representation of a secu‐
2037 rity domain.
2038 Returns
2040 DomainInfo
2041 property systems
2043 class pki.system.FinalizeConfigRequest
2045 Bases: object
2046 class pki.system.InstallToken
2048 Bases: object
2049 classmethod from_json(json_value)
2051 class pki.system.SecurityDomainClient(connection)
2053 Bases: object
2054 Client used to get the security domain from a security domain
2056 CA. The connection details for the security domain CA are spec‐
2057 ified in a PKIConnection object used to construct this client.
2058 get_domain_info()
2060 Contact the security domain CA specified in the connec‐
2061 tion object used to construct this client and get the
2062 security domain using the REST API.
2063 Returns
2065 pki.system.DomainInfo
2066 get_install_token(hostname, subsystem)
2068 Returns
2070 pki.system.InstallToken
2071 get_old_domain_info()
2073 Contact the security domain CA specified in the connec‐
2074 tion object used to construct this client and get the
2075 security domain using the old servlet-based interface.
2076 This method is useful when contacting old servers which
2077 do not provide the REST API.
2078 Returns
2080 pki.system.DomainInfo
2081 get_security_domain_info()
2083 class pki.system.SecurityDomainHost
2085 Bases: object
2086 Class representing a security domain host.
2088 classmethod from_json(json_value)
2090 Constructs a SecurityDomainHost object from JSON.
2091 Parameters
2093 json_value (str) -- JSON string representing a
2094 security domain host.
2095 Returns
2097 SecurityDomainHost
2098 class pki.system.SecurityDomainSubsystem
2100 Bases: object
2101 Class representing a security domain subsystem. This is essen‐
2103 tially a list of SecurityDomainHost objects of a particular sub‐
2104 system type (ca, kra, tps, tks, ocsp).
2105 classmethod from_json(json_value)
2107 Constructs a SecurityDomainSubsystem from a JSON repre‐
2108 sentation.
2109 Parameters
2111 json_value (str) -- JSON representation of the
2112 Security Domain Subsystem
2113 Returns
2115 SecurityDomainSubsystem
2116 get_host(hostname, secure_port)
2118 class pki.system.SystemCertData
2120 Bases: object
2121 Class used to represent the data for a system certificate, which
2123 is used in the data passed into and returned from the Java
2124 installation servlet during the execution of pkispawn.
2125 This class is the python equivalent of the Java class: com.net‐
2127 scape.certsrv.system.SystemCertData
2128 class pki.system.SystemConfigClient(connection, subsystem=None)
2130 Bases: object
2131 Client used to interact with the Java configuration servlet to
2133 configure a Dogtag subsystem during the execution of pkispawn.
2134 The connection details for the system being configured are
2136 passed in the PKIConnection object used when constructing this
2137 object.
2138 finalizeConfiguration(request)
2140 Finalize server configuration.
2141 Parameters
2143 request (FinalizeConfigRequest) -- Finalize con‐
2144 figuration request
2145 setupAdmin(request)
2147 Set up admin.
2148 Parameters
2150 request (AdminSetupRequest) -- Admin setup request
2151 Returns
2153 AdminSetupResponse
2154 setupCert(request)
2156 Set up certificate.
2157 Parameters
2159 request (CertificateSetupRequest) -- Certificate
2160 setup request
2161 Returns
2163 SystemCertData
2164 class pki.system.SystemStatusClient(connection, subsystem=None)
2166 Bases: object
2167 Client used to check the status of a Dogtag subsystem.
2169 get_status(timeout=None)
2171 Checks the status of the subsystem by calling the getSta‐
2172 tus() servlet. This is used to determine if the server
2173 is up and ready to receive and process requests.
2174 Returns
2176 str - getStatus response
2177 systemcert Module
2179 Module containing the Python client classes for the SystemCert REST API
2180 class pki.systemcert.SystemCertClient(connection, subsystem=None)
2182 Bases: object
2183 Class encapsulating and mirroring the functionality in the Sys‐
2185 temCertResource Java interface class defining the REST API for
2186 system certificate resources.
2187 get_transport_cert()
2189 Return transport certificate.
2190 Returns
2192 pki.cert.CertData -- transport certificate data
2193 upgrade Module
2195 class pki.upgrade.PKIUpgradeScriptlet
2196 Bases: object
2197 backup(path)
2199 get_backup_dir()
2201 upgrade_system()
2203 class pki.upgrade.PKIUpgradeTracker(name, filename, delimiter='=', ver‐
2205 sion_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
2206 Bases: object
2207 get_index()
2209 get_version()
2211 remove()
2213 remove_index()
2215 remove_version()
2217 set(version)
2219 set_index(index)
2221 set_version(version)
2223 show()
2225 class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade')
2227 Bases: object
2228 all_versions()
2230 backup(scriptlet, path)
2232 copydirs(source, dest, force=False)
2234 copyfile(source, dest, force=False)
2236 get_current_version()
2238 get_target_version()
2240 get_tracker()
2242 init_scriptlet(scriptlet)
2244 is_complete()
2246 makedirs(path, exist_ok=False)
2248 record(scriptlet, path)
2250 remove_tracker()
2252 reset_tracker()
2254 revert()
2256 revert_scriptlet(scriptlet)
2258 revert_version(version)
2260 run_scriptlet(scriptlet)
2262 scriptlets(version)
2264 set_tracker(version)
2266 show_tracker()
2268 status()
2270 touch(path)
2272 update_tracker(scriptlet)
2274 upgrade()
2276 upgrade_version(version)
2278 validate()
2280 version_dir(version)
2282 versions()
2284 util Module
2286 Module containing utility functions and classes for the Dogtag python
2287 code
2288 class pki.util.Version(obj)
2290 Bases: object
2291 pki.util.chmod(path, mode)
2293 Change permissions of a file, link, or folder recursively.
2294 pki.util.chown(path, uid, gid)
2296 Change ownership of a file, link, or folder recursively.
2297 pki.util.copy(source, dest, uid=- 1, gid=- 1, dir_mode=None,
2299 file_mode=None, force=False)
2300 Copy a file or a folder and its contents.
2301 pki.util.copydirs(source, dest, uid=- 1, gid=- 1, mode=None,
2303 force=False)
2304 Copy a folder and its parents (without the contents) while pre‐
2305 serving their attributes.
2306 pki.util.copyfile(source, dest, slots=None, params=None, uid=None,
2308 gid=None, mode=None, force=False)
2309 Copy a file or link while preserving its attributes.
2310 pki.util.copytree(src, dst, symlinks=False, ignore=None)
2312 Recursively copy a directory tree using copy2().
2313 PATCH: This code was copied from 'shutil.py' and patched to
2315 allow 'The destination directory to already exist.'
2316 If exception(s) occur, an Error is raised with a list of rea‐
2318 sons.
2319 If the optional symlinks flag is true, symbolic links in the
2321 source tree result in symbolic links in the destination tree; if
2322 it is false, the contents of the files pointed to by symbolic
2323 links are copied.
2324 The optional ignore argument is a callable. If given, it is
2326 called with the src parameter, which is the directory being vis‐
2327 ited by copytree(), and names which is the list of src contents,
2328 as returned by os.listdir():
2329 callable(src, names) -> ignored_names
2330 Since copytree() is called recursively, the callable will be
2332 called once for each directory that is copied. It returns a list
2333 of names relative to the src directory that should not be
2334 copied.
2335 Consider this example code rather than the ultimate tool.
2337 pki.util.customize_file(input_file, output_file, params)
2339 Customize a file with specified parameters.
2340 pki.util.load_properties(filename, properties)
2342 pki.util.makedirs(path, mode=511, exist_ok=False, uid=- 1, gid=- 1,
2344 force=False)
2345 pki.util.read_environment_files(env_file_list=None)
2347 pki.util.read_text(message, options=None, default=None, delimiter=':',
2349 case_sensitive=True, password=False, required=False)
2350 Get an input from the user. This is used, for example, in
2351 pkispawn and pkidestroy to obtain user input.
2352 Parameters
2354 · message (str) -- prompt to display to the user
2356 · options (list) -- list of possible inputs by the user.
2358 · default (str) -- default value of parameter being
2360 prompted.
2361 · delimiter (str) -- delimiter to be used at the end of
2363 the prompt.
2364 · case_sensitive (boolean -- True/False) -- Allow input
2366 to be case sensitive.
2367 · password (boolean -- True/False) -- Input is a pass‐
2369 word. Don't show the value.
2370 · required (boolean -- True/False) -- Input must be
2372 non-empty.
2373 Returns
2375 str -- value obtained from user input.
2376 pki.util.remove(path, force=False)
2378 pki.util.replace_params(line, params=None)
2380 Replace all occurrences of [param] in the line with the value of
2381 the parameter.
2382 pki.util.rmtree(path, force=False)
2384 pki.util.set_property(properties, name, value)
2386 pki.util.store_properties(filename, properties)
2388 pki.util.symlink(source, dest, uid=- 1, gid=- 1, force=False)
2390 pki.util.unlink(link, force=False)
2392 · genindex
2394 · modindex
2396 · search
2398
2400 Dogtag PKI Project Team
2401
2403 2021, Dogtag PKI Team
2404@APPLICATION_VERSION@ Mar 12, 2021 PKI-PYTHON-CLIENT(1)