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/#cryptography.x509.Name
263 -
264 https://cryptography.io/en/latest/x509/reference/#cryptography.x509.NameAttribute
265 -
266 https://cryptography.io/en/latest/x509/reference/#cryptography.x509.ObjectIdentifier
267 Parameters
269 name (cryptography.x509.Name) -- X.509 Name
270 Returns
272 str -- DN string.
273 pki.generate_password()
275 This function generates FIPS-compliant password.
276 See sftk_newPinCheck() in the following file:
278 https://dxr.mozilla.org/nss/source/nss/lib/softoken/fipstokn.c
279 The minimum password length is FIPS_MIN_PIN Unicode characters.
281 The password must contain at least 3 character classes:
283 · digits (string.digits)
285 · ASCII lowercase letters (string.ascii_lowercase)
287 · ASCII uppercase letters (string.ascii_uppercase)
289 · ASCII non-alphanumeric characters (PUNCTUATIONS)
291 · non-ASCII characters
293 If an ASCII uppercase letter is the first character of the pass‐
295 word, the uppercase letter is not counted toward its character
296 class.
297 If a digit is the last character of the password, the digit is
299 not counted toward its character class.
300 The FIPS_MIN_PIN is defined in the following file:
302 https://dxr.mozilla.org/nss/source/nss/lib/softoken/pkcs11i.h
303 #define FIPS_MIN_PIN 7
305 pki.get_info(name)
307 pki.handle_exceptions()
309 Decorator handling exceptions from REST methods.
310 pki.implementation_version()
312 Return implementation version.
313 Returns
315 str -- implementation version
316 pki.specification_version()
318 Return specification version.
319 Returns
321 str -- specification version
322 account Module
324 class pki.account.AccountClient(connection, subsystem=None)
325 Bases: object
326 Class used to associate an authentication session variable with
328 a connection.
329 To use this class:
331 · set the authentication credentials with the connection,
333 · create an AccountClient and then call login().
335 · further operations in this session will use the same
337 authentication credentials without re-authentication.
338 · call logout() to invalidate the session.
340 login()
342 Login to account REST interface. If login is successful,
343 an authentication session variable is associated with the
344 connection.
345 Returns
347 None
348 logout()
350 Logs out of the session. Authentication session vari‐
351 ables are invalidated for the connection
352 Returns
354 None
355 cert Module
357 class pki.cert.CertClient(connection)
358 Bases: object
359 Class encapsulating and mirroring the functionality in the
361 CertResource Java interface class defining the REST API for Cer‐
362 tificate resources.
363 approve_request(request_id, cert_review_response=None)
365 Approves a certificate enrollment request. If
366 cert_review_response is None, a review request operation
367 is performed to fetch the CertReviewResponse object.
368 Requires as agent level authentication.
369 assign_request(request_id, cert_review_response)
371 Assigns a certificate enrollment request. If
372 cert_review_response is None, a review request operation
373 is performed to fetch the CertReviewResponse object.
374 Requires as agent level authentication.
375 cancel_request(request_id, cert_review_response=None)
377 Cancels a certificate enrollment request. If
378 cert_review_response is None, a review request operation
379 is performed to fetch the CertReviewResponse object.
380 Requires as agent level authentication.
381 create_enrollment_request(profile_id, inputs)
383 Fetches the enrollment request object for the given pro‐
384 file and sets values to its attributes using the values
385 provided in the inputs dictionary. Returns the CertEn‐
386 rollmentRequest object, which can be submitted to enroll
387 a certificate.
388 enroll_cert(profile_id, inputs, authority=None)
390 A convenience method for enrolling a certificate for a
391 given profile id. The inputs parameter should be a dic‐
392 tionary with values for the profile attributes for an
393 enrollment request.
394 Calling this method with valid arguments, creates an
396 enrollment request, submits it to the server, approves
397 the certificate requests generated for the enrollment and
398 returns a list of CertData objects for all the certifi‐
399 cates generated as part of this enrollment.
400 Note: This method supports only certificate enrollment
402 where only one agent approval is sufficient.
403 Requires an agent level authentication. Returns a list
405 of CertEnrollmentResult objects.
406 get_cert(cert_serial_number)
408 Return a CertData object for a particular certificate.
409 get_enrollment_template(profile_id)
411 Fetch the enrollment template for the given profile id.
412 For the first time, the request is sent to the server.
413 The retrieved CertEnrollmentRequest object is then cached
414 locally for future requests. Returns a CerEnrollmentRe‐
415 quest object.
416 get_request(request_id)
418 Get information of a certificate request with the given
419 request ID. Returns a CertRequestInfo object.
420 hold_cert(cert_serial_number, comments=None, authority=None)
422 Places a certificate on-hold. Calls the revoke_cert
423 method with reason - CertRevokeRequest.REASON_CERTIFI‐
424 CATE_HOLD. Returns a CertRequestInfo object. This
425 method requires an agent's authentication cert in the
426 connection object.
427 list_certs(max_results=None, max_time=None, start=None,
429 size=None, **cert_search_params)
430 Return a CertDataInfoCollection object with a information
431 about all the certificates that satisfy the search crite‐
432 ria. If cert_search_request=None, returns all the cer‐
433 tificates.
434 list_enrollment_templates(start=None, size=None)
436 Gets the list of profile templates supported by the CA.
437 The values for start and size arguments determine the
438 starting point and the length of the list. Returns a
439 ProfileDataInfoCollection object.
440 list_requests(request_status=None, request_type=None,
442 from_request_id=None, size=None, max_results=None,
443 max_time=None)
444 Query for a list of certificates using the arguments
445 passed. Returns a CertRequestInfoCollection object.
446 reject_request(request_id, cert_review_response=None)
448 Rejects a certificate enrollment request. If
449 cert_review_response is None, a review request operation
450 is performed to fetch the CertReviewResponse object.
451 Requires as agent level authentication.
452 review_cert(cert_serial_number)
454 Reviews a certificate. Returns a CertData object with a
455 nonce. This method requires an agent's authentication
456 cert in the connection object.
457 review_request(request_id)
459 Reviews a certificate enrollment request. Returns a
460 CertReviewResponse object which contains the nonce from
461 the server needed to perform an action on the request.
462 revoke_ca_cert(cert_serial_number, revocation_reason=None, inva‐
464 lidity_date=None, comments=None, nonce=None, authority=None)
465 Revokes a CA certificate. Returns a CertRequestInfo
466 object with information about the request. This method
467 requires an agent's authentication cert in the connection
468 object.
469 revoke_cert(cert_serial_number, revocation_reason=None, invalid‐
471 ity_date=None, comments=None, nonce=None, authority=None)
472 Revokes a certificate. Returns a CertRequestInfo object
473 with information about the request. This method requires
474 an agent's authentication cert in the connection object.
475 submit_enrollment_request(enrollment_request, authority=None)
477 Submits the CertEnrollmentRequest object to the server.
478 Returns a CertRequestInfoCollection object with informa‐
479 tion about the certificate requests enrolled at the CA.
480 unassign_request(request_id, cert_review_response)
482 Un-assigns a certificate enrollment request. If
483 cert_review_response is None, a review request operation
484 is performed to fetch the CertReviewResponse object.
485 Requires as agent level authentication.
486 unrevoke_cert(cert_serial_number, authority=None)
488 Un-revokes a revoked certificate. Returns a CertRe‐
489 questInfo object. This method requires an agent's
490 authentication cert in the connection object.
491 update_request(request_id, cert_review_response)
493 Updates a certificate enrollment request. If
494 cert_review_response is None, a review request operation
495 is performed to fetch the CertReviewResponse object.
496 Requires as agent level authentication.
497 validate_request(request_id, cert_review_response)
499 Validates a certificate enrollment request. If
500 cert_review_response is None, a review request operation
501 is performed to fetch the CertReviewResponse object.
502 Requires as agent level authentication.
503 class pki.cert.CertData
505 Bases: object
506 Class containing certificate data as returned from getCert()
508 classmethod from_json(attr_list)
510 Return CertData object from JSON dict
511 json_attribute_names = {'Encoded': 'encoded', 'IssuerDN':
513 'issuer_dn', 'Link': 'link', 'Nonce': 'nonce', 'NotAfter':
514 'not_after', 'NotBefore': 'not_before', 'PKCS7CertChain':
515 'pkcs7_cert_chain', 'PrettyPrint': 'pretty_repr', 'Status':
516 'status', 'SubjectDN': 'subject_dn', 'id': 'serial_number'}
517 class pki.cert.CertDataInfo
519 Bases: object
520 Class containing information contained in a CertRecord on the
522 CA. This data is returned when searching/listing certificate
523 records.
524 classmethod from_json(attr_list)
526 Return CertDataInfo object from JSON dict
527 json_attribute_names = {'IssuedBy': 'issued_by', 'IssuedOn':
529 'issued_on', 'KeyAlgorithmOID': 'key_algorithm_oid',
530 'KeyLength': 'key_length', 'Link': 'link', 'NotValidAfter':
531 'not_valid_after', 'NotValidBefore': 'not_valid_before', 'Sta‐
532 tus': 'status', 'SubjectDN': 'subject_dn', 'Type': 'type', 'Ver‐
533 sion': 'version', 'id': 'serial_number'}
534 class pki.cert.CertDataInfoCollection
536 Bases: object
537 Class containing list of CertDataInfo objects and their respec‐
539 tive link objects. This data is returned when searching/listing
540 certificate records in the CA.
541 classmethod from_json(json_value)
543 Populate object from JSON input
544 class pki.cert.CertEnrollmentRequest(profile_id=None, renewal=False,
546 serial_number=None, remote_host=None, remote_address=None, inputs=None,
547 outputs=None)
548 Bases: object
549 This class encapsulates the parameters required for a certifi‐
551 cate
552 enrollment request.
553 add_input(profile_input)
555 add_output(profile_output)
557 classmethod from_json(attr_list)
559 get_input(profile_input_name)
561 get_output(profile_output_name)
563 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
565 'ProfileID': 'profile_id', 'RemoteAddress': 'remote_address',
566 'RemoteHost': 'remote_host', 'Renewal': 'renewal', 'SerialNum‐
567 ber': 'serial_number'}
568 remove_input(profile_input_name)
570 remove_output(profile_output_name)
572 class pki.cert.CertEnrollmentResult(request, cert)
574 Bases: object
575 Class containing results of an enrollment request.
577 This structure contains information about the cert request gen‐
579 erated and any certificates issued.
580 class pki.cert.CertRequestInfo
582 Bases: object
583 An object of this class stores represents a certificate request.
585 classmethod from_json(attr_list)
587 json_attribute_names = {'certId': 'cert_id', 'certRequestType':
589 'cert_request_type', 'certURL': 'cert_url', 'errorMessage':
590 'error_message', 'operationResult': 'operation_result',
591 'requestStatus': 'request_status', 'requestType':
592 'request_type', 'requestURL': 'request_url'}
593 class pki.cert.CertRequestInfoCollection
595 Bases: object
596 Class containing list of CertRequestInfo objects. This data is
598 returned when listing certificate request records in the CA.
599 classmethod from_json(json_value)
601 Populate object from JSON input
602 class pki.cert.CertRequestStatus
604 Bases: object
605 Class containing valid cert statuses.
607 CANCELED = 'canceled'
609 COMPLETE = 'complete'
611 PENDING = 'pending'
613 REJECTED = 'rejected'
615 class pki.cert.CertReviewResponse(profile_id=None, renewal=False,
617 serial_number=None, remote_host=None, remote_address=None, inputs=None,
618 outputs=None, nonce=None, request_id=None, request_type=None,
619 request_status=None, request_owner=None, request_creation_time=None,
620 request_modification_time=None, request_notes=None, pro‐
621 file_approval_by=None, profile_set_id=None, profile_is_visible=None,
622 profile_name=None, profile_description=None, profile_remote_host=None,
623 profile_remote_address=None, policy_sets=None)
624 Bases: pki.cert.CertEnrollmentRequest
625 An object of this class represent the response from the server
627 when reviewing a certificate enrollment request. It contains a
628 nonce required to perform action on the request.
629 classmethod from_json(attr_list)
631 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
633 'ProfileID': 'profile_id', 'ProfilePolicySet': 'policy_sets',
634 'RemoteAddress': 'remote_address', 'RemoteHost': 'remote_host',
635 'Renewal': 'renewal', 'SerialNumber': 'serial_number', 'pro‐
636 fileApprovedBy': 'profile_approved_by', 'profileDescription':
637 'profile_description', 'profileIsVisible': 'profile_is_visible',
638 'profileName': 'profile_name', 'profileRemoteAddr': 'pro‐
639 file_remote_address', 'profileRemoteHost': 'pro‐
640 file_remote_host', 'profileSetId': 'profile_set_id',
641 'requestCreationTime': 'request_creation_time', 'requestId':
642 'request_id', 'requestModificationTime': 'request_modifica‐
643 tion_time', 'requestNotes': 'request_notes', 'requestOwner':
644 'request_owner', 'requestStatus': 'request_status', 'request‐
645 Type': 'request_type'}
646 class pki.cert.CertRevokeRequest(nonce, reason=None, invalid‐
648 ity_date=None, comments=None)
649 Bases: object
650 An object of this class encapsulates all the parameters required
652 for revoking a certificate.
653 Valid values for reasons for revoking a request are:
655 'Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affil‐
656 iation_Changed', 'Superseded', 'Cessation_of_Operation',
657 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_With‐
658 drawn', 'AA_Compromise'
659 reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise',
661 'Affiliation_Changed', 'Superseded', 'Cessation_of_Operation',
662 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_Withdrawn',
663 'AA_Compromise']
664 class pki.cert.CertSearchRequest(**cert_search_params)
666 Bases: object
667 An object of this class is used to store the search parameters
669 and send them to server.
670 search_params = {'cert_type_secure_email': 'certTypeSe‐
672 cureEmail', 'cert_type_ssl_client': 'certTypeSSLClient',
673 'cert_type_ssl_server': 'certTypeSSLServer',
674 'cert_type_sub_email_ca': 'certTypeSubEmailCA',
675 'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'common_name': 'com‐
676 monName', 'country': 'country', 'email': 'eMail', 'issued_by':
677 'issuedBy', 'issued_on_from': 'issuedOnFrom', 'issued_on_to':
678 'issuedOnTo', 'locality': 'locality', 'match_exactly': 'matchEx‐
679 actly', 'org': 'org', 'org_unit': 'orgUnit', 'revocation_rea‐
680 son': 'revocationReason', 'revoked_by': 'revokedBy',
681 'revoked_on_from': 'revokedOnFrom', 'revoked_on_to': 'revoke‐
682 dOnTo', 'serial_from': 'serialFrom', 'serial_to': 'serialTo',
683 'state': 'state', 'status': 'status', 'user_id': 'userID',
684 'valid_not_after_from': 'validNotAfterFrom',
685 'valid_not_after_to': 'validNotAfterTo',
686 'valid_not_before_from': 'validNotBeforeFrom',
687 'valid_not_before_to': 'validNotBeforeTo', 'validity_count':
688 'validityCount', 'validity_operation': 'validityOperation',
689 'validity_unit': 'validityUnit'}
690 pki.cert.main()
692 client Module
694 class pki.client.PKIConnection(protocol='http', hostname='localhost',
695 port='8080', subsystem=None, accept='application/json', trust_env=None,
696 verify=False)
697 Bases: object
698 Class to encapsulate the connection between the client and a
700 Dogtag subsystem.
701 authenticate(username=None, password=None)
703 Set the parameters used for authentication if user‐
704 name/password is to be used. Both username and password
705 must not be None. Note that this method only sets the
706 parameters. Actual authentication occurs when the con‐
707 nection is attempted,
708 Parameters
710 · username -- username to authenticate connection
712 · password -- password to authenticate connection
714 Returns
716 None
717 delete(path, headers=None, use_root_uri=False)
719 Uses python-requests to issue a DEL request to the
720 server.
721 Parameters
723 · path (str) -- path URI for the DEL request
725 · headers (dict) -- headers for the DEL request
727 · use_root_uri (boolean) -- use root URI instead
729 of subsystem URI as base
730 Returns
732 request.response -- response from the server
733 Raises Exception from python-requests in case the DEL was
735 not successful, or returns an error code.
736 get(path, headers=None, params=None, payload=None,
738 use_root_uri=False, timeout=None)
739 Uses python-requests to issue a GET request to the
740 server.
741 Parameters
743 · path (str) -- path URI for the GET request
745 · headers (dict) -- headers for the GET request
747 · params (dict or bytes) -- Query parameters for
749 the GET request
750 · payload (dict, bytes, file-like object) -- data
752 to be sent in the body of the request
753 · use_root_uri (boolean) -- use root URI instead
755 of subsystem URI as base
756 Returns
758 request.response -- response from the server
759 Raises Exception from python-requests in case the GET was
761 not successful, or returns an error code.
762 post(path, payload, headers=None, params=None,
764 use_root_uri=False)
765 Uses python-requests to issue a POST request to the
766 server.
767 Parameters
769 · path (str) -- path URI for the POST request
771 · payload (dict, bytes, file-like object) -- data
773 to be sent in the body of the request
774 · headers (dict) -- headers for the POST request
776 · params (dict or bytes) -- Query parameters for
778 the POST request
779 · use_root_uri (boolean) -- use root URI instead
781 of subsystem URI as base
782 Returns
784 request.response -- response from the server
785 Raises Exception from python-requests in case the POST
787 was not successful, or returns an error code.
788 put(path, payload, headers=None, use_root_uri=False)
790 Uses python-requests to issue a PUT request to the
791 server.
792 Parameters
794 · path (str) -- path URI for the PUT request
796 · payload (dict, bytes, file-like object) -- data
798 to be sent in the body of the request
799 · headers (dict) -- headers for the PUT request
801 · use_root_uri (boolean) -- use root URI instead
803 of subsystem URI as base
804 Returns
806 request.response -- response from the server
807 Raises Exception from python-requests in case the PUT was
809 not successful, or returns an error code.
810 set_authentication_cert(pem_cert_path, pem_key_path=None)
812 Set the path to the PEM file containing the certificate
813 and private key for the client certificate to be used for
814 authentication to the server, when client certificate
815 authentication is required. The private key may option‐
816 ally be stored in a different path.
817 Parameters
819 · pem_cert_path (str) -- path to the PEM file
821 · pem_key_path (str) -- path to the PEM-formatted
823 private key file
824 Returns
826 None
827 Raises Exception if path is empty or None.
829 pki.client.catch_insecure_warning(func)
831 Temporary silence InsecureRequestWarning
832 PKIConnection is not able to verify HTTPS connections yet. This
834 decorator catches the warning.
835 See https://fedorahosted.org/pki/ticket/1253
837 pki.client.main()
839 Test code for the PKIConnection class. :return: None
840 crypto Module
842 Module containing crypto classes.
843 class pki.crypto.CryptoProvider
845 Bases: object
846 Abstract class containing methods to do cryptographic opera‐
848 tions.
849 abstract asymmetric_wrap(data, wrapping_cert, mechanism=None)
851 encrypt a symmetric key with the public key of a trans‐
852 port cert.
853 The mechanism is the type of symmetric key, which
855 defaults to a 56 bit DES3 key.
856 abstract generate_nonce_iv(mechanism)
858 Create a random initialization vector
859 abstract generate_session_key()
861 Generate a session key to be used for wrapping data to
862 the DRM This must return a 3DES 168 bit key
863 abstract generate_symmetric_key(mechanism=None, size=0)
865 Generate and return a symmetric key
866 abstract get_cert(cert_nick)
868 Get the certificate for the specified cert_nick.
869 abstract get_supported_algorithm_keyset()
871 returns highest supported algorithm keyset
872 abstract initialize()
874 Initialization code
875 abstract key_unwrap(mechanism, data, wrapping_key, nonce_iv)
877 Unwrap data that has been key wrapped using AES KeyWrap
878 abstract set_algorithm_keyset(level)
880 sets required keyset
881 abstract symmetric_unwrap(data, wrapping_key, mechanism=None,
883 nonce_iv=None)
884 decrypt data originally encrypted with symmetric key
885 (wrapping key)
886 We expect the data and nonce_iv values to be base64
888 encoded. The mechanism is the type of key used to do the
889 wrapping. It defaults to a 56 bit DES3 key.
890 abstract symmetric_wrap(data, wrapping_key, mechanism=None,
892 nonce_iv=None)
893 encrypt data using a symmetric key (wrapping key)
894 class pki.crypto.CryptographyCryptoProvider(transport_cert_nick, trans‐
896 port_cert, backend=<cryptography.hazmat.backends.openssl.backend.Back‐
897 end object>)
898 Bases: pki.crypto.CryptoProvider
899 Class that defines python-cryptography implementation of Crypto‐
901 Provider. Requires a PEM file containing the agent cert to be
902 initialized.
903 Note that all inputs and outputs are unencoded.
905 asymmetric_wrap(data, wrapping_cert, mechanism=None)
907 :param data Data to be wrapped :param wrap‐
908 ping_cert Public key to wrap data :param mechanism
909 algorithm of symmetric key to be wrapped
910 Wrap (encrypt) data using the supplied asymmetric key
912 generate_nonce_iv(mechanism='AES')
914 Create a random initialization vector
915 generate_session_key()
917 Returns a session key to be used when wrapping secrets
918 for the DRM.
919 generate_symmetric_key(mechanism=None, size=0)
921 Returns a symmetric key.
922 get_cert(cert_nick)
924 :param cert_nick Nickname for the certificate to be
925 returned.
926 get_supported_algorithm_keyset()
928 returns highest supported algorithm keyset
929 initialize()
931 Any operations here that need to be performed before
932 crypto operations.
933 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
935 :param mechanism key wrapping mechanism :param
936 data: data to unwrap :param wrapping_key:
937 AES key used to wrap data :param nonce_iv Nonce
938 data :return: unwrapped data
939 Unwrap the encrypted data which has been wrapped using a
941 KeyWrap mechanism.
942 set_algorithm_keyset(level)
944 sets required keyset
945 symmetric_unwrap(data, wrapping_key, mechanism=None,
947 nonce_iv=None)
948 :param data Data to be unwrapped :param wrap‐
949 ping_key Symmetric key to unwrap data :param mechanism
950 Mechanism to use when unwrapping :param nonce_iv
951 iv data
952 Unwrap (decrypt) data using the supplied symmetric key
954 symmetric_wrap(data, wrapping_key, mechanism=None,
956 nonce_iv=None)
957 :param data Data to be wrapped :param wrap‐
958 ping_key Symmetric key to wrap data :param mechanism
959 Mechanism to use for wrapping key :param nonce_iv
960 Nonce for initialization vector
961 Wrap (encrypt) data using the supplied symmetric key
963 class pki.crypto.NSSCryptoProvider(certdb_dir, certdb_password=None,
965 password_file=None)
966 Bases: pki.crypto.CryptoProvider
967 Class that defines NSS implementation of CryptoProvider.
969 Requires an NSS database to have been set up and initialized.
970 Note that all inputs and outputs are unencoded.
972 asymmetric_wrap(data, wrapping_cert, mechanism=310)
974 :param data Data to be wrapped :param wrap‐
975 ping_cert Public key to wrap data :param mechanism
976 algorithm of symmetric key to be wrapped
977 Wrap (encrypt) data using the supplied asymmetric key
979 generate_nonce_iv(mechanism=310)
981 Create a random initialization vector
982 generate_session_key()
984 Returns a session key to be used when wrapping secrets
985 for the DRM This will return a 168 bit 3DES key.
986 generate_symmetric_key(mechanism=310, size=0)
988 Returns a symmetric key.
989 Note that for fixed length keys, this length should be 0.
991 If no length is provided, then the function will either
992 use 0 (for fixed length keys) or the maximum available
993 length for that algorithm and the token.
994 get_cert(cert_nick)
996 :param cert_nick Nickname for the certificate to be
997 returned
998 Searches NSS database and returns SecItem object for this
1000 certificate.
1001 get_supported_algorithm_keyset()
1003 returns highest supported algorithm keyset
1004 import_cert(cert_nick, cert, trust=', ')
1006 Import a certificate into the nss database
1007 initialize()
1009 Initialize the nss db. Must be done before any crypto
1010 operations
1011 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
1013 :param mechanism Key wrapping mechanism :param
1014 data: Data to be unwrapped :param wrap‐
1015 ping_key: Wrapping Key :param nonce_iv Nonce
1016 data :return: Unwrapped data
1017 Return unwrapped data for data that has been keywrapped.
1019 For NSS, we only support 3DES - so something that has
1020 been keywrapped can be decrypted. This is precisely what
1021 we used to do before.
1022 set_algorithm_keyset(level)
1024 sets required keyset
1025 classmethod setup_contexts(mechanism, sym_key, nonce_iv)
1027 Set up contexts to do wrapping/unwrapping by symmetric
1028 keys.
1029 static setup_database(db_dir, password=None, over_write=False,
1031 password_file=None)
1032 Create an NSS database
1033 symmetric_unwrap(data, wrapping_key, mechanism=310,
1035 nonce_iv=None)
1036 :param data Data to be unwrapped :param wrap‐
1037 ping_key Symmetric key to unwrap data :param mechanism
1038 Mechanism to use when wrapping :param nonce_iv iv
1039 data
1040 Unwrap (decrypt) data using the supplied symmetric key
1042 symmetric_wrap(data, wrapping_key, mechanism=310, nonce_iv=None)
1044 :param data Data to be wrapped :param wrap‐
1045 ping_key Symmetric key to wrap data :param mechanism
1046 Mechanism to user when wrapping :param nonce_iv
1047 Nonce to use when wrapping
1048 Wrap (encrypt) data using the supplied symmetric key
1050 encoder Module
1052 pki.encoder.CustomTypeDecoder(dct)
1053 class pki.encoder.CustomTypeEncoder(*, skipkeys=False,
1055 ensure_ascii=True, check_circular=True, allow_nan=True,
1056 sort_keys=False, indent=None, separators=None, default=None)
1057 Bases: json.encoder.JSONEncoder
1058 A custom JSONEncoder class that knows how to encode core custom
1060 objects.
1061 Custom objects are encoded as JSON object literals (ie, dicts)
1063 with one key, 'TypeName' where 'TypeName' is the actual name of
1064 the type to which the object belongs. That single key maps to
1065 another object literal which is just the __dict__ of the object
1066 encoded.
1067 Reason for ignoring the error: E0202 - An attribute affected in
1069 json.encoder line 157 hide this method reported by pylint:
1070 The error is in json.encoder.JSONEncoder class. There is a
1072 default method (which is overridden here) and also a class
1073 attribute self.default initialized in the init method of the
1074 class. The intention of such usage being that a custom default
1075 method object can be passed to init when creating an instance of
1076 JSONEncoder, which is then assigned to class's default method.
1077 (which is valid) But pylint raises an issue due to the usage of
1078 same name for a method and an attribute in which case the
1079 attribute definition hides the method. The reason and example
1080 for the issue: (top rated comment)
1081 http://stackoverflow.com/questions/12949064/python-what-happens-
1082 when-instance-variable-name-is-same-as-method-name
1083 static attr_name_conversion(attr_dict, object_class)
1085 default(o)
1087 Implement this method in a subclass such that it returns
1088 a serializable object for o, or calls the base implemen‐
1089 tation (to raise a TypeError).
1090 For example, to support arbitrary iterators, you could
1092 implement default like this:
1093 def default(self, o):
1095 try:
1096 iterable = iter(o)
1097 except TypeError:
1098 pass
1099 else:
1100 return list(iterable)
1101 # Let the base class default method raise the TypeError
1102 return JSONEncoder.default(self, o)
1103 pki.encoder.decode_cert(data)
1105 base64 decode X.509 certificate
1106 Parameters
1108 data (str, bytes) -- data as bytes or ASCII text
1109 Return type
1111 bytes
1112 pki.encoder.encode_cert(data)
1114 base64 encode X.509 certificate
1115 Python 3's base64.b64encode() doesn't support ASCII text.
1117 Parameters
1119 data (str, bytes) -- data as bytes or ASCII text
1120 Return type
1122 bytes
1123 key Module
1125 Module containing the Python client classes for the KeyClient and
1126 KeyRequestClient REST API on a DRM
1127 class pki.key.AsymKeyGenerationRequest(client_key_id=None,
1129 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1130 sion_key=None, realm=None)
1131 Bases: pki.ResourceMessage
1132 Class representing the data sent to the DRM when generating and
1134 archiving asymmetric keys in the DRM.
1135 DECRYPT_USAGE = 'decrypt'
1137 DERIVE_USAGE = 'derive'
1139 ENCRYPT_USAGE = 'encrypt'
1141 SIGN_RECOVER_USAGE = 'sign_recover'
1143 SIGN_USAGE = 'sign'
1145 UNWRAP_USAGE = 'unwrap'
1147 VERIFY_RECOVER_USAGE = 'verify_recover'
1149 VERIFY_USAGE = 'verify'
1151 WRAP_USAGE = 'wrap'
1153 class pki.key.Key(key_data)
1155 Bases: object
1156 An instance of this class stores the decoded encrypted secret
1158 present in the KeyData object passed in the constructor. All
1159 the key retrieval requests return this object.
1160 class pki.key.KeyArchivalRequest(client_key_id=None, data_type=None,
1162 wrapped_private_data=None, trans_wrapped_session_key=None, pki_ar‐
1163 chive_options=None, algorithm_oid=None, symkey_params=None, key_algo‐
1164 rithm=None, key_size=None, realm=None)
1165 Bases: pki.ResourceMessage
1166 Class representing the object sent to the DRM when archiving a
1168 secret.
1169 class pki.key.KeyClient(connection, crypto, transport_cert_nick=None,
1171 info_client=None)
1172 Bases: object
1173 Class that encapsulates and mirrors the functions in the KeyRe‐
1175 source and KeyRequestResource Java classes in the DRM REST API.
1176 AES_ALGORITHM = 'AES'
1178 ASYMMETRIC_KEY_TYPE = 'asymmetricKey'
1180 DES3_ALGORITHM = 'DES3'
1182 DESEDE_ALGORITHM = 'DESede'
1184 DES_ALGORITHM = 'DES'
1186 DSA_ALGORITHM = 'DSA'
1188 KEY_STATUS_ACTIVE = 'active'
1190 KEY_STATUS_INACTIVE = 'inactive'
1192 PASS_PHRASE_TYPE = 'passPhrase'
1194 RC2_ALGORITHM = 'RC2'
1196 RC4_ALGORITHM = 'RC4'
1198 RSA_ALGORITHM = 'RSA'
1200 SYMMETRIC_KEY_TYPE = 'symmetricKey'
1202 approve_request(request_id)
1204 Approve a secret recovery request
1205 archive_encrypted_data(client_key_id, data_type, encrypted_data,
1207 wrapped_session_key, algorithm_oid=None, nonce_iv=None,
1208 key_algorithm=None, key_size=None, realm=None)
1209 Archive a secret (symmetric key or passphrase) on the
1210 DRM.
1211 Refer to archive_key() comments for a description of
1213 client_key_id, data_type, key_algorithm and key_size.
1214 The following parameters are also required:
1216 · encrypted_data - which is the data encrypted by
1218 a session key (168 bit 3DES symmetric key)
1219 · wrapped_session_key - the above session key
1221 wrapped by the DRM transport certificate public
1222 key.
1223 · the algorithm_oid string for the symmetric key
1225 wrap
1226 · the nonce_iv for the symmetric key wrap
1228 This function is useful if the caller wants to do their
1230 own wrapping of the secret, or if the secret was gener‐
1231 ated on a separate client machine and the wrapping was
1232 done there.
1233 The function returns a KeyRequestResponse object contain‐
1235 ing a KeyRequestInfo object with details about the
1236 archival request and key archived.
1237 archive_key(client_key_id, data_type, private_data, key_algo‐
1239 rithm=None, key_size=None, realm=None)
1240 Archive a secret (symmetric key or passphrase) on the
1241 DRM.
1242 Requires a user-supplied client ID. There can be only
1244 one active key with a specified client ID. If a record
1245 for a duplicate active key exists, a BadRequestException
1246 is thrown.
1247 data_type can be one of the following:
1249 KeyClient.SYMMETRIC_KEY_TYPE, KeyClient.ASYMMET‐
1250 RIC_KEY_TYPE, KeyClient.PASS_PHRASE_TYPE
1251 key_algorithm and key_size are applicable to symmetric
1253 keys only. If a symmetric key is being archived, these
1254 parameters are required.
1255 private_data is the raw secret to be archived. It will
1257 be wrapped and sent to the DRM.
1258 The function returns a KeyRequestResponse object contain‐
1260 ing a KeyRequestInfo object with details about the
1261 archival request and key archived.
1262 archive_pki_options(client_key_id, data_type, pki_ar‐
1264 chive_options, key_algorithm=None, key_size=None, realm=None)
1265 Archive a secret (symmetric key or passphrase) on the
1266 DRM.
1267 Refer to archive_key() comments for a description of
1269 client_key_id, data_type, key_algorithm and key_size.
1270 pki_archive_options is the data to be archived wrapped in
1272 a PKIArchiveOptions structure,
1273 The function returns a KeyRequestResponse object contain‐
1275 ing a KeyRequestInfo object with details about the
1276 archival request and key archived.
1277 cancel_request(request_id)
1279 Cancel a secret recovery request
1280 generate_asymmetric_key(client_key_id, algorithm=None,
1282 key_size=None, usages=None, trans_wrapped_session_key=None,
1283 realm=None)
1284 Generate and archive asymmetric keys in the DRM. Sup‐
1285 ports algorithms RSA and DSA. Valid key size for RSA =
1286 256 + (16 * n), where n: 0-496 Valid key size for DSA =
1287 512, 768, 1024. p,q,g params are not supported.
1288 Return a KeyRequestResponse which contains a KeyRe‐
1290 questInfo object that describes the URL for the request
1291 and generated keys.
1292 generate_symmetric_key(client_key_id, algorithm=None, size=None,
1294 usages=None, trans_wrapped_session_key=None, realm=None)
1295 Generate and archive a symmetric key on the DRM.
1296 Return a KeyRequestResponse which contains a KeyRe‐
1298 questInfo object that describes the URL for the request
1299 and generated key.
1300 get_active_key_info(client_key_id)
1302 Get the info in the KeyRecord for the active secret in
1303 the DRM.
1304 get_client_keyset()
1306 get_key_info(key_id)
1308 Get the info in the KeyRecord for a specific secret in
1309 the DRM.
1310 get_request_info(request_id)
1312 Return a KeyRequestInfo object for a specific request.
1313 get_server_keyset()
1315 list_keys(client_key_id=None, status=None, max_results=None,
1317 max_time=None, start=None, size=None, realm=None)
1318 List/Search archived secrets in the DRM.
1319 See KRAClient.list_keys for the valid values of status.
1321 Returns a KeyInfoCollection object.
1322 list_requests(request_state=None, request_type=None,
1324 client_key_id=None, start=None, page_size=None,
1325 max_results=None, max_time=None, realm=None)
1326 List/Search key requests in the DRM.
1327 See KRAClient.list_requests for the valid values of
1329 request_state and request_type. Returns a KeyRequestIn‐
1330 foCollection object.
1331 modify_key_status(key_id, status)
1333 Modify the status of a key
1334 process_returned_key(key, session_key)
1336 Decrypt the returned key and place in key.data
1337 The data will either by encrypted using an encryption
1339 algorithm - in which case, the key data will contain an
1340 encryption algorithm OID, or it will be key wrapped - in
1341 which case, the key data will contain a key wrap mecha‐
1342 nism name.
1343 Only one of these should be present. If we are talking
1345 to an older server, and none is present, we will assume
1346 encryption.
1347 recover_key(key_id, request_id=None, ses‐
1349 sion_wrapped_passphrase=None, trans_wrapped_session_key=None,
1350 b64certificate=None, nonce_data=None)
1351 Create a request to recover a secret.
1352 To retrieve a symmetric key or passphrase, the only
1354 parameter that is required is the keyId. It is possible
1355 (but not required) to pass in the session keys/passphrase
1356 and nonceData for the retrieval at this time. Those
1357 parameters are documented in the docstring for
1358 retrieve_key below.
1359 To retrieve an asymmetric key, the keyId and the the
1361 base-64 encoded certificate is required.
1362 reject_request(request_id)
1364 Reject a secret recovery request.
1365 retrieve_key(key_id=None, trans_wrapped_session_key=None,
1367 request_id=None)
1368 Retrieve a secret (passphrase or symmetric key) from the
1369 DRM.
1370 This method will retrieve a key from the KRA given the
1372 key_id or request_id (one of which must be specified).
1373 The data is returned as a KeyData object (which is recast
1374 to a Key object).
1375 If request_id is specified, then the value of key_id is
1377 ignored. Exceptions will be thrown if the caller is not
1378 the originator of the request, or the request is not
1379 approved.
1380 If key_id is specified instead, the following behavior
1382 applies:
1383 · If the key can be retrieved synchronously - ie. only
1385 one agent's approval is required, then the KeyData will
1386 include the secret.
1387 · If the key cannot be retrieved synchronously - ie. if
1389 more than one approval is needed, then the KeyData
1390 object will include the request ID for a recovery
1391 request that was created on the server. When that
1392 request is approved, callers can retrieve the key using
1393 retrieve_key() and setting the request_id.
1394 To ensure data security in transit, the data will be
1396 returned encrypted by a session key (168 bit 3DES symmet‐
1397 ric key) - which is first wrapped (encrypted) by the pub‐
1398 lic key of the DRM transport certificate before being
1399 sent to the DRM. The parameter trans_wrapped_session_key
1400 refers to this wrapped session key.
1401 If the trans_wrapped_session_key is not provided by call‐
1403 er, the method will call CryptoProvider methods to gener‐
1404 ate and wrap the session key. The function will return
1405 the KeyData object with a private_data attribute which
1406 stores the unwrapped key information.
1407 If the trans_wrapped_session_key is provided by the call‐
1409 er, the method will simply pass the data to the KRA, and
1410 will return the secret wrapped in the session key. The
1411 secret will still need to be unwrapped by the caller.
1412 The function will return the KeyData object, where the
1413 KeyData structure includes the wrapped secret and some
1414 nonce data to be used as a salt when unwrapping.
1415 retrieve_key_by_passphrase(key_id=None, request_id=None,
1417 passphrase=None, trans_wrapped_session_key=None, ses‐
1418 sion_wrapped_passphrase=None, nonce_data=None)
1419 Retrieve a secret (passphrase or symmetric key) from the
1420 DRM using a passphrase.
1421 This function generates a key recovery request, approves
1423 it, and retrieves the secret referred to by key_id. This
1424 assumes that only one approval is required to authorize
1425 the recovery.
1426 The secret is secured in transit by wrapping the secret
1428 with a passphrase using PBE encryption.
1429 There are two ways of using this function:
1431 1. A passphrase is provided by the caller.
1433 In this case, CryptoProvider methods will be called to
1435 create the data to securely send the passphrase to the
1436 DRM. Basically, three pieces of data will be sent:
1437 · the passphrase wrapped by a 168 bit 3DES symmetric
1439 key (the session key). This is referred to as the
1440 parameter session_wrapped_passphrase.
1441 · the session key wrapped with the public key in the
1443 DRM transport certificate. This is referred to as
1444 the trans_wrapped_session_key.
1445 · ivps nonce data, referred to as nonce_data
1447 The function will return the tuple (KeyData,
1449 unwrapped_secret)
1450 2. The caller provides the trans_wrapped_session_key,
1452 session_wrapped_passphrase and nonce_data.
1453 In this case, the data will simply be passed to the
1455 DRM. The function will return the secret encrypted by
1456 the passphrase using PBE Encryption. The secret will
1457 still need to be decrypted by the caller.
1458 The function will return the tuple (KeyData, None)
1460 retrieve_key_by_pkcs12(key_id, certificate, passphrase)
1462 Retrieve an asymmetric private key and return it as
1463 PKCS12 data.
1464 This function generates a key recovery request, approves
1466 it, and retrieves the secret referred to by key_id in a
1467 PKCS12 file. This assumes that only one approval is
1468 required to authorize the recovery.
1469 This function requires the following parameters: - key_id
1471 : the ID of the key - certificate: the certificate asso‐
1472 ciated with the private key - passphrase: A passphrase
1473 for the pkcs12 file.
1474 The function returns a KeyData object.
1476 retrieve_key_data(data)
1478 Retrieve a secret from the DRM.
1479 @param: data - a KeyRecoveryRequest containing the keyId
1481 of the secret being retrieved, the request_id of the
1482 approved recovery request and a wrapping mechanism. More
1483 details at KRAClient.retrieve_key.
1484 Returns a KeyData object containing the wrapped secret.
1486 set_crypto_algorithms()
1488 set_transport_cert(transport_cert_nick)
1490 Set the transport certificate for crypto operations
1491 submit_request(request)
1493 Submit an archival, recovery or key generation request to
1494 the DRM.
1495 @param request - is either a KeyArchivalRequest, KeyRe‐
1497 coverRequest, SymKeyGenerationRequest or AsymKeyGenera‐
1498 tionRequest.
1499 returns a KeyRequestResponse object.
1501 class pki.key.KeyData
1503 Bases: object
1504 This is the object that contains the encoded wrapped secret when
1506 that secret is retrieved. It is used by the DRM to send informa‐
1507 tion of the key in the key retrieval requests.
1508 classmethod from_json(attr_list)
1510 Return a KeyData object from a JSON dict
1511 json_attribute_names = {'encryptAlgorithmOID': 'encrypt_algo‐
1513 rithm_oid', 'nonceData': 'nonce_data', 'publicKey': 'pub‐
1514 lic_key', 'requestID': 'request_id', 'wrapAlgorithm':
1515 'wrap_algorithm', 'wrappedPrivateData': 'wrapped_private_data'}
1516 class pki.key.KeyInfo
1518 Bases: object
1519 This is the object that contains information stored in the data‐
1521 base record for an archived secret. It does not contain the
1522 secret itself.
1523 classmethod from_json(attr_list)
1525 Return KeyInfo from JSON dict
1526 get_key_id()
1528 Return the key ID as parsed from key URL
1529 json_attribute_names = {'clientKeyID': 'client_key_id',
1531 'keyURL': 'key_url', 'ownerName': 'owner_name', 'publicKey':
1532 'public_key'}
1533 class pki.key.KeyInfoCollection
1535 Bases: object
1536 This class represents data returned when searching the DRM
1538 archived secrets. Essentially, its a list of KeyInfo objects.
1539 classmethod from_json(json_value)
1541 Return a KeyInfoCollection object from its JSON represen‐
1542 tation
1543 class pki.key.KeyRecoveryRequest(key_id=None, request_id=None,
1545 trans_wrapped_session_key=None, session_wrapped_passphrase=None,
1546 nonce_data=None, certificate=None, passphrase=None, payload_wrap‐
1547 ping_name=None, payload_encryption_oid=None)
1548 Bases: pki.ResourceMessage
1549 Class representing the data sent to the DRM when either creating
1551 a request for the recovery of a secret, or, once the request is
1552 approved, retrieving the secret.
1553 class pki.key.KeyRequestInfo
1555 Bases: object
1556 This class represents data about key requests (archival, recov‐
1558 ery, key generation etc.) in the DRM.
1559 classmethod from_json(attr_list)
1561 Return a KeyRequestInfo object from a JSON dict.
1562 get_key_id()
1564 Return the ID of the secret referred to by this request.
1565 get_request_id()
1567 Return the request ID by parsing the request URL.
1568 json_attribute_names = {'keyURL': 'key_url', 'requestStatus':
1570 'request_status', 'requestType': 'request_type', 'requestURL':
1571 'request_url'}
1572 class pki.key.KeyRequestInfoCollection
1574 Bases: object
1575 This class represents the data returned when searching the key
1577 requests in the DRM. Essentially, its a list of KeyRequestInfo
1578 objects.
1579 classmethod from_json(json_value)
1581 Return a KeyRequestInfoCollection object from its JSON
1582 representation.
1583 class pki.key.KeyRequestResponse
1585 Bases: object
1586 This class is returned when an archival, recovery or key genera‐
1588 tion request is created. It includes a KeyRequestInfo object
1589 with information about the created request, and a KeyData struc‐
1590 ture which contains the wrapped secret (if that operation is
1591 supported).
1592 classmethod from_json(json_value)
1594 Return a KeyRequestResponse object from its JSON repre‐
1595 sentation.
1596 get_key_id()
1598 Return the id for the key archived, recovered or gener‐
1599 ated
1600 get_request_id()
1602 Return the id for the created request
1603 class pki.key.RequestId(req_id)
1605 Bases: object
1606 Class representing a Request ID
1608 class pki.key.SymKeyGenerationRequest(client_key_id=None,
1610 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1611 sion_key=None, realm=None)
1612 Bases: pki.ResourceMessage
1613 Class representing the data sent to the DRM when generating and
1615 archiving a symmetric key in the DRM.
1616 DECRYPT_USAGE = 'decrypt'
1618 ENCRYPT_USAGE = 'encrypt'
1620 SIGN_USAGE = 'sign'
1622 UNWRAP_USAGE = 'unwrap'
1624 VERIFY_USAGE = 'verify'
1626 WRAP_USAGE = 'wrap'
1628 pki.key.main()
1630 Some unit tests - basically printing different types of requests
1631 kra Module
1633 Module containing KRAClient class. This class should be used by Python
1634 clients to interact with the DRM to expose the functionality of the
1635 KeyClient and KeyRequestResource REST APIs.
1636 class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
1638 Bases: object
1639 Client class that models interactions with a KRA using the Key
1641 and KeyRequest REST APIs.
1642 profile Module
1644 class pki.profile.Descriptor(syntax=None, constraint=None, descrip‐
1645 tion=None, default_value=None)
1646 Bases: object
1647 This class represents the description of a ProfileAttribute. It
1649 stores information such as the syntax, constraint and default
1650 value of a profile attribute.
1651 classmethod from_json(attr_list)
1653 json_attribute_names = {'Constraint': 'constraint', 'Default‐
1655 Value': 'default_value', 'Description': 'description', 'Syntax':
1656 'syntax'}
1657 class pki.profile.PolicyConstraint(name=None, description=None,
1659 class_id=None, policy_constraint_values=None)
1660 Bases: object
1661 An object of this class contains the policy constraints applied
1663 to a ProfileInput used by a certificate enrollment request.
1664 add_constraint_value(policy_constraint_value)
1666 Add a PolicyConstraintValue to the policy_constraint_val‐
1667 ues list.
1668 classmethod from_json(attr_list)
1670 get_constraint_value(policy_constraint_value_name)
1672 Returns a PolicyConstraintValue object with the given
1673 name. None, if there is no match.
1674 json_attribute_names = {'classId': 'class_id', 'constraint':
1676 'policy_constraint_values', 'id': 'name'}
1677 remove_constraint_value(policy_constraint_value_name)
1679 Removes a PolicyConstraintValue with the given name form
1680 the policy_constraint_values list.
1681 class pki.profile.PolicyConstraintValue(name=None, value=None, descrip‐
1683 tor=None)
1684 Bases: object
1685 Represents a PolicyConstraintValue
1687 classmethod from_json(attr_list)
1689 property name
1691 class pki.profile.PolicyDefault(name=None, class_id=None, descrip‐
1693 tion=None, policy_attributes=None, policy_params=None)
1694 Bases: object
1695 An object of this class contains information of the default
1697 usage of a specific ProfileInput.
1698 add_attribute(policy_attribute)
1700 Add a policy attribute to the attribute list. @param
1701 policy_attribute - A ProfileAttribute object
1702 add_parameter(policy_parameter)
1704 Add a profile parameter to the parameters list. @param
1705 policy_parameter - A ProfileParameter object.
1706 classmethod from_json(attr_list)
1708 get_attribute(policy_attribute_name)
1710 Fetch the policy attribute with the given name from the
1711 attributes list.
1712 get_parameter(profile_parameter_name)
1714 Fetch a profile parameter with the given name from the
1715 parameters list.
1716 json_attribute_names = {'classId': 'class_id', 'id': 'name',
1718 'params': 'policy_params', 'policyAttribute': 'pol‐
1719 icy_attributes'}
1720 remove_attribute(policy_attribute_name)
1722 Remove a policy attribute with the given name from the
1723 attributes list.
1724 remove_parameter(profile_parameter_name)
1726 Remove a profile parameter with the given name from the
1727 parameters list.
1728 class pki.profile.PolicySet(name=None, policy_list=None)
1730 Bases: object
1731 An object of this class contains a name value pair of the policy
1733 name and the ProfilePolicy object.
1734 add_policy(profile_policy)
1736 Add a ProfilePolicy object to the policy_list
1737 classmethod from_json(attr_list)
1739 get_policy(policy_id)
1741 Returns a ProfilePolicy object with the given profile id.
1742 json_attribute_names = {'id': 'name', 'value': 'policy_list'}
1744 remove_policy(policy_id)
1746 Removes a ProfilePolicy with the given ID from the Poli‐
1747 cySet.
1748 class pki.profile.PolicySetList(policy_sets=None)
1750 Bases: object
1751 An object of this class stores a list of ProfileSet objects.
1753 add_policy_set(policy_set)
1755 Add a PolicySet object to the policy_sets list.
1756 classmethod from_json(attr_list)
1758 get_policy_set(policy_set_name)
1760 Fetch the PolicySet object for the given name. Returns
1761 None, if not found.
1762 property policy_sets
1764 remove_policy_set(policy_set_name)
1766 Remove a PolicySet object with the given name from the
1767 policy_sets list.
1768 class pki.profile.Profile(profile_id=None, class_id=None, name=None,
1770 description=None, enabled=None, visible=None, enabled_by=None, authen‐
1771 ticator_id=None, authorization_acl=None, renewal=None, xml_output=None,
1772 inputs=None, outputs=None, policy_set_list=None, link=None)
1773 Bases: object
1774 This class represents an enrollment profile.
1776 add_input(profile_input)
1778 Add a ProfileInput object to the inputs list of the Pro‐
1779 file.
1780 add_output(profile_output)
1782 Add a ProfileOutput object to the outputs list of the
1783 Profile.
1784 add_policy_set(policy_set)
1786 Add a PolicySet object to the policy_sets list of the
1787 Profile.
1788 classmethod from_json(attr_list)
1790 get_input(profile_input_id)
1792 Fetches a ProfileInput with the given ProfileInput id.
1793 Returns None, if there is no matching input.
1794 get_output(profile_output_id)
1796 Fetches a ProfileOutput with the given ProfileOutput id.
1797 Returns None, if there is no matching output.
1798 get_policy_set(policy_set_name)
1800 Fetches a ProfileInput with the given ProfileInput id.
1801 Returns None, if there is no matching input.
1802 static get_profile_data_from_file(path_to_file)
1804 Reads the file for the serialized Profile object. Cur‐
1805 rently supports only data format in json.
1806 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
1808 'PolicySets': 'policy_set_list', 'authenticatorId': 'authentica‐
1809 tor_id', 'authzAcl': 'authorization_acl', 'classId': 'class_id',
1810 'enabledBy': 'enabled_by', 'id': 'profile_id', 'xmlOutput':
1811 'xml_output'}
1812 remove_input(profile_input_id)
1814 Remove a ProfileInput from the inputs list of the Pro‐
1815 file.
1816 remove_output(profile_output_id)
1818 Remove a ProfileOutput from the outputs list of the Pro‐
1819 file.
1820 remove_policy_set(policy_set_name)
1822 Remove a PolicySet from the policy_sets list of the Pro‐
1823 file.
1824 class pki.profile.ProfileAttribute(name=None, value=None, descrip‐
1826 tor=None)
1827 Bases: object
1828 Represents a profile attribute of a ProfileInput.
1830 classmethod from_json(attr_list)
1832 json_attribute_names = {'Descriptor': 'descriptor', 'Value':
1834 'value'}
1835 class pki.profile.ProfileClient(connection)
1837 Bases: object
1838 This class consists of methods for accessing the ProfileRe‐
1840 source.
1841 create_profile(profile_data)
1843 Create a new profile for the given Profile object.
1844 create_profile_from_file(path_to_file)
1846 Reads the file for the serialized Profile object. Per‐
1847 forms the profile create operation. Currently supports
1848 only data format in json.
1849 delete_profile(profile_id)
1851 Delete a profile with the given Profile Id.
1852 disable_profile(profile_id)
1854 Disables a profile.
1855 enable_profile(profile_id)
1857 Enables a profile.
1858 get_profile(profile_id)
1860 Fetches information for the profile for the given profile
1861 id. Returns a ProfileData object.
1862 list_profiles(start=None, size=None)
1864 Fetches the list of profiles. The start and size argu‐
1865 ments provide pagination support. Returns a Profile‐
1866 DataInfoCollection object.
1867 modify_profile(profile_data)
1869 Modify an existing profile with the given Profile object.
1870 modify_profile_from_file(path_to_file)
1872 Reads the file for the serialized Profile object. Per‐
1873 forms the profile modify operation. Currently supports
1874 only data format in json.
1875 class pki.profile.ProfileDataInfo
1877 Bases: object
1878 Stores information about a profile
1880 classmethod from_json(attr_list)
1882 json_attribute_names = {'profileDescription': 'profile_descrip‐
1884 tion', 'profileId': 'profile_id', 'profileName': 'profile_name',
1885 'profileURL': 'profile_url'}
1886 class pki.profile.ProfileDataInfoCollection
1888 Bases: object
1889 Represents a collection of ProfileDataInfo objects. Also encap‐
1891 sulates the links for the list of the objects stored.
1892 classmethod from_json(attr_list)
1894 class pki.profile.ProfileInput(profile_input_id=None, class_id=None,
1896 name=None, text=None, attributes=None, config_attributes=None)
1897 Bases: object
1898 This class encapsulates all the attributes of a profile to gen‐
1900 erate a specific property of a certificate. Ex. Subject name,
1901 Requestor Information etc.
1902 add_attribute(profile_attribute)
1904 Add a ProfileAttribute object to the attributes list.
1905 add_config_attribute(profile_attribute)
1907 Add a ProfileAttribute object to the config_attributes
1908 list.
1909 classmethod from_json(attr_list)
1911 get_attribute(profile_attribute_name)
1913 Returns a ProfileAttribute object for the given name.
1914 None, if no match.
1915 get_config_attribute(config_attribute_name)
1917 Returns a ProfileAttribute object with the given name.
1918 None, if there is no match in the config_attributes list.
1919 json_attribute_names = {'Attribute': 'attributes', 'ClassID':
1921 'class_id', 'ConfigAttribute': 'config_attributes', 'Name':
1922 'name', 'Text': 'text', 'id': 'profile_input_id'}
1923 remove_attribute(profile_attribute_name)
1925 Remove a ProfileAttribute object with the given name from
1926 the attributes list.
1927 remove_config_attribute(config_attribute_name)
1929 Remove a ProfileAttribute object with the given name from
1930 the config_attributes list.
1931 class pki.profile.ProfileOutput(profile_output_id=None, name=None,
1933 text=None, class_id=None, attributes=None)
1934 Bases: object
1935 This class defines the output of a certificate enrollment
1937 request using a profile.
1938 add_attribute(profile_attribute)
1940 Add a ProfileAttribute object to the attributes list.
1941 classmethod from_json(attr_list)
1943 get_attribute(profile_attribute_name)
1945 Returns a ProfileAttribute object for the given name.
1946 None, if no match.
1947 json_attribute_names = {'classId': 'class_id', 'id': 'pro‐
1949 file_output_id'}
1950 remove_attribute(profile_attribute_name)
1952 Remove a ProfileAttribute object with the given name from
1953 the attributes list.
1954 class pki.profile.ProfileParameter(name=None, value=None)
1956 Bases: object
1957 classmethod from_json(attr_list)
1959 class pki.profile.ProfilePolicy(policy_id=None, policy_default=None,
1961 policy_constraint=None)
1962 Bases: object
1963 This class represents the policy a profile adheres to. An
1965 object of this class stores the default values for profile and
1966 the constraints present on the values of the attributes of the
1967 profile submitted for an enrollment request.
1968 classmethod from_json(attr_list)
1970 json_attribute_names = {'constraint': 'policy_constraint',
1972 'def': 'policy_default', 'id': 'policy_id'}
1973 class pki.profile.ProfilePolicySet
1975 Bases: object
1976 Stores a list of ProfilePolicy objects.
1978 classmethod from_json(attr_list)
1980 pki.profile.main()
1982 system Module
1984 class pki.system.AdminSetupRequest
1985 Bases: object
1986 class pki.system.AdminSetupResponse
1988 Bases: object
1989 class pki.system.CertificateSetupRequest
1991 Bases: object
1992 class pki.system.CertificateSetupResponse
1994 Bases: object
1995 class pki.system.CloneSetupRequest
1997 Bases: object
1998 class pki.system.ConfigurationRequest
2000 Bases: object
2001 Class used to represent a configuration request to be submitted
2003 to the Java installation servlet during the execution of
2004 pkispawn.
2005 This class is the python equivalent of the Java class: com.net‐
2007 scape.certsrv.system.ConfigurationRequest
2008 class pki.system.DatabaseSetupRequest
2010 Bases: object
2011 class pki.system.DatabaseUserSetupRequest
2013 Bases: object
2014 class pki.system.DomainInfo
2016 Bases: object
2017 Class representing the entire security domain. This is essen‐
2019 tially a list of SecurityDomainSubsystem components.
2020 classmethod from_json(json_value)
2022 Create a DomainInfo object from JSON.
2023 Parameters
2025 json_value (str) -- JSON representation of a secu‐
2026 rity domain.
2027 Returns
2029 DomainInfo
2030 property systems
2032 class pki.system.FinalizeConfigRequest
2034 Bases: object
2035 class pki.system.InstallToken
2037 Bases: object
2038 classmethod from_json(json_value)
2040 class pki.system.SecurityDomainClient(connection)
2042 Bases: object
2043 Client used to get the security domain from a security domain
2045 CA. The connection details for the security domain CA are spec‐
2046 ified in a PKIConnection object used to construct this client.
2047 get_domain_info()
2049 Contact the security domain CA specified in the connec‐
2050 tion object used to construct this client and get the
2051 security domain using the REST API.
2052 Returns
2054 pki.system.DomainInfo
2055 get_install_token(hostname, subsystem)
2057 Returns
2059 pki.system.InstallToken
2060 get_old_domain_info()
2062 Contact the security domain CA specified in the connec‐
2063 tion object used to construct this client and get the
2064 security domain using the old servlet-based interface.
2065 This method is useful when contacting old servers which
2066 do not provide the REST API.
2067 Returns
2069 pki.system.DomainInfo
2070 get_security_domain_info()
2072 class pki.system.SecurityDomainHost
2074 Bases: object
2075 Class representing a security domain host.
2077 classmethod from_json(json_value)
2079 Constructs a SecurityDomainHost object from JSON.
2080 Parameters
2082 json_value (str) -- JSON string representing a
2083 security domain host.
2084 Returns
2086 SecurityDomainHost
2087 class pki.system.SecurityDomainSetupRequest
2089 Bases: object
2090 class pki.system.SecurityDomainSubsystem
2092 Bases: object
2093 Class representing a security domain subsystem. This is essen‐
2095 tially a list of SecurityDomainHost objects of a particular sub‐
2096 system type (ca, kra, tps, tks, ocsp).
2097 classmethod from_json(json_value)
2099 Constructs a SecurityDomainSubsystem from a JSON repre‐
2100 sentation.
2101 Parameters
2103 json_value (str) -- JSON representation of the
2104 Security Domain Subsystem
2105 Returns
2107 SecurityDomainSubsystem
2108 get_host(hostname, secure_port)
2110 class pki.system.SystemCertData
2112 Bases: object
2113 Class used to represent the data for a system certificate, which
2115 is used in the data passed into and returned from the Java
2116 installation servlet during the execution of pkispawn.
2117 This class is the python equivalent of the Java class: com.net‐
2119 scape.certsrv.system.SystemCertData
2120 class pki.system.SystemConfigClient(connection, subsystem=None)
2122 Bases: object
2123 Client used to interact with the Java configuration servlet to
2125 configure a Dogtag subsystem during the execution of pkispawn.
2126 The connection details for the system being configured are
2128 passed in the PKIConnection object used when constructing this
2129 object.
2130 configure(request)
2132 Contacts the server and invokes the Java configuration
2133 REST API to configure a Dogtag subsystem.
2134 Parameters
2136 request (ConfigurationRequest) -- Configuration
2137 request containing all the input needed to config‐
2138 ure the subsystem
2139 finalizeConfiguration(request)
2141 Finalize server configuration.
2142 Parameters
2144 request (FinalizeConfigRequest) -- Finalize con‐
2145 figuration request
2146 setupAdmin(request)
2148 Set up admin.
2149 Parameters
2151 request (AdminSetupRequest) -- Admin setup request
2152 Returns
2154 AdminSetupResponse
2155 setupCert(request)
2157 Set up certificate.
2158 Parameters
2160 request (CertificateSetupRequest) -- Certificate
2161 setup request
2162 Returns
2164 SystemCertData
2165 setupClone(request)
2167 Set up clone.
2168 Parameters
2170 request (CloneSetupRequest) -- Clone setup request
2171 setupDatabase(request)
2173 Set up database.
2174 Parameters
2176 request (DatabaseSetupRequest) -- Database setup
2177 request
2178 setupDatabaseUser(request)
2180 Set up database user.
2181 Parameters
2183 request (DatabaseUserSetupRequest) -- Database
2184 user setup request
2185 setupSecurityDomain(request)
2187 Setup security domain.
2188 Parameters
2190 request (SecurityDomainSetupRequest) -- Security
2191 domain setup request
2192 class pki.system.SystemStatusClient(connection, subsystem=None)
2194 Bases: object
2195 Client used to check the status of a Dogtag subsystem.
2197 get_status(timeout=None)
2199 Checks the status of the subsystem by calling the getSta‐
2200 tus() servlet. This is used to determine if the server
2201 is up and ready to receive and process requests.
2202 Returns
2204 str - getStatus response
2205 systemcert Module
2207 Module containing the Python client classes for the SystemCert REST API
2208 class pki.systemcert.SystemCertClient(connection)
2210 Bases: object
2211 Class encapsulating and mirroring the functionality in the Sys‐
2213 temCertResource Java interface class defining the REST API for
2214 system certificate resources.
2215 get_transport_cert()
2217 Return transport certificate.
2218 Returns
2220 pki.cert.CertData -- transport certificate data
2221 upgrade Module
2223 class pki.upgrade.PKIUpgradeScriptlet
2224 Bases: object
2225 backup(path)
2227 can_upgrade()
2229 get_backup_dir()
2231 init()
2233 revert()
2235 update_tracker()
2237 upgrade()
2239 upgrade_system()
2241 class pki.upgrade.PKIUpgradeTracker(name, filename, delimiter='=', ver‐
2243 sion_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
2244 Bases: object
2245 get_index()
2247 get_version()
2249 remove()
2251 remove_index()
2253 remove_version()
2255 set(version)
2257 set_index(index)
2259 set_version(version)
2261 show()
2263 class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade',
2265 version=None, index=None, silent=False)
2266 Bases: object
2267 all_versions()
2269 get_current_version()
2271 get_target_version()
2273 get_tracker()
2275 is_complete()
2277 remove_tracker()
2279 reset_tracker()
2281 revert()
2283 revert_version(version)
2285 scriptlets(version)
2287 set_tracker(version)
2289 show_tracker()
2291 status()
2293 upgrade()
2295 upgrade_version(version)
2297 validate()
2299 version_dir(version)
2301 versions()
2303 util Module
2305 Module containing utility functions and classes for the Dogtag python
2306 code
2307 class pki.util.Version(obj)
2309 Bases: object
2310 pki.util.chmod(path, perms)
2312 Change permissions of a file, link, or folder recursively.
2313 pki.util.chown(path, uid, gid)
2315 Change ownership of a file, link, or folder recursively.
2316 pki.util.copy(source, dest, uid=-1, gid=-1, force=False)
2318 Copy a file or a folder and its contents.
2319 pki.util.copydirs(source, dest, uid=-1, gid=-1, force=False)
2321 Copy a folder and its parents while preserving their attributes.
2322 pki.util.copyfile(source, dest, slots=None, params=None, uid=None,
2324 gid=None, perms=None, force=False)
2325 Copy a file or link while preserving its attributes.
2326 pki.util.copytree(src, dst, symlinks=False, ignore=None)
2328 Recursively copy a directory tree using copy2().
2329 PATCH: This code was copied from 'shutil.py' and patched to
2331 allow 'The destination directory to already exist.'
2332 If exception(s) occur, an Error is raised with a list of rea‐
2334 sons.
2335 If the optional symlinks flag is true, symbolic links in the
2337 source tree result in symbolic links in the destination tree; if
2338 it is false, the contents of the files pointed to by symbolic
2339 links are copied.
2340 The optional ignore argument is a callable. If given, it is
2342 called with the src parameter, which is the directory being vis‐
2343 ited by copytree(), and names which is the list of src contents,
2344 as returned by os.listdir():
2345 callable(src, names) -> ignored_names
2346 Since copytree() is called recursively, the callable will be
2348 called once for each directory that is copied. It returns a list
2349 of names relative to the src directory that should not be
2350 copied.
2351 Consider this example code rather than the ultimate tool.
2353 pki.util.customize_file(input_file, output_file, params)
2355 Customize a file with specified parameters.
2356 pki.util.load_properties(filename, properties)
2358 pki.util.makedirs(path, uid=-1, gid=-1, force=False)
2360 pki.util.read_environment_files(env_file_list=None)
2362 pki.util.read_text(message, options=None, default=None, delimiter=':',
2364 allow_empty=True, case_sensitive=True)
2365 Get an input from the user. This is used, for example, in
2366 pkispawn and pkidestroy to obtain user input.
2367 Parameters
2369 · message (str) -- prompt to display to the user
2371 · options (list) -- list of possible inputs by the user.
2373 · default (str) -- default value of parameter being
2375 prompted.
2376 · delimiter (str) -- delimiter to be used at the end of
2378 the prompt.
2379 · allow_empty (boolean -- True/False) -- Allow input to
2381 be empty.
2382 · case_sensitive (boolean -- True/False) -- Allow input
2384 to be case sensitive.
2385 Returns
2387 str -- value obtained from user input.
2388 pki.util.remove(path, force=False)
2390 pki.util.replace_params(line, params=None)
2392 Replace all occurrences of [param] in the line with the value of
2393 the parameter.
2394 pki.util.rmtree(path, force=False)
2396 pki.util.store_properties(filename, properties)
2398 pki.util.symlink(source, dest, uid=-1, gid=-1, force=False)
2400 pki.util.unlink(link, force=False)
2402 · genindex
2404 · modindex
2406 · search
2408
2410 Dogtag PKI Project Team
2411
2413 2020, Dogtag PKI Team
2414@APPLICATION_VERSION@ Apr 27, 2020 PKI-PYTHON-CLIENT(1)