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 exception pki.ForbiddenException(message, exception=None, code=None,
53 class_name=None)
54 Bases: pki.PKIException
55 Forbidden Exception: return code = 403
57 exception pki.GroupNotFoundException(message, exception=None,
59 code=None, class_name=None)
60 Bases: pki.ResourceNotFoundException
61 Group Not Found Exception: return code = 404
63 exception pki.HTTPGoneException(message, exception=None, code=None,
65 class_name=None)
66 Bases: pki.PKIException
67 Gone Exception: return code = 410
69 exception pki.KeyNotFoundException(message, exception=None, code=None,
71 class_name=None)
72 Bases: pki.ResourceNotFoundException
73 Key Not Found Exception: return code 404
75 class pki.Link
77 Bases: object
78 Stores the information of the resteasy's Link object sent by
80 the server for a resource.
81 classmethod from_json(attr_list)
83 Generate Link from JSON
84 Parameters
86 attr_list (str) -- JSON representation of Link
87 Returns
89 pki.Link
90 exception pki.PKIException(message, exception=None, code=None,
92 class_name=None)
93 Bases: Exception, pki.ResourceMessage
94 Base exception class for REST Interface
96 classmethod from_json(json_value)
98 Construct PKIException from JSON. :param json_value:
99 JSON representation of the exception. :type json_value:
100 str :return: pki.PKIException
101 exception pki.ProfileNotFoundException(message, exception=None,
103 code=None, class_name=None)
104 Bases: pki.ResourceNotFoundException
105 Profile Not Found Exception: return code = 404
107 class pki.PropertyFile(filename, delimiter='=')
109 Bases: object
110 Class to manage property files The contents of the property
112 file are maintained internally as a list of properties.
113 Properties are strings of the format <name> <delimiter> <value>
115 where '=' is the default delimiter.
116 get(name)
118 Get the value of the specified property.
119 Parameters
121 name (str) -- name of property to be fetched.
122 Returns
124 str -- value of property
125 index(name)
127 Find the index (position) of a property in a property
128 file.
129 Parameters
131 name (str) -- name of property
132 Returns
134 int -- index of property.
135 insert_line(index, line)
137 Insert property into the list of properties maintained by
138 this object at the specified location (index).
139 Parameters
141 · index (int) -- point at which to insert value.
143 · line (str) -- value to be inserted.
145 Returns
147 None
148 read() Read from property file into the list of properties main‐
150 tained by this object.
151 Returns
153 None
154 remove(name)
156 Remove property from list of properties maintained by
157 this object.
158 Parameters
160 name (str) -- name of property to be removed.
161 Returns
163 None
164 remove_line(index)
166 Remove property at specified index from the properties
167 list.
168 Parameters
170 index (int) -- location of property to be removed.
171 Returns
173 None
174 set(name, value, index=None)
176 Set value of specified property.
177 Parameters
179 · name (str) -- name of property to set.
181 · value (str) -- value to set
183 · index (int) -- (optional) position of property
185 Returns
187 None
188 show() Print the contents of the list of properties maintained
190 by this object to STDOUT.
191 Returns
193 None
194 write()
196 Write the list of properties maintained by this object to
197 the property file.
198 Returns
200 None
201 exception pki.RequestNotFoundException(message, exception=None,
203 code=None, class_name=None)
204 Bases: pki.ResourceNotFoundException
205 Request Not Found Exception: return code = 404
207 class pki.ResourceMessage(class_name)
209 Bases: object
210 This class is the basis for the various types of key requests.
212 It is essentially a list of attributes.
213 add_attribute(name, value)
215 Add an attribute to the list.
216 Parameters
218 · name (str) -- name of attribute to add
220 · value (str) -- value to add
222 Returns
224 None
225 get_attribute_value(name)
227 Get the value of a given attribute.
228 Parameters
230 name (str) -- name of attribute to retrieve
231 Returns
233 str -- value of parameter
234 exception pki.ResourceNotFoundException(message, exception=None,
236 code=None, class_name=None)
237 Bases: pki.PKIException
238 Not Found Exception: return code = 404
240 exception pki.UnauthorizedException(message, exception=None, code=None,
242 class_name=None)
243 Bases: pki.PKIException
244 Unauthorized Exception: return code = 401
246 exception pki.UserNotFoundException(message, exception=None, code=None,
248 class_name=None)
249 Bases: pki.ResourceNotFoundException
250 User Not Found Exception: return code = 404
252 pki.convert_x509_name_to_dn(name)
254 Convert X.509 Name into NSS-style DN string.
255 See also: -
257 https://cryptography.io/en/latest/x509/reference/#cryptography.x509.Name
258 -
259 https://cryptography.io/en/latest/x509/reference/#cryptography.x509.NameAttribute
260 -
261 https://cryptography.io/en/latest/x509/reference/#cryptography.x509.ObjectIdentifier
262 Parameters
264 name (cryptography.x509.Name) -- X.509 Name
265 Returns
267 str -- DN string.
268 pki.generate_password()
270 This function generates FIPS-compliant password.
271 See sftk_newPinCheck() in the following file:
273 https://dxr.mozilla.org/nss/source/nss/lib/softoken/fipstokn.c
274 The minimum password length is FIPS_MIN_PIN Unicode characters.
276 The password must contain at least 3 character classes:
278 · digits (string.digits)
280 · ASCII lowercase letters (string.ascii_lowercase)
282 · ASCII uppercase letters (string.ascii_uppercase)
284 · ASCII non-alphanumeric characters (PUNCTUATIONS)
286 · non-ASCII characters
288 If an ASCII uppercase letter is the first character of the pass‐
290 word, the uppercase letter is not counted toward its character
291 class.
292 If a digit is the last character of the password, the digit is
294 not counted toward its character class.
295 The FIPS_MIN_PIN is defined in the following file:
297 https://dxr.mozilla.org/nss/source/nss/lib/softoken/pkcs11i.h
298 #define FIPS_MIN_PIN 7
300 pki.get_info(name)
302 pki.handle_exceptions()
304 Decorator handling exceptions from REST methods.
305 pki.implementation_version()
307 Return implementation version.
308 Returns
310 str -- implementation version
311 pki.specification_version()
313 Return specification version.
314 Returns
316 str -- specification version
317 account Module
319 class pki.account.AccountClient(connection)
320 Bases: object
321 Class used to associate an authentication session variable with
323 a connection.
324 To use this class:
326 · set the authentication credentials with the connection,
328 · create an AccountClient and then call login().
330 · further operations in this session will use the same
332 authentication credentials without re-authentication.
333 · call logout() to invalidate the session.
335 login()
337 Login to account REST interface. If login is successful,
338 an authentication session variable is associated with the
339 connection.
340 Returns
342 None
343 logout()
345 Logs out of the session. Authentication session vari‐
346 ables are invalidated for the connection
347 Returns
349 None
350 cert Module
352 class pki.cert.CertClient(connection)
353 Bases: object
354 Class encapsulating and mirroring the functionality in the
356 CertResource Java interface class defining the REST API for Cer‐
357 tificate resources.
358 approve_request(request_id, cert_review_response=None)
360 Approves a certificate enrollment request. If
361 cert_review_response is None, a review request operation
362 is performed to fetch the CertReviewResponse object.
363 Requires as agent level authentication.
364 assign_request(request_id, cert_review_response)
366 Assigns a certificate enrollment request. If
367 cert_review_response is None, a review request operation
368 is performed to fetch the CertReviewResponse object.
369 Requires as agent level authentication.
370 cancel_request(request_id, cert_review_response=None)
372 Cancels a certificate enrollment request. If
373 cert_review_response is None, a review request operation
374 is performed to fetch the CertReviewResponse object.
375 Requires as agent level authentication.
376 create_enrollment_request(profile_id, inputs)
378 Fetches the enrollment request object for the given pro‐
379 file and sets values to its attributes using the values
380 provided in the inputs dictionary. Returns the CertEn‐
381 rollmentRequest object, which can be submitted to enroll
382 a certificate.
383 enroll_cert(profile_id, inputs, authority=None)
385 A convenience method for enrolling a certificate for a
386 given profile id. The inputs parameter should be a dic‐
387 tionary with values for the profile attributes for an
388 enrollment request.
389 Calling this method with valid arguments, creates an
391 enrollment request, submits it to the server, approves
392 the certificate requests generated for the enrollment and
393 returns a list of CertData objects for all the certifi‐
394 cates generated as part of this enrollment.
395 Note: This method supports only certificate enrollment
397 where only one agent approval is sufficient.
398 Requires an agent level authentication. Returns a list
400 of CertEnrollmentResult objects.
401 get_cert(cert_serial_number)
403 Return a CertData object for a particular certificate.
404 get_enrollment_template(profile_id)
406 Fetch the enrollment template for the given profile id.
407 For the first time, the request is sent to the server.
408 The retrieved CertEnrollmentRequest object is then cached
409 locally for future requests. Returns a CerEnrollmentRe‐
410 quest object.
411 get_request(request_id)
413 Get information of a certificate request with the given
414 request ID. Returns a CertRequestInfo object.
415 hold_cert(cert_serial_number, comments=None, authority=None)
417 Places a certificate on-hold. Calls the revoke_cert
418 method with reason - CertRevokeRequest.REASON_CERTIFI‐
419 CATE_HOLD. Returns a CertRequestInfo object. This
420 method requires an agent's authentication cert in the
421 connection object.
422 list_certs(max_results=None, max_time=None, start=None,
424 size=None, **cert_search_params)
425 Return a CertDataInfoCollection object with a information
426 about all the certificates that satisfy the search crite‐
427 ria. If cert_search_request=None, returns all the cer‐
428 tificates.
429 list_enrollment_templates(start=None, size=None)
431 Gets the list of profile templates supported by the CA.
432 The values for start and size arguments determine the
433 starting point and the length of the list. Returns a
434 ProfileDataInfoCollection object.
435 list_requests(request_status=None, request_type=None,
437 from_request_id=None, size=None, max_results=None,
438 max_time=None)
439 Query for a list of certificates using the arguments
440 passed. Returns a CertRequestInfoCollection object.
441 reject_request(request_id, cert_review_response=None)
443 Rejects a certificate enrollment request. If
444 cert_review_response is None, a review request operation
445 is performed to fetch the CertReviewResponse object.
446 Requires as agent level authentication.
447 review_cert(cert_serial_number)
449 Reviews a certificate. Returns a CertData object with a
450 nonce. This method requires an agent's authentication
451 cert in the connection object.
452 review_request(request_id)
454 Reviews a certificate enrollment request. Returns a
455 CertReviewResponse object which contains the nonce from
456 the server needed to perform an action on the request.
457 revoke_ca_cert(cert_serial_number, revocation_reason=None, inva‐
459 lidity_date=None, comments=None, nonce=None, authority=None)
460 Revokes a CA certificate. Returns a CertRequestInfo
461 object with information about the request. This method
462 requires an agent's authentication cert in the connection
463 object.
464 revoke_cert(cert_serial_number, revocation_reason=None, invalid‐
466 ity_date=None, comments=None, nonce=None, authority=None)
467 Revokes a certificate. Returns a CertRequestInfo object
468 with information about the request. This method requires
469 an agent's authentication cert in the connection object.
470 submit_enrollment_request(enrollment_request, authority=None)
472 Submits the CertEnrollmentRequest object to the server.
473 Returns a CertRequestInfoCollection object with informa‐
474 tion about the certificate requests enrolled at the CA.
475 unassign_request(request_id, cert_review_response)
477 Un-assigns a certificate enrollment request. If
478 cert_review_response is None, a review request operation
479 is performed to fetch the CertReviewResponse object.
480 Requires as agent level authentication.
481 unrevoke_cert(cert_serial_number, authority=None)
483 Un-revokes a revoked certificate. Returns a CertRe‐
484 questInfo object. This method requires an agent's
485 authentication cert in the connection object.
486 update_request(request_id, cert_review_response)
488 Updates a certificate enrollment request. If
489 cert_review_response is None, a review request operation
490 is performed to fetch the CertReviewResponse object.
491 Requires as agent level authentication.
492 validate_request(request_id, cert_review_response)
494 Validates a certificate enrollment request. If
495 cert_review_response is None, a review request operation
496 is performed to fetch the CertReviewResponse object.
497 Requires as agent level authentication.
498 class pki.cert.CertData
500 Bases: object
501 Class containing certificate data as returned from getCert()
503 classmethod from_json(attr_list)
505 Return CertData object from JSON dict
506 json_attribute_names = {'Encoded': 'encoded', 'IssuerDN':
508 'issuer_dn', 'Link': 'link', 'Nonce': 'nonce', 'NotAfter':
509 'not_after', 'NotBefore': 'not_before', 'PKCS7CertChain':
510 'pkcs7_cert_chain', 'PrettyPrint': 'pretty_repr', 'Status':
511 'status', 'SubjectDN': 'subject_dn', 'id': 'serial_number'}
512 class pki.cert.CertDataInfo
514 Bases: object
515 Class containing information contained in a CertRecord on the
517 CA. This data is returned when searching/listing certificate
518 records.
519 classmethod from_json(attr_list)
521 Return CertDataInfo object from JSON dict
522 json_attribute_names = {'IssuedBy': 'issued_by', 'IssuedOn':
524 'issued_on', 'KeyAlgorithmOID': 'key_algorithm_oid',
525 'KeyLength': 'key_length', 'Link': 'link', 'NotValidAfter':
526 'not_valid_after', 'NotValidBefore': 'not_valid_before', 'Sta‐
527 tus': 'status', 'SubjectDN': 'subject_dn', 'Type': 'type', 'Ver‐
528 sion': 'version', 'id': 'serial_number'}
529 class pki.cert.CertDataInfoCollection
531 Bases: object
532 Class containing list of CertDataInfo objects and their respec‐
534 tive link objects. This data is returned when searching/listing
535 certificate records in the CA.
536 classmethod from_json(json_value)
538 Populate object from JSON input
539 class pki.cert.CertEnrollmentRequest(profile_id=None, renewal=False,
541 serial_number=None, remote_host=None, remote_address=None, inputs=None,
542 outputs=None)
543 Bases: object
544 This class encapsulates the parameters required for a certifi‐
546 cate
547 enrollment request.
548 add_input(profile_input)
550 add_output(profile_output)
552 classmethod from_json(attr_list)
554 get_input(profile_input_name)
556 get_output(profile_output_name)
558 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
560 'ProfileID': 'profile_id', 'RemoteAddress': 'remote_address',
561 'RemoteHost': 'remote_host', 'Renewal': 'renewal', 'SerialNum‐
562 ber': 'serial_number'}
563 remove_input(profile_input_name)
565 remove_output(profile_output_name)
567 class pki.cert.CertEnrollmentResult(request, cert)
569 Bases: object
570 Class containing results of an enrollment request.
572 This structure contains information about the cert request gen‐
574 erated and any certificates issued.
575 class pki.cert.CertRequestInfo
577 Bases: object
578 An object of this class stores represents a certificate request.
580 classmethod from_json(attr_list)
582 json_attribute_names = {'certId': 'cert_id', 'certRequestType':
584 'cert_request_type', 'certURL': 'cert_url', 'errorMessage':
585 'error_message', 'operationResult': 'operation_result',
586 'requestStatus': 'request_status', 'requestType':
587 'request_type', 'requestURL': 'request_url'}
588 class pki.cert.CertRequestInfoCollection
590 Bases: object
591 Class containing list of CertRequestInfo objects. This data is
593 returned when listing certificate request records in the CA.
594 classmethod from_json(json_value)
596 Populate object from JSON input
597 class pki.cert.CertRequestStatus
599 Bases: object
600 Class containing valid cert statuses.
602 CANCELED = 'canceled'
604 COMPLETE = 'complete'
606 PENDING = 'pending'
608 REJECTED = 'rejected'
610 class pki.cert.CertReviewResponse(profile_id=None, renewal=False,
612 serial_number=None, remote_host=None, remote_address=None, inputs=None,
613 outputs=None, nonce=None, request_id=None, request_type=None,
614 request_status=None, request_owner=None, request_creation_time=None,
615 request_modification_time=None, request_notes=None, pro‐
616 file_approval_by=None, profile_set_id=None, profile_is_visible=None,
617 profile_name=None, profile_description=None, profile_remote_host=None,
618 profile_remote_address=None, policy_sets=None)
619 Bases: pki.cert.CertEnrollmentRequest
620 An object of this class represent the response from the server
622 when reviewing a certificate enrollment request. It contains a
623 nonce required to perform action on the request.
624 classmethod from_json(attr_list)
626 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
628 'ProfileID': 'profile_id', 'ProfilePolicySet': 'policy_sets',
629 'RemoteAddress': 'remote_address', 'RemoteHost': 'remote_host',
630 'Renewal': 'renewal', 'SerialNumber': 'serial_number', 'pro‐
631 fileApprovedBy': 'profile_approved_by', 'profileDescription':
632 'profile_description', 'profileIsVisible': 'profile_is_visible',
633 'profileName': 'profile_name', 'profileRemoteAddr': 'pro‐
634 file_remote_address', 'profileRemoteHost': 'pro‐
635 file_remote_host', 'profileSetId': 'profile_set_id',
636 'requestCreationTime': 'request_creation_time', 'requestId':
637 'request_id', 'requestModificationTime': 'request_modifica‐
638 tion_time', 'requestNotes': 'request_notes', 'requestOwner':
639 'request_owner', 'requestStatus': 'request_status', 'request‐
640 Type': 'request_type'}
641 class pki.cert.CertRevokeRequest(nonce, reason=None, invalid‐
643 ity_date=None, comments=None)
644 Bases: object
645 An object of this class encapsulates all the parameters required
647 for revoking a certificate.
648 Valid values for reasons for revoking a request are:
650 'Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affil‐
651 iation_Changed', 'Superseded', 'Cessation_of_Operation',
652 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_With‐
653 drawn', 'AA_Compromise'
654 reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise',
656 'Affiliation_Changed', 'Superseded', 'Cessation_of_Operation',
657 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_Withdrawn',
658 'AA_Compromise']
659 class pki.cert.CertSearchRequest(**cert_search_params)
661 Bases: object
662 An object of this class is used to store the search parameters
664 and send them to server.
665 search_params = {'cert_type_secure_email': 'certTypeSe‐
667 cureEmail', 'cert_type_ssl_client': 'certTypeSSLClient',
668 'cert_type_ssl_server': 'certTypeSSLServer',
669 'cert_type_sub_email_ca': 'certTypeSubEmailCA',
670 'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'common_name': 'com‐
671 monName', 'country': 'country', 'email': 'eMail', 'issued_by':
672 'issuedBy', 'issued_on_from': 'issuedOnFrom', 'issued_on_to':
673 'issuedOnTo', 'locality': 'locality', 'match_exactly': 'matchEx‐
674 actly', 'org': 'org', 'org_unit': 'orgUnit', 'revocation_rea‐
675 son': 'revocationReason', 'revoked_by': 'revokedBy',
676 'revoked_on_from': 'revokedOnFrom', 'revoked_on_to': 'revoke‐
677 dOnTo', 'serial_from': 'serialFrom', 'serial_to': 'serialTo',
678 'state': 'state', 'status': 'status', 'user_id': 'userID',
679 'valid_not_after_from': 'validNotAfterFrom',
680 'valid_not_after_to': 'validNotAfterTo',
681 'valid_not_before_from': 'validNotBeforeFrom',
682 'valid_not_before_to': 'validNotBeforeTo', 'validity_count':
683 'validityCount', 'validity_operation': 'validityOperation',
684 'validity_unit': 'validityUnit'}
685 pki.cert.main()
687 client Module
689 class pki.client.PKIConnection(protocol='http', hostname='localhost',
690 port='8080', subsystem='ca', accept='application/json', trust_env=None)
691 Bases: object
692 Class to encapsulate the connection between the client and a
694 Dogtag subsystem.
695 authenticate(username=None, password=None)
697 Set the parameters used for authentication if user‐
698 name/password is to be used. Both username and password
699 must not be None. Note that this method only sets the
700 parameters. Actual authentication occurs when the con‐
701 nection is attempted,
702 Parameters
704 · username -- username to authenticate connection
706 · password -- password to authenticate connection
708 Returns
710 None
711 delete(path, headers=None, use_root_uri=False)
713 Uses python-requests to issue a DEL request to the
714 server.
715 Parameters
717 · path (str) -- path URI for the DEL request
719 · headers (dict) -- headers for the DEL request
721 · use_root_uri (boolean) -- use root URI instead
723 of subsystem URI as base
724 Returns
726 request.response -- response from the server
727 Raises Exception from python-requests in case the DEL was
729 not successful, or returns an error code.
730 get(path, headers=None, params=None, payload=None,
732 use_root_uri=False, timeout=None)
733 Uses python-requests to issue a GET request to the
734 server.
735 Parameters
737 · path (str) -- path URI for the GET request
739 · headers (dict) -- headers for the GET request
741 · params (dict or bytes) -- Query parameters for
743 the GET request
744 · payload (dict, bytes, file-like object) -- data
746 to be sent in the body of the request
747 · use_root_uri (boolean) -- use root URI instead
749 of subsystem URI as base
750 Returns
752 request.response -- response from the server
753 Raises Exception from python-requests in case the GET was
755 not successful, or returns an error code.
756 post(path, payload, headers=None, params=None,
758 use_root_uri=False)
759 Uses python-requests to issue a POST request to the
760 server.
761 Parameters
763 · path (str) -- path URI for the POST request
765 · payload (dict, bytes, file-like object) -- data
767 to be sent in the body of the request
768 · headers (dict) -- headers for the POST request
770 · params (dict or bytes) -- Query parameters for
772 the POST request
773 · use_root_uri (boolean) -- use root URI instead
775 of subsystem URI as base
776 Returns
778 request.response -- response from the server
779 Raises Exception from python-requests in case the POST
781 was not successful, or returns an error code.
782 put(path, payload, headers=None, use_root_uri=False)
784 Uses python-requests to issue a PUT request to the
785 server.
786 Parameters
788 · path (str) -- path URI for the PUT request
790 · payload (dict, bytes, file-like object) -- data
792 to be sent in the body of the request
793 · headers (dict) -- headers for the PUT request
795 · use_root_uri (boolean) -- use root URI instead
797 of subsystem URI as base
798 Returns
800 request.response -- response from the server
801 Raises Exception from python-requests in case the PUT was
803 not successful, or returns an error code.
804 set_authentication_cert(pem_cert_path, pem_key_path=None)
806 Set the path to the PEM file containing the certificate
807 and private key for the client certificate to be used for
808 authentication to the server, when client certificate
809 authentication is required. The private key may option‐
810 ally be stored in a different path.
811 Parameters
813 · pem_cert_path (str) -- path to the PEM file
815 · pem_key_path (str) -- path to the PEM-formatted
817 private key file
818 Returns
820 None
821 Raises Exception if path is empty or None.
823 pki.client.catch_insecure_warning(func)
825 Temporary silence InsecureRequestWarning
826 PKIConnection is not able to verify HTTPS connections yet. This
828 decorator catches the warning.
829 See https://fedorahosted.org/pki/ticket/1253
831 pki.client.main()
833 Test code for the PKIConnection class. :return: None
834 crypto Module
836 Module containing crypto classes.
837 class pki.crypto.CryptoProvider
839 Bases: object
840 Abstract class containing methods to do cryptographic opera‐
842 tions.
843 asymmetric_wrap(data, wrapping_cert, mechanism=None)
845 encrypt a symmetric key with the public key of a trans‐
846 port cert.
847 The mechanism is the type of symmetric key, which
849 defaults to a 56 bit DES3 key.
850 generate_nonce_iv(mechanism)
852 Create a random initialization vector
853 generate_session_key()
855 Generate a session key to be used for wrapping data to
856 the DRM This must return a 3DES 168 bit key
857 generate_symmetric_key(mechanism=None, size=0)
859 Generate and return a symmetric key
860 get_cert(cert_nick)
862 Get the certificate for the specified cert_nick.
863 get_supported_algorithm_keyset()
865 returns highest supported algorithm keyset
866 initialize()
868 Initialization code
869 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
871 Unwrap data that has been key wrapped using AES KeyWrap
872 set_algorithm_keyset(level)
874 sets required keyset
875 symmetric_unwrap(data, wrapping_key, mechanism=None,
877 nonce_iv=None)
878 decrypt data originally encrypted with symmetric key
879 (wrapping key)
880 We expect the data and nonce_iv values to be base64
882 encoded. The mechanism is the type of key used to do the
883 wrapping. It defaults to a 56 bit DES3 key.
884 symmetric_wrap(data, wrapping_key, mechanism=None,
886 nonce_iv=None)
887 encrypt data using a symmetric key (wrapping key)
888 class pki.crypto.CryptographyCryptoProvider(transport_cert_nick, trans‐
890 port_cert, backend=<cryptography.hazmat.backends.openssl.backend.Back‐
891 end object>)
892 Bases: pki.crypto.CryptoProvider
893 Class that defines python-cryptography implementation of Crypto‐
895 Provider. Requires a PEM file containing the agent cert to be
896 initialized.
897 Note that all inputs and outputs are unencoded.
899 asymmetric_wrap(data, wrapping_cert, mechanism=None)
901 :param data Data to be wrapped :param wrap‐
902 ping_cert Public key to wrap data :param mechanism
903 algorithm of symmetric key to be wrapped
904 Wrap (encrypt) data using the supplied asymmetric key
906 generate_nonce_iv(mechanism='AES')
908 Create a random initialization vector
909 generate_session_key()
911 Returns a session key to be used when wrapping secrets
912 for the DRM.
913 generate_symmetric_key(mechanism=None, size=0)
915 Returns a symmetric key.
916 get_cert(cert_nick)
918 :param cert_nick Nickname for the certificate to be
919 returned.
920 get_supported_algorithm_keyset()
922 returns highest supported algorithm keyset
923 initialize()
925 Any operations here that need to be performed before
926 crypto operations.
927 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
929 :param mechanism key wrapping mechanism :param
930 data: data to unwrap :param wrapping_key:
931 AES key used to wrap data :param nonce_iv Nonce
932 data :return: unwrapped data
933 Unwrap the encrypted data which has been wrapped using a
935 KeyWrap mechanism.
936 set_algorithm_keyset(level)
938 sets required keyset
939 symmetric_unwrap(data, wrapping_key, mechanism=None,
941 nonce_iv=None)
942 :param data Data to be unwrapped :param wrap‐
943 ping_key Symmetric key to unwrap data :param mechanism
944 Mechanism to use when unwrapping :param nonce_iv
945 iv data
946 Unwrap (decrypt) data using the supplied symmetric key
948 symmetric_wrap(data, wrapping_key, mechanism=None,
950 nonce_iv=None)
951 :param data Data to be wrapped :param wrap‐
952 ping_key Symmetric key to wrap data :param mechanism
953 Mechanism to use for wrapping key :param nonce_iv
954 Nonce for initialization vector
955 Wrap (encrypt) data using the supplied symmetric key
957 class pki.crypto.NSSCryptoProvider(certdb_dir, certdb_password=None,
959 password_file=None)
960 Bases: pki.crypto.CryptoProvider
961 Class that defines NSS implementation of CryptoProvider.
963 Requires an NSS database to have been set up and initialized.
964 Note that all inputs and outputs are unencoded.
966 asymmetric_wrap(data, wrapping_cert, mechanism=310)
968 :param data Data to be wrapped :param wrap‐
969 ping_cert Public key to wrap data :param mechanism
970 algorithm of symmetric key to be wrapped
971 Wrap (encrypt) data using the supplied asymmetric key
973 generate_nonce_iv(mechanism=310)
975 Create a random initialization vector
976 generate_session_key()
978 Returns a session key to be used when wrapping secrets
979 for the DRM This will return a 168 bit 3DES key.
980 generate_symmetric_key(mechanism=310, size=0)
982 Returns a symmetric key.
983 Note that for fixed length keys, this length should be 0.
985 If no length is provided, then the function will either
986 use 0 (for fixed length keys) or the maximum available
987 length for that algorithm and the token.
988 get_cert(cert_nick)
990 :param cert_nick Nickname for the certificate to be
991 returned
992 Searches NSS database and returns SecItem object for this
994 certificate.
995 get_supported_algorithm_keyset()
997 returns highest supported algorithm keyset
998 import_cert(cert_nick, cert, trust=', ')
1000 Import a certificate into the nss database
1001 initialize()
1003 Initialize the nss db. Must be done before any crypto
1004 operations
1005 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
1007 :param mechanism Key wrapping mechanism :param
1008 data: Data to be unwrapped :param wrap‐
1009 ping_key: Wrapping Key :param nonce_iv Nonce
1010 data :return: Unwrapped data
1011 Return unwrapped data for data that has been keywrapped.
1013 For NSS, we only support 3DES - so something that has
1014 been keywrapped can be decrypted. This is precisely what
1015 we used to do before.
1016 set_algorithm_keyset(level)
1018 sets required keyset
1019 classmethod setup_contexts(mechanism, sym_key, nonce_iv)
1021 Set up contexts to do wrapping/unwrapping by symmetric
1022 keys.
1023 static setup_database(db_dir, password=None, over_write=False,
1025 password_file=None)
1026 Create an NSS database
1027 symmetric_unwrap(data, wrapping_key, mechanism=310,
1029 nonce_iv=None)
1030 :param data Data to be unwrapped :param wrap‐
1031 ping_key Symmetric key to unwrap data :param mechanism
1032 Mechanism to use when wrapping :param nonce_iv iv
1033 data
1034 Unwrap (decrypt) data using the supplied symmetric key
1036 symmetric_wrap(data, wrapping_key, mechanism=310, nonce_iv=None)
1038 :param data Data to be wrapped :param wrap‐
1039 ping_key Symmetric key to wrap data :param mechanism
1040 Mechanism to user when wrapping :param nonce_iv
1041 Nonce to use when wrapping
1042 Wrap (encrypt) data using the supplied symmetric key
1044 encoder Module
1046 pki.encoder.CustomTypeDecoder(dct)
1047 class pki.encoder.CustomTypeEncoder(*, skipkeys=False,
1049 ensure_ascii=True, check_circular=True, allow_nan=True,
1050 sort_keys=False, indent=None, separators=None, default=None)
1051 Bases: json.encoder.JSONEncoder
1052 A custom JSONEncoder class that knows how to encode core custom
1054 objects.
1055 Custom objects are encoded as JSON object literals (ie, dicts)
1057 with one key, 'TypeName' where 'TypeName' is the actual name of
1058 the type to which the object belongs. That single key maps to
1059 another object literal which is just the __dict__ of the object
1060 encoded.
1061 Reason for ignoring the error: E0202 - An attribute affected in
1063 json.encoder line 157 hide this method reported by pylint:
1064 The error is in json.encoder.JSONEncoder class. There is a
1066 default method (which is overridden here) and also a class
1067 attribute self.default initialized in the init method of the
1068 class. The intention of such usage being that a custom default
1069 method object can be passed to init when creating an instance of
1070 JSONEncoder, which is then assigned to class's default method.
1071 (which is valid) But pylint raises an issue due to the usage of
1072 same name for a method and an attribute in which case the
1073 attribute definition hides the method. The reason and example
1074 for the issue: (top rated comment)
1075 http://stackoverflow.com/questions/12949064/python-what-happens-
1076 when-instance-variable-name-is-same-as-method-name
1077 static attr_name_conversion(attr_dict, object_class)
1079 default(o)
1081 Implement this method in a subclass such that it returns
1082 a serializable object for o, or calls the base implemen‐
1083 tation (to raise a TypeError).
1084 For example, to support arbitrary iterators, you could
1086 implement default like this:
1087 def default(self, o):
1089 try:
1090 iterable = iter(o)
1091 except TypeError:
1092 pass
1093 else:
1094 return list(iterable)
1095 # Let the base class default method raise the TypeError
1096 return JSONEncoder.default(self, o)
1097 pki.encoder.decode_cert(data)
1099 base64 decode X.509 certificate
1100 Parameters
1102 data (str, bytes) -- data as bytes or ASCII text
1103 Return type
1105 bytes
1106 pki.encoder.encode_cert(data)
1108 base64 encode X.509 certificate
1109 Python 3's base64.b64encode() doesn't support ASCII text.
1111 Parameters
1113 data (str, bytes) -- data as bytes or ASCII text
1114 Return type
1116 bytes
1117 key Module
1119 Module containing the Python client classes for the KeyClient and
1120 KeyRequestClient REST API on a DRM
1121 class pki.key.AsymKeyGenerationRequest(client_key_id=None,
1123 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1124 sion_key=None, realm=None)
1125 Bases: pki.ResourceMessage
1126 Class representing the data sent to the DRM when generating and
1128 archiving asymmetric keys in the DRM.
1129 DECRYPT_USAGE = 'decrypt'
1131 DERIVE_USAGE = 'derive'
1133 ENCRYPT_USAGE = 'encrypt'
1135 SIGN_RECOVER_USAGE = 'sign_recover'
1137 SIGN_USAGE = 'sign'
1139 UNWRAP_USAGE = 'unwrap'
1141 VERIFY_RECOVER_USAGE = 'verify_recover'
1143 VERIFY_USAGE = 'verify'
1145 WRAP_USAGE = 'wrap'
1147 class pki.key.Key(key_data)
1149 Bases: object
1150 An instance of this class stores the decoded encrypted secret
1152 present in the KeyData object passed in the constructor. All
1153 the key retrieval requests return this object.
1154 class pki.key.KeyArchivalRequest(client_key_id=None, data_type=None,
1156 wrapped_private_data=None, trans_wrapped_session_key=None, pki_ar‐
1157 chive_options=None, algorithm_oid=None, symkey_params=None, key_algo‐
1158 rithm=None, key_size=None, realm=None)
1159 Bases: pki.ResourceMessage
1160 Class representing the object sent to the DRM when archiving a
1162 secret.
1163 class pki.key.KeyClient(connection, crypto, transport_cert_nick=None,
1165 info_client=None)
1166 Bases: object
1167 Class that encapsulates and mirrors the functions in the KeyRe‐
1169 source and KeyRequestResource Java classes in the DRM REST API.
1170 AES_ALGORITHM = 'AES'
1172 ASYMMETRIC_KEY_TYPE = 'asymmetricKey'
1174 DES3_ALGORITHM = 'DES3'
1176 DESEDE_ALGORITHM = 'DESede'
1178 DES_ALGORITHM = 'DES'
1180 DSA_ALGORITHM = 'DSA'
1182 KEY_STATUS_ACTIVE = 'active'
1184 KEY_STATUS_INACTIVE = 'inactive'
1186 PASS_PHRASE_TYPE = 'passPhrase'
1188 RC2_ALGORITHM = 'RC2'
1190 RC4_ALGORITHM = 'RC4'
1192 RSA_ALGORITHM = 'RSA'
1194 SYMMETRIC_KEY_TYPE = 'symmetricKey'
1196 approve_request(request_id)
1198 Approve a secret recovery request
1199 archive_encrypted_data(client_key_id, data_type, encrypted_data,
1201 wrapped_session_key, algorithm_oid=None, nonce_iv=None,
1202 key_algorithm=None, key_size=None, realm=None)
1203 Archive a secret (symmetric key or passphrase) on the
1204 DRM.
1205 Refer to archive_key() comments for a description of
1207 client_key_id, data_type, key_algorithm and key_size.
1208 The following parameters are also required:
1210 · encrypted_data - which is the data encrypted by
1212 a session key (168 bit 3DES symmetric key)
1213 · wrapped_session_key - the above session key
1215 wrapped by the DRM transport certificate public
1216 key.
1217 · the algorithm_oid string for the symmetric key
1219 wrap
1220 · the nonce_iv for the symmetric key wrap
1222 This function is useful if the caller wants to do their
1224 own wrapping of the secret, or if the secret was gener‐
1225 ated on a separate client machine and the wrapping was
1226 done there.
1227 The function returns a KeyRequestResponse object contain‐
1229 ing a KeyRequestInfo object with details about the
1230 archival request and key archived.
1231 archive_key(client_key_id, data_type, private_data, key_algo‐
1233 rithm=None, key_size=None, realm=None)
1234 Archive a secret (symmetric key or passphrase) on the
1235 DRM.
1236 Requires a user-supplied client ID. There can be only
1238 one active key with a specified client ID. If a record
1239 for a duplicate active key exists, a BadRequestException
1240 is thrown.
1241 data_type can be one of the following:
1243 KeyClient.SYMMETRIC_KEY_TYPE, KeyClient.ASYMMET‐
1244 RIC_KEY_TYPE, KeyClient.PASS_PHRASE_TYPE
1245 key_algorithm and key_size are applicable to symmetric
1247 keys only. If a symmetric key is being archived, these
1248 parameters are required.
1249 private_data is the raw secret to be archived. It will
1251 be wrapped and sent to the DRM.
1252 The function returns a KeyRequestResponse object contain‐
1254 ing a KeyRequestInfo object with details about the
1255 archival request and key archived.
1256 archive_pki_options(client_key_id, data_type, pki_ar‐
1258 chive_options, key_algorithm=None, key_size=None, realm=None)
1259 Archive a secret (symmetric key or passphrase) on the
1260 DRM.
1261 Refer to archive_key() comments for a description of
1263 client_key_id, data_type, key_algorithm and key_size.
1264 pki_archive_options is the data to be archived wrapped in
1266 a PKIArchiveOptions structure,
1267 The function returns a KeyRequestResponse object contain‐
1269 ing a KeyRequestInfo object with details about the
1270 archival request and key archived.
1271 cancel_request(request_id)
1273 Cancel a secret recovery request
1274 generate_asymmetric_key(client_key_id, algorithm=None,
1276 key_size=None, usages=None, trans_wrapped_session_key=None,
1277 realm=None)
1278 Generate and archive asymmetric keys in the DRM. Sup‐
1279 ports algorithms RSA and DSA. Valid key size for RSA =
1280 256 + (16 * n), where n: 0-496 Valid key size for DSA =
1281 512, 768, 1024. p,q,g params are not supported.
1282 Return a KeyRequestResponse which contains a KeyRe‐
1284 questInfo object that describes the URL for the request
1285 and generated keys.
1286 generate_symmetric_key(client_key_id, algorithm=None, size=None,
1288 usages=None, trans_wrapped_session_key=None, realm=None)
1289 Generate and archive a symmetric key on the DRM.
1290 Return a KeyRequestResponse which contains a KeyRe‐
1292 questInfo object that describes the URL for the request
1293 and generated key.
1294 get_active_key_info(client_key_id)
1296 Get the info in the KeyRecord for the active secret in
1297 the DRM.
1298 get_client_keyset()
1300 get_key_info(key_id)
1302 Get the info in the KeyRecord for a specific secret in
1303 the DRM.
1304 get_request_info(request_id)
1306 Return a KeyRequestInfo object for a specific request.
1307 get_server_keyset()
1309 list_keys(client_key_id=None, status=None, max_results=None,
1311 max_time=None, start=None, size=None, realm=None)
1312 List/Search archived secrets in the DRM.
1313 See KRAClient.list_keys for the valid values of status.
1315 Returns a KeyInfoCollection object.
1316 list_requests(request_state=None, request_type=None,
1318 client_key_id=None, start=None, page_size=None,
1319 max_results=None, max_time=None, realm=None)
1320 List/Search key requests in the DRM.
1321 See KRAClient.list_requests for the valid values of
1323 request_state and request_type. Returns a KeyRequestIn‐
1324 foCollection object.
1325 modify_key_status(key_id, status)
1327 Modify the status of a key
1328 process_returned_key(key, session_key)
1330 Decrypt the returned key and place in key.data
1331 The data will either by encrypted using an encryption
1333 algorithm - in which case, the key data will contain an
1334 encryption algorithm OID, or it will be key wrapped - in
1335 which case, the key data will contain a key wrap mecha‐
1336 nism name.
1337 Only one of these should be present. If we are talking
1339 to an older server, and none is present, we will assume
1340 encryption.
1341 recover_key(key_id, request_id=None, ses‐
1343 sion_wrapped_passphrase=None, trans_wrapped_session_key=None,
1344 b64certificate=None, nonce_data=None)
1345 Create a request to recover a secret.
1346 To retrieve a symmetric key or passphrase, the only
1348 parameter that is required is the keyId. It is possible
1349 (but not required) to pass in the session keys/passphrase
1350 and nonceData for the retrieval at this time. Those
1351 parameters are documented in the docstring for
1352 retrieve_key below.
1353 To retrieve an asymmetric key, the keyId and the the
1355 base-64 encoded certificate is required.
1356 reject_request(request_id)
1358 Reject a secret recovery request.
1359 retrieve_key(key_id=None, trans_wrapped_session_key=None,
1361 request_id=None)
1362 Retrieve a secret (passphrase or symmetric key) from the
1363 DRM.
1364 This method will retrieve a key from the KRA given the
1366 key_id or request_id (one of which must be specified).
1367 The data is returned as a KeyData object (which is recast
1368 to a Key object).
1369 If request_id is specified, then the value of key_id is
1371 ignored. Exceptions will be thrown if the caller is not
1372 the originator of the request, or the request is not
1373 approved.
1374 If key_id is specified instead, the following behavior
1376 applies:
1377 · If the key can be retrieved synchronously - ie. only
1379 one agent's approval is required, then the KeyData will
1380 include the secret.
1381 · If the key cannot be retrieved synchronously - ie. if
1383 more than one approval is needed, then the KeyData
1384 object will include the request ID for a recovery
1385 request that was created on the server. When that
1386 request is approved, callers can retrieve the key using
1387 retrieve_key() and setting the request_id.
1388 To ensure data security in transit, the data will be
1390 returned encrypted by a session key (168 bit 3DES symmet‐
1391 ric key) - which is first wrapped (encrypted) by the pub‐
1392 lic key of the DRM transport certificate before being
1393 sent to the DRM. The parameter trans_wrapped_session_key
1394 refers to this wrapped session key.
1395 If the trans_wrapped_session_key is not provided by call‐
1397 er, the method will call CryptoProvider methods to gener‐
1398 ate and wrap the session key. The function will return
1399 the KeyData object with a private_data attribute which
1400 stores the unwrapped key information.
1401 If the trans_wrapped_session_key is provided by the call‐
1403 er, the method will simply pass the data to the KRA, and
1404 will return the secret wrapped in the session key. The
1405 secret will still need to be unwrapped by the caller.
1406 The function will return the KeyData object, where the
1407 KeyData structure includes the wrapped secret and some
1408 nonce data to be used as a salt when unwrapping.
1409 retrieve_key_by_passphrase(key_id=None, request_id=None,
1411 passphrase=None, trans_wrapped_session_key=None, ses‐
1412 sion_wrapped_passphrase=None, nonce_data=None)
1413 Retrieve a secret (passphrase or symmetric key) from the
1414 DRM using a passphrase.
1415 This function generates a key recovery request, approves
1417 it, and retrieves the secret referred to by key_id. This
1418 assumes that only one approval is required to authorize
1419 the recovery.
1420 The secret is secured in transit by wrapping the secret
1422 with a passphrase using PBE encryption.
1423 There are two ways of using this function:
1425 1. A passphrase is provided by the caller.
1427 In this case, CryptoProvider methods will be called to
1429 create the data to securely send the passphrase to the
1430 DRM. Basically, three pieces of data will be sent:
1431 · the passphrase wrapped by a 168 bit 3DES symmetric
1433 key (the session key). This is referred to as the
1434 parameter session_wrapped_passphrase.
1435 · the session key wrapped with the public key in the
1437 DRM transport certificate. This is referred to as
1438 the trans_wrapped_session_key.
1439 · ivps nonce data, referred to as nonce_data
1441 The function will return the tuple (KeyData,
1443 unwrapped_secret)
1444 2. The caller provides the trans_wrapped_session_key,
1446 session_wrapped_passphrase and nonce_data.
1447 In this case, the data will simply be passed to the
1449 DRM. The function will return the secret encrypted by
1450 the passphrase using PBE Encryption. The secret will
1451 still need to be decrypted by the caller.
1452 The function will return the tuple (KeyData, None)
1454 retrieve_key_by_pkcs12(key_id, certificate, passphrase)
1456 Retrieve an asymmetric private key and return it as
1457 PKCS12 data.
1458 This function generates a key recovery request, approves
1460 it, and retrieves the secret referred to by key_id in a
1461 PKCS12 file. This assumes that only one approval is
1462 required to authorize the recovery.
1463 This function requires the following parameters: - key_id
1465 : the ID of the key - certificate: the certificate asso‐
1466 ciated with the private key - passphrase: A passphrase
1467 for the pkcs12 file.
1468 The function returns a KeyData object.
1470 retrieve_key_data(data)
1472 Retrieve a secret from the DRM.
1473 @param: data - a KeyRecoveryRequest containing the keyId
1475 of the secret being retrieved, the request_id of the
1476 approved recovery request and a wrapping mechanism. More
1477 details at KRAClient.retrieve_key.
1478 Returns a KeyData object containing the wrapped secret.
1480 set_crypto_algorithms()
1482 set_transport_cert(transport_cert_nick)
1484 Set the transport certificate for crypto operations
1485 submit_request(request)
1487 Submit an archival, recovery or key generation request to
1488 the DRM.
1489 @param request - is either a KeyArchivalRequest, KeyRe‐
1491 coverRequest, SymKeyGenerationRequest or AsymKeyGenera‐
1492 tionRequest.
1493 returns a KeyRequestResponse object.
1495 class pki.key.KeyData
1497 Bases: object
1498 This is the object that contains the encoded wrapped secret when
1500 that secret is retrieved. It is used by the DRM to send informa‐
1501 tion of the key in the key retrieval requests.
1502 classmethod from_json(attr_list)
1504 Return a KeyData object from a JSON dict
1505 json_attribute_names = {'encryptAlgorithmOID': 'encrypt_algo‐
1507 rithm_oid', 'nonceData': 'nonce_data', 'publicKey': 'pub‐
1508 lic_key', 'requestID': 'request_id', 'wrapAlgorithm':
1509 'wrap_algorithm', 'wrappedPrivateData': 'wrapped_private_data'}
1510 class pki.key.KeyInfo
1512 Bases: object
1513 This is the object that contains information stored in the data‐
1515 base record for an archived secret. It does not contain the
1516 secret itself.
1517 classmethod from_json(attr_list)
1519 Return KeyInfo from JSON dict
1520 get_key_id()
1522 Return the key ID as parsed from key URL
1523 json_attribute_names = {'clientKeyID': 'client_key_id',
1525 'keyURL': 'key_url', 'ownerName': 'owner_name', 'publicKey':
1526 'public_key'}
1527 class pki.key.KeyInfoCollection
1529 Bases: object
1530 This class represents data returned when searching the DRM
1532 archived secrets. Essentially, its a list of KeyInfo objects.
1533 classmethod from_json(json_value)
1535 Return a KeyInfoCollection object from its JSON represen‐
1536 tation
1537 class pki.key.KeyRecoveryRequest(key_id=None, request_id=None,
1539 trans_wrapped_session_key=None, session_wrapped_passphrase=None,
1540 nonce_data=None, certificate=None, passphrase=None, payload_wrap‐
1541 ping_name=None, payload_encryption_oid=None)
1542 Bases: pki.ResourceMessage
1543 Class representing the data sent to the DRM when either creating
1545 a request for the recovery of a secret, or, once the request is
1546 approved, retrieving the secret.
1547 class pki.key.KeyRequestInfo
1549 Bases: object
1550 This class represents data about key requests (archival, recov‐
1552 ery, key generation etc.) in the DRM.
1553 classmethod from_json(attr_list)
1555 Return a KeyRequestInfo object from a JSON dict.
1556 get_key_id()
1558 Return the ID of the secret referred to by this request.
1559 get_request_id()
1561 Return the request ID by parsing the request URL.
1562 json_attribute_names = {'keyURL': 'key_url', 'requestStatus':
1564 'request_status', 'requestType': 'request_type', 'requestURL':
1565 'request_url'}
1566 class pki.key.KeyRequestInfoCollection
1568 Bases: object
1569 This class represents the data returned when searching the key
1571 requests in the DRM. Essentially, its a list of KeyRequestInfo
1572 objects.
1573 classmethod from_json(json_value)
1575 Return a KeyRequestInfoCollection object from its JSON
1576 representation.
1577 class pki.key.KeyRequestResponse
1579 Bases: object
1580 This class is returned when an archival, recovery or key genera‐
1582 tion request is created. It includes a KeyRequestInfo object
1583 with information about the created request, and a KeyData struc‐
1584 ture which contains the wrapped secret (if that operation is
1585 supported).
1586 classmethod from_json(json_value)
1588 Return a KeyRequestResponse object from its JSON repre‐
1589 sentation.
1590 get_key_id()
1592 Return the id for the key archived, recovered or gener‐
1593 ated
1594 get_request_id()
1596 Return the id for the created request
1597 class pki.key.RequestId(req_id)
1599 Bases: object
1600 Class representing a Request ID
1602 class pki.key.SymKeyGenerationRequest(client_key_id=None,
1604 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1605 sion_key=None, realm=None)
1606 Bases: pki.ResourceMessage
1607 Class representing the data sent to the DRM when generating and
1609 archiving a symmetric key in the DRM.
1610 DECRYPT_USAGE = 'decrypt'
1612 ENCRYPT_USAGE = 'encrypt'
1614 SIGN_USAGE = 'sign'
1616 UNWRAP_USAGE = 'unwrap'
1618 VERIFY_USAGE = 'verify'
1620 WRAP_USAGE = 'wrap'
1622 pki.key.main()
1624 Some unit tests - basically printing different types of requests
1625 kra Module
1627 Module containing KRAClient class. This class should be used by Python
1628 clients to interact with the DRM to expose the functionality of the
1629 KeyClient and KeyRequestResource REST APIs.
1630 class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
1632 Bases: object
1633 Client class that models interactions with a KRA using the Key
1635 and KeyRequest REST APIs.
1636 profile Module
1638 class pki.profile.Descriptor(syntax=None, constraint=None, descrip‐
1639 tion=None, default_value=None)
1640 Bases: object
1641 This class represents the description of a ProfileAttribute. It
1643 stores information such as the syntax, constraint and default
1644 value of a profile attribute.
1645 classmethod from_json(attr_list)
1647 json_attribute_names = {'Constraint': 'constraint', 'Default‐
1649 Value': 'default_value', 'Description': 'description', 'Syntax':
1650 'syntax'}
1651 class pki.profile.PolicyConstraint(name=None, description=None,
1653 class_id=None, policy_constraint_values=None)
1654 Bases: object
1655 An object of this class contains the policy constraints applied
1657 to a ProfileInput used by a certificate enrollment request.
1658 add_constraint_value(policy_constraint_value)
1660 Add a PolicyConstraintValue to the policy_constraint_val‐
1661 ues list.
1662 classmethod from_json(attr_list)
1664 get_constraint_value(policy_constraint_value_name)
1666 Returns a PolicyConstraintValue object with the given
1667 name. None, if there is no match.
1668 json_attribute_names = {'classId': 'class_id', 'constraint':
1670 'policy_constraint_values', 'id': 'name'}
1671 remove_constraint_value(policy_constraint_value_name)
1673 Removes a PolicyConstraintValue with the given name form
1674 the policy_constraint_values list.
1675 class pki.profile.PolicyConstraintValue(name=None, value=None, descrip‐
1677 tor=None)
1678 Bases: object
1679 Represents a PolicyConstraintValue
1681 classmethod from_json(attr_list)
1683 name
1685 class pki.profile.PolicyDefault(name=None, class_id=None, descrip‐
1687 tion=None, policy_attributes=None, policy_params=None)
1688 Bases: object
1689 An object of this class contains information of the default
1691 usage of a specific ProfileInput.
1692 add_attribute(policy_attribute)
1694 Add a policy attribute to the attribute list. @param
1695 policy_attribute - A ProfileAttribute object
1696 add_parameter(policy_parameter)
1698 Add a profile parameter to the parameters list. @param
1699 policy_parameter - A ProfileParameter object.
1700 classmethod from_json(attr_list)
1702 get_attribute(policy_attribute_name)
1704 Fetch the policy attribute with the given name from the
1705 attributes list.
1706 get_parameter(profile_parameter_name)
1708 Fetch a profile parameter with the given name from the
1709 parameters list.
1710 json_attribute_names = {'classId': 'class_id', 'id': 'name',
1712 'params': 'policy_params', 'policyAttribute': 'pol‐
1713 icy_attributes'}
1714 remove_attribute(policy_attribute_name)
1716 Remove a policy attribute with the given name from the
1717 attributes list.
1718 remove_parameter(profile_parameter_name)
1720 Remove a profile parameter with the given name from the
1721 parameters list.
1722 class pki.profile.PolicySet(name=None, policy_list=None)
1724 Bases: object
1725 An object of this class contains a name value pair of the policy
1727 name and the ProfilePolicy object.
1728 add_policy(profile_policy)
1730 Add a ProfilePolicy object to the policy_list
1731 classmethod from_json(attr_list)
1733 get_policy(policy_id)
1735 Returns a ProfilePolicy object with the given profile id.
1736 json_attribute_names = {'id': 'name', 'value': 'policy_list'}
1738 remove_policy(policy_id)
1740 Removes a ProfilePolicy with the given ID from the Poli‐
1741 cySet.
1742 class pki.profile.PolicySetList(policy_sets=None)
1744 Bases: object
1745 An object of this class stores a list of ProfileSet objects.
1747 add_policy_set(policy_set)
1749 Add a PolicySet object to the policy_sets list.
1750 classmethod from_json(attr_list)
1752 get_policy_set(policy_set_name)
1754 Fetch the PolicySet object for the given name. Returns
1755 None, if not found.
1756 policy_sets
1758 remove_policy_set(policy_set_name)
1760 Remove a PolicySet object with the given name from the
1761 policy_sets list.
1762 class pki.profile.Profile(profile_id=None, class_id=None, name=None,
1764 description=None, enabled=None, visible=None, enabled_by=None, authen‐
1765 ticator_id=None, authorization_acl=None, renewal=None, xml_output=None,
1766 inputs=None, outputs=None, policy_set_list=None, link=None)
1767 Bases: object
1768 This class represents an enrollment profile.
1770 add_input(profile_input)
1772 Add a ProfileInput object to the inputs list of the Pro‐
1773 file.
1774 add_output(profile_output)
1776 Add a ProfileOutput object to the outputs list of the
1777 Profile.
1778 add_policy_set(policy_set)
1780 Add a PolicySet object to the policy_sets list of the
1781 Profile.
1782 classmethod from_json(attr_list)
1784 get_input(profile_input_id)
1786 Fetches a ProfileInput with the given ProfileInput id.
1787 Returns None, if there is no matching input.
1788 get_output(profile_output_id)
1790 Fetches a ProfileOutput with the given ProfileOutput id.
1791 Returns None, if there is no matching output.
1792 get_policy_set(policy_set_name)
1794 Fetches a ProfileInput with the given ProfileInput id.
1795 Returns None, if there is no matching input.
1796 static get_profile_data_from_file(path_to_file)
1798 Reads the file for the serialized Profile object. Cur‐
1799 rently supports only data format in json.
1800 json_attribute_names = {'Input': 'inputs', 'Output': 'outputs',
1802 'PolicySets': 'policy_set_list', 'authenticatorId': 'authentica‐
1803 tor_id', 'authzAcl': 'authorization_acl', 'classId': 'class_id',
1804 'enabledBy': 'enabled_by', 'id': 'profile_id', 'xmlOutput':
1805 'xml_output'}
1806 remove_input(profile_input_id)
1808 Remove a ProfileInput from the inputs list of the Pro‐
1809 file.
1810 remove_output(profile_output_id)
1812 Remove a ProfileOutput from the outputs list of the Pro‐
1813 file.
1814 remove_policy_set(policy_set_name)
1816 Remove a PolicySet from the policy_sets list of the Pro‐
1817 file.
1818 class pki.profile.ProfileAttribute(name=None, value=None, descrip‐
1820 tor=None)
1821 Bases: object
1822 Represents a profile attribute of a ProfileInput.
1824 classmethod from_json(attr_list)
1826 json_attribute_names = {'Descriptor': 'descriptor', 'Value':
1828 'value'}
1829 class pki.profile.ProfileClient(connection)
1831 Bases: object
1832 This class consists of methods for accessing the ProfileRe‐
1834 source.
1835 create_profile(profile_data)
1837 Create a new profile for the given Profile object.
1838 create_profile_from_file(path_to_file)
1840 Reads the file for the serialized Profile object. Per‐
1841 forms the profile create operation. Currently supports
1842 only data format in json.
1843 delete_profile(profile_id)
1845 Delete a profile with the given Profile Id.
1846 disable_profile(profile_id)
1848 Disables a profile.
1849 enable_profile(profile_id)
1851 Enables a profile.
1852 get_profile(profile_id)
1854 Fetches information for the profile for the given profile
1855 id. Returns a ProfileData object.
1856 list_profiles(start=None, size=None)
1858 Fetches the list of profiles. The start and size argu‐
1859 ments provide pagination support. Returns a Profile‐
1860 DataInfoCollection object.
1861 modify_profile(profile_data)
1863 Modify an existing profile with the given Profile object.
1864 modify_profile_from_file(path_to_file)
1866 Reads the file for the serialized Profile object. Per‐
1867 forms the profile modify operation. Currently supports
1868 only data format in json.
1869 class pki.profile.ProfileDataInfo
1871 Bases: object
1872 Stores information about a profile
1874 classmethod from_json(attr_list)
1876 json_attribute_names = {'profileDescription': 'profile_descrip‐
1878 tion', 'profileId': 'profile_id', 'profileName': 'profile_name',
1879 'profileURL': 'profile_url'}
1880 class pki.profile.ProfileDataInfoCollection
1882 Bases: object
1883 Represents a collection of ProfileDataInfo objects. Also encap‐
1885 sulates the links for the list of the objects stored.
1886 classmethod from_json(attr_list)
1888 class pki.profile.ProfileInput(profile_input_id=None, class_id=None,
1890 name=None, text=None, attributes=None, config_attributes=None)
1891 Bases: object
1892 This class encapsulates all the attributes of a profile to gen‐
1894 erate a specific property of a certificate. Ex. Subject name,
1895 Requestor Information etc.
1896 add_attribute(profile_attribute)
1898 Add a ProfileAttribute object to the attributes list.
1899 add_config_attribute(profile_attribute)
1901 Add a ProfileAttribute object to the config_attributes
1902 list.
1903 classmethod from_json(attr_list)
1905 get_attribute(profile_attribute_name)
1907 Returns a ProfileAttribute object for the given name.
1908 None, if no match.
1909 get_config_attribute(config_attribute_name)
1911 Returns a ProfileAttribute object with the given name.
1912 None, if there is no match in the config_attributes list.
1913 json_attribute_names = {'Attribute': 'attributes', 'ClassID':
1915 'class_id', 'ConfigAttribute': 'config_attributes', 'Name':
1916 'name', 'Text': 'text', 'id': 'profile_input_id'}
1917 remove_attribute(profile_attribute_name)
1919 Remove a ProfileAttribute object with the given name from
1920 the attributes list.
1921 remove_config_attribute(config_attribute_name)
1923 Remove a ProfileAttribute object with the given name from
1924 the config_attributes list.
1925 class pki.profile.ProfileOutput(profile_output_id=None, name=None,
1927 text=None, class_id=None, attributes=None)
1928 Bases: object
1929 This class defines the output of a certificate enrollment
1931 request using a profile.
1932 add_attribute(profile_attribute)
1934 Add a ProfileAttribute object to the attributes list.
1935 classmethod from_json(attr_list)
1937 get_attribute(profile_attribute_name)
1939 Returns a ProfileAttribute object for the given name.
1940 None, if no match.
1941 json_attribute_names = {'classId': 'class_id', 'id': 'pro‐
1943 file_output_id'}
1944 remove_attribute(profile_attribute_name)
1946 Remove a ProfileAttribute object with the given name from
1947 the attributes list.
1948 class pki.profile.ProfileParameter(name=None, value=None)
1950 Bases: object
1951 classmethod from_json(attr_list)
1953 class pki.profile.ProfilePolicy(policy_id=None, policy_default=None,
1955 policy_constraint=None)
1956 Bases: object
1957 This class represents the policy a profile adheres to. An
1959 object of this class stores the default values for profile and
1960 the constraints present on the values of the attributes of the
1961 profile submitted for an enrollment request.
1962 classmethod from_json(attr_list)
1964 json_attribute_names = {'constraint': 'policy_constraint',
1966 'def': 'policy_default', 'id': 'policy_id'}
1967 class pki.profile.ProfilePolicySet
1969 Bases: object
1970 Stores a list of ProfilePolicy objects.
1972 classmethod from_json(attr_list)
1974 pki.profile.main()
1976 system Module
1978 class pki.system.AdminSetupRequest
1979 Bases: object
1980 class pki.system.AdminSetupResponse
1982 Bases: object
1983 class pki.system.ConfigurationRequest
1985 Bases: object
1986 Class used to represent a configuration request to be submitted
1988 to the Java installation servlet during the execution of
1989 pkispawn.
1990 This class is the python equivalent of the Java class: com.net‐
1992 scape.certsrv.system.ConfigurationRequest
1993 class pki.system.ConfigurationResponse
1995 Bases: object
1996 Class used to represent the response from the Java configuration
1998 servlet during the execution of pkispawn.
1999 This class is the python equivalent of the Java class: com.net‐
2001 scape.certsrv.system.ConfigurationRequest
2002 class pki.system.KeyBackupRequest
2004 Bases: object
2005 class pki.system.SecurityDomainClient(connection)
2007 Bases: object
2008 Client used to get the security domain from a security domain
2010 CA. The connection details for the security domain CA are spec‐
2011 ified in a PKIConnection object used to construct this client.
2012 get_old_security_domain_info()
2014 Contact the security domain CA specified in the connec‐
2015 tion object used to construct this client and get the
2016 security domain using the old servlet-based interface.
2017 This method is useful when contacting old servers which
2018 do not provide the REST API.
2019 Returns
2021 pki.system.SecurityDomainInfo
2022 get_security_domain_info()
2024 Contact the security domain CA specified in the connec‐
2025 tion object used to construct this client and get the
2026 security domain using the REST API.
2027 Returns
2029 pki.system.SecurityDomainInfo
2030 class pki.system.SecurityDomainHost
2032 Bases: object
2033 Class representing a security domain host.
2035 classmethod from_json(json_value)
2037 Constructs a SecurityDomainHost object from JSON.
2038 Parameters
2040 json_value (str) -- JSON string representing a
2041 security domain host.
2042 Returns
2044 SecurityDomainHost
2045 class pki.system.SecurityDomainInfo
2047 Bases: object
2048 Class representing the entire security domain. This is essen‐
2050 tially a list of SecurityDomainSubsystem components.
2051 classmethod from_json(json_value)
2053 Create a SecurityDomainInfo object from JSON.
2054 Parameters
2056 json_value (str) -- JSON representation of a secu‐
2057 rity domain.
2058 Returns
2060 SecurityDomainInfo
2061 class pki.system.SecurityDomainSubsystem
2063 Bases: object
2064 Class representing a security domain subsystem. This is essen‐
2066 tially a list of SecurityDomainHost objects of a particular sub‐
2067 system type (ca, kra, tps, tks, ocsp).
2068 classmethod from_json(json_value)
2070 Constructs a SecurityDomainSubsystem from a JSON repre‐
2071 sentation.
2072 Parameters
2074 json_value (str) -- JSON representation of the
2075 Security Domain Subsystem
2076 Returns
2078 SecurityDomainSubsystem
2079 class pki.system.SystemCertData
2081 Bases: object
2082 Class used to represent the data for a system certificate, which
2084 is used in the data passed into and returned from the Java
2085 installation servlet during the execution of pkispawn.
2086 This class is the python equivalent of the Java class: com.net‐
2088 scape.certsrv.system.SystemCertData
2089 class pki.system.SystemConfigClient(connection)
2091 Bases: object
2092 Client used to interact with the Java configuration servlet to
2094 configure a Dogtag subsystem during the execution of pkispawn.
2095 The connection details for the system being configured are
2097 passed in the PKIConnection object used when constructing this
2098 object.
2099 backupKeys(request)
2101 Backup keys.
2102 Parameters
2104 request (KeyBackupRequest) -- Key backup request
2105 configure(request)
2107 Contacts the server and invokes the Java configuration
2108 REST API to configure a Dogtag subsystem.
2109 Parameters
2111 request (ConfigurationRequest) -- Configuration
2112 request containing all the input needed to config‐
2113 ure the subsystem
2114 Returns
2116 ConfigurationResponse -- response from configura‐
2117 tion servlet.
2118 configureCerts(request)
2120 Configure certificates.
2121 Parameters
2123 request (ConfigurationRequest) -- Configuration
2124 request
2125 Returns
2127 ConfigurationResponse
2128 finalizeConfiguration(request)
2130 Finalize server configuration.
2131 Parameters
2133 request (ConfigurationRequest) -- Configuration
2134 request
2135 setupAdmin(request)
2137 Set up admin.
2138 Parameters
2140 request (AdminSetupRequest) -- Admin setup request
2141 Returns
2143 AdminSetupResponse
2144 setupDatabase(request)
2146 Set up database.
2147 Parameters
2149 request (ConfigurationRequest) -- Configuration
2150 request
2151 setupDatabaseUser(request)
2153 Set up database user.
2154 Parameters
2156 request (ConfigurationRequest) -- Configuration
2157 request
2158 setupSecurityDomain(request)
2160 Setup security domain.
2161 Parameters
2163 request (ConfigurationRequest) -- Configuration
2164 request
2165 class pki.system.SystemStatusClient(connection)
2167 Bases: object
2168 Client used to check the status of a Dogtag subsystem.
2170 get_status(timeout=None)
2172 Checks the status of the subsystem by calling the getSta‐
2173 tus() servlet. This is used to determine if the server
2174 is up and ready to receive and process requests.
2175 Returns
2177 str - getStatus response
2178 systemcert Module
2180 Module containing the Python client classes for the SystemCert REST API
2181 class pki.systemcert.SystemCertClient(connection)
2183 Bases: object
2184 Class encapsulating and mirroring the functionality in the Sys‐
2186 temCertResource Java interface class defining the REST API for
2187 system certificate resources.
2188 get_transport_cert()
2190 Return transport certificate.
2191 Returns
2193 pki.cert.CertData -- transport certificate data
2194 upgrade Module
2196 class pki.upgrade.PKIUpgradeScriptlet
2197 Bases: object
2198 backup(path)
2200 can_upgrade()
2202 get_backup_dir()
2204 init()
2206 revert()
2208 update_tracker()
2210 upgrade()
2212 upgrade_system()
2214 class pki.upgrade.PKIUpgradeTracker(name, filename, delimiter='=', ver‐
2216 sion_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
2217 Bases: object
2218 get_index()
2220 get_version()
2222 remove()
2224 remove_index()
2226 remove_version()
2228 set(version)
2230 set_index(index)
2232 set_version(version)
2234 show()
2236 class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade',
2238 version=None, index=None, silent=False)
2239 Bases: object
2240 all_versions()
2242 get_current_version()
2244 get_target_version()
2246 get_tracker()
2248 is_complete()
2250 remove_tracker()
2252 reset_tracker()
2254 revert()
2256 revert_version(version)
2258 scriptlets(version)
2260 set_tracker(version)
2262 show_tracker()
2264 status()
2266 upgrade()
2268 upgrade_version(version)
2270 version_dir(version)
2272 versions()
2274 util Module
2276 Module containing utility functions and classes for the Dogtag python
2277 code
2278 class pki.util.Version(obj)
2280 Bases: object
2281 pki.util.chmod(path, perms)
2283 Change permissions of a file, link, or folder recursively.
2284 pki.util.chown(path, uid, gid)
2286 Change ownership of a file, link, or folder recursively.
2287 pki.util.copy(source, dest, uid=-1, gid=-1, force=False)
2289 Copy a file or a folder and its contents.
2290 pki.util.copydirs(source, dest, uid=-1, gid=-1, force=False)
2292 Copy a folder and its parents while preserving their attributes.
2293 pki.util.copyfile(source, dest, uid=-1, gid=-1, force=False)
2295 Copy a file or link while preserving its attributes.
2296 pki.util.copytree(src, dst, symlinks=False, ignore=None)
2298 Recursively copy a directory tree using copy2().
2299 PATCH: This code was copied from 'shutil.py' and patched to
2301 allow 'The destination directory to already exist.'
2302 If exception(s) occur, an Error is raised with a list of rea‐
2304 sons.
2305 If the optional symlinks flag is true, symbolic links in the
2307 source tree result in symbolic links in the destination tree; if
2308 it is false, the contents of the files pointed to by symbolic
2309 links are copied.
2310 The optional ignore argument is a callable. If given, it is
2312 called with the src parameter, which is the directory being vis‐
2313 ited by copytree(), and names which is the list of src contents,
2314 as returned by os.listdir():
2315 callable(src, names) -> ignored_names
2316 Since copytree() is called recursively, the callable will be
2318 called once for each directory that is copied. It returns a list
2319 of names relative to the src directory that should not be
2320 copied.
2321 Consider this example code rather than the ultimate tool.
2323 pki.util.customize_file(input_file, output_file, params)
2325 Customize a file with specified parameters.
2326 pki.util.load_properties(filename, properties)
2328 pki.util.makedirs(path, uid=-1, gid=-1, force=False)
2330 pki.util.read_environment_files(env_file_list=None)
2332 pki.util.read_text(message, options=None, default=None, delimiter=':',
2334 allow_empty=True, case_sensitive=True)
2335 Get an input from the user. This is used, for example, in
2336 pkispawn and pkidestroy to obtain user input.
2337 Parameters
2339 · message (str) -- prompt to display to the user
2341 · options (list) -- list of possible inputs by the user.
2343 · default (str) -- default value of parameter being
2345 prompted.
2346 · delimiter (str) -- delimiter to be used at the end of
2348 the prompt.
2349 · allow_empty (boolean -- True/False) -- Allow input to
2351 be empty.
2352 · case_sensitive (boolean -- True/False) -- Allow input
2354 to be case sensitive.
2355 Returns
2357 str -- value obtained from user input.
2358 pki.util.remove(path, force=False)
2360 pki.util.rmtree(path, force=False)
2362 pki.util.store_properties(filename, properties)
2364 pki.util.symlink(source, dest, uid=-1, gid=-1, force=False)
2366 pki.util.unlink(link, force=False)
2368 · genindex
2370 · modindex
2372 · search
2374
2376 Dogtag PKI Project Team
2377
2379 2014, Dogtag PKI Team
2380@APPLICATION_VERSION@ May 07, 2019 PKI-PYTHON-CLIENT(1)