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: exceptions.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.handle_exceptions()
302 Decorator handling exceptions from REST methods.
303 pki.implementation_version()
305 Return implementation version.
306 Returns
308 str --implementation version
309 pki.read_text(message, options=None, default=None, delimiter=':',
311 allow_empty=True, case_sensitive=True)
312 Get an input from the user. This is used, for example, in
313 pkispawn and pkidestroy to obtain user input.
314 Parameters
316 · message (str) -- prompt to display to the user
318 · options (list) -- list of possible inputs by the user.
320 · default (str) -- default value of parameter being
322 prompted.
323 · delimiter (str) -- delimiter to be used at the end of
325 the prompt.
326 · allow_empty (boolean -- True/False) -- Allow input to
328 be empty.
329 · case_sensitive (boolean -- True/False) -- Allow input
331 to be case sensitive.
332 Returns
334 str -- value obtained from user input.
335 account Module
337 class pki.account.AccountClient(connection)
338 Class used to associate an authentication session variable with
339 a connection.
340 To use this class:
342 · set the authentication credentials with the connection,
344 · create an AccountClient and then call login().
346 · further operations in this session will use the same
348 authentication credentials without re-authentication.
349 · call logout() to invalidate the session.
351 login(inst, *args, **kwargs)
353 Login to account REST interface. If login is successful,
354 an authentication session variable is associated with the
355 connection.
356 Returns
358 None
359 logout(inst, *args, **kwargs)
361 Logs out of the session. Authentication session vari‐
362 ables are invalidated for the connection
363 Returns
365 None
366 cert Module
368 class pki.cert.CertClient(connection)
369 Bases: object
370 Class encapsulating and mirroring the functionality in the
372 CertResource Java interface class defining the REST API for Cer‐
373 tificate resources.
374 approve_request(request_id, cert_review_response=None)
376 Approves a certificate enrollment request. If
377 cert_review_response is None, a review request operation
378 is performed to fetch the CertReviewResponse object.
379 Requires as agent level authentication.
380 assign_request(request_id, cert_review_response)
382 Assigns a certificate enrollment request. If
383 cert_review_response is None, a review request operation
384 is performed to fetch the CertReviewResponse object.
385 Requires as agent level authentication.
386 cancel_request(request_id, cert_review_response=None)
388 Cancels a certificate enrollment request. If
389 cert_review_response is None, a review request operation
390 is performed to fetch the CertReviewResponse object.
391 Requires as agent level authentication.
392 create_enrollment_request(inst, *args, **kwargs)
394 Fetches the enrollment request object for the given pro‐
395 file and sets values to its attributes using the values
396 provided in the inputs dictionary. Returns the CertEn‐
397 rollmentRequest object, which can be submitted to enroll
398 a certificate.
399 enroll_cert(inst, *args, **kwargs)
401 A convenience method for enrolling a certificate for a
402 given profile id. The inputs parameter should be a dic‐
403 tionary with values for the profile attributes for an
404 enrollment request.
405 Calling this method with valid arguments, creates an
407 enrollment request, submits it to the server, approves
408 the certificate requests generated for the enrollment and
409 returns a list of CertData objects for all the certifi‐
410 cates generated as part of this enrollment.
411 Note: This method supports only certificate enrollment
413 where only one agent approval is sufficient.
414 Requires an agent level authentication. Returns a list
416 of CertEnrollmentResult objects.
417 get_cert(inst, *args, **kwargs)
419 Return a CertData object for a particular certificate.
420 get_enrollment_template(inst, *args, **kwargs)
422 Fetch the enrollment template for the given profile id.
423 For the first time, the request is sent to the server.
424 The retrieved CertEnrollmentRequest object is then cached
425 locally for future requests. Returns a CerEnrollmentRe‐
426 quest object.
427 get_request(inst, *args, **kwargs)
429 Get information of a certificate request with the given
430 request ID. Returns a CertRequestInfo object.
431 hold_cert(inst, *args, **kwargs)
433 Places a certificate on-hold. Calls the revoke_cert
434 method with reason - CertRevokeRequest.REASON_CERTIFI‐
435 CATE_HOLD. Returns a CertRequestInfo object. This
436 method requires an agent's authentication cert in the
437 connection object.
438 list_certs(inst, *args, **kwargs)
440 Return a CertDataInfoCollection object with a information
441 about all the certificates that satisfy the search crite‐
442 ria. If cert_search_request=None, returns all the cer‐
443 tificates.
444 list_enrollment_templates(inst, *args, **kwargs)
446 Gets the list of profile templates supported by the CA.
447 The values for start and size arguments determine the
448 starting point and the length of the list. Returns a
449 ProfileDataInfoCollection object.
450 list_requests(inst, *args, **kwargs)
452 Query for a list of certificates using the arguments
453 passed. Returns a CertRequestInfoCollection object.
454 reject_request(request_id, cert_review_response=None)
456 Rejects a certificate enrollment request. If
457 cert_review_response is None, a review request operation
458 is performed to fetch the CertReviewResponse object.
459 Requires as agent level authentication.
460 review_cert(inst, *args, **kwargs)
462 Reviews a certificate. Returns a CertData object with a
463 nonce. This method requires an agent's authentication
464 cert in the connection object.
465 review_request(inst, *args, **kwargs)
467 Reviews a certificate enrollment request. Returns a
468 CertReviewResponse object which contains the nonce from
469 the server needed to perform an action on the request.
470 revoke_ca_cert(inst, *args, **kwargs)
472 Revokes a CA certificate. Returns a CertRequestInfo
473 object with information about the request. This method
474 requires an agent's authentication cert in the connection
475 object.
476 revoke_cert(inst, *args, **kwargs)
478 Revokes a certificate. Returns a CertRequestInfo object
479 with information about the request. This method requires
480 an agent's authentication cert in the connection object.
481 submit_enrollment_request(inst, *args, **kwargs)
483 Submits the CertEnrollmentRequest object to the server.
484 Returns a CertRequestInfoCollection object with informa‐
485 tion about the certificate requests enrolled at the CA.
486 unassign_request(request_id, cert_review_response)
488 Un-assigns 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 unrevoke_cert(inst, *args, **kwargs)
494 Un-revokes a revoked certificate. Returns a CertRe‐
495 questInfo object. This method requires an agent's
496 authentication cert in the connection object.
497 update_request(request_id, cert_review_response)
499 Updates 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 validate_request(request_id, cert_review_response)
505 Validates a certificate enrollment request. If
506 cert_review_response is None, a review request operation
507 is performed to fetch the CertReviewResponse object.
508 Requires as agent level authentication.
509 class pki.cert.CertData
511 Bases: object
512 Class containing certificate data as returned from getCert()
514 classmethod from_json(attr_list)
516 Return CertData object from JSON dict
517 json_attribute_names = {'Nonce': 'nonce', 'SubjectDN': 'sub‐
519 ject_dn', 'NotBefore': 'not_before', 'IssuerDN': 'issuer_dn',
520 'NotAfter': 'not_after', 'id': 'serial_number', 'Status': 'sta‐
521 tus', 'PKCS7CertChain': 'pkcs7_cert_chain', 'PrettyPrint':
522 'pretty_repr', 'Link': 'link', 'Encoded': 'encoded'}
523 class pki.cert.CertDataInfo
525 Bases: object
526 Class containing information contained in a CertRecord on the
528 CA. This data is returned when searching/listing certificate
529 records.
530 classmethod from_json(attr_list)
532 Return CertDataInfo object from JSON dict
533 json_attribute_names = {'IssuedOn': 'issued_on', 'SubjectDN':
535 'subject_dn', 'NotValidBefore': 'not_valid_before', 'Version':
536 'version', 'Type': 'type', 'id': 'serial_number', 'Status':
537 'status', 'NotValidAfter': 'not_valid_after', 'IssuedBy':
538 'issued_by', 'KeyLength': 'key_length', 'Link': 'link', 'KeyAl‐
539 gorithmOID': 'key_algorithm_oid'}
540 class pki.cert.CertDataInfoCollection
542 Bases: object
543 Class containing list of CertDataInfo objects and their respec‐
545 tive link objects. This data is returned when searching/listing
546 certificate records in the CA.
547 classmethod from_json(json_value)
549 Populate object from JSON input
550 class pki.cert.CertEnrollmentRequest(profile_id=None, renewal=False,
552 serial_number=None, remote_host=None, remote_address=None, inputs=None,
553 outputs=None)
554 Bases: object
555 This class encapsulates the parameters required for a certifi‐
557 cate
558 enrollment request.
559 add_input(profile_input)
561 add_output(profile_output)
563 classmethod from_json(attr_list)
565 get_input(profile_input_name)
567 get_output(profile_output_name)
569 json_attribute_names = {'RemoteAddress': 'remote_address',
571 'RemoteHost': 'remote_host', 'SerialNumber': 'serial_number',
572 'Output': 'outputs', 'Input': 'inputs', 'Renewal': 'renewal',
573 'ProfileID': 'profile_id'}
574 remove_input(profile_input_name)
576 remove_output(profile_output_name)
578 class pki.cert.CertEnrollmentResult(request, cert)
580 Bases: object
581 Class containing results of an enrollment request.
583 This structure contains information about the cert request gen‐
585 erated and any certificates issued.
586 class pki.cert.CertRequestInfo
588 Bases: object
589 An object of this class stores represents a certificate request.
591 classmethod from_json(attr_list)
593 json_attribute_names = {'certRequestType': 'cert_request_type',
595 'certId': 'cert_id', 'operationResult': 'operation_result',
596 'requestType': 'request_type', 'requestStatus': 'request_sta‐
597 tus', 'errorMessage': 'error_message', 'requestURL':
598 'request_url', 'certURL': 'cert_url'}
599 class pki.cert.CertRequestInfoCollection
601 Bases: object
602 Class containing list of CertRequestInfo objects. This data is
604 returned when listing certificate request records in the CA.
605 classmethod from_json(json_value)
607 Populate object from JSON input
608 class pki.cert.CertRequestStatus
610 Bases: object
611 Class containing valid cert statuses.
613 CANCELED = 'canceled'
615 COMPLETE = 'complete'
617 PENDING = 'pending'
619 REJECTED = 'rejected'
621 class pki.cert.CertReviewResponse(profile_id=None, renewal=False,
623 serial_number=None, remote_host=None, remote_address=None, inputs=None,
624 outputs=None, nonce=None, request_id=None, request_type=None,
625 request_status=None, request_owner=None, request_creation_time=None,
626 request_modification_time=None, request_notes=None, pro‐
627 file_approval_by=None, profile_set_id=None, profile_is_visible=None,
628 profile_name=None, profile_description=None, profile_remote_host=None,
629 profile_remote_address=None, policy_sets=None)
630 Bases: pki.cert.CertEnrollmentRequest
631 An object of this class represent the response from the server
633 when reviewing a certificate enrollment request. It contains a
634 nonce required to perform action on the request.
635 classmethod from_json(attr_list)
637 json_attribute_names = {'ProfilePolicySet': 'policy_sets', 'pro‐
639 fileSetId': 'profile_set_id', 'RemoteAddress': 'remote_address',
640 'requestType': 'request_type', 'RemoteHost': 'remote_host',
641 'SerialNumber': 'serial_number', 'requestCreationTime':
642 'request_creation_time', 'requestOwner': 'request_owner',
643 'Input': 'inputs', 'Output': 'outputs', 'profileIsVisible':
644 'profile_is_visible', 'requestStatus': 'request_status', 'pro‐
645 fileRemoteHost': 'profile_remote_host', 'profileApprovedBy':
646 'profile_approved_by', 'requestNotes': 'request_notes',
647 'Renewal': 'renewal', 'profileDescription': 'profile_descrip‐
648 tion', 'profileRemoteAddr': 'profile_remote_address', 'Pro‐
649 fileID': 'profile_id', 'profileName': 'profile_name', 'request‐
650 ModificationTime': 'request_modification_time', 'requestId':
651 'request_id'}
652 class pki.cert.CertRevokeRequest(nonce, reason=None, invalid‐
654 ity_date=None, comments=None)
655 Bases: object
656 An object of this class encapsulates all the parameters required
658 for revoking a certificate.
659 Valid values for reasons for revoking a request are:
661 'Unspecified', 'Key_Compromise', 'CA_Compromise', 'Affil‐
662 iation_Changed', 'Superseded', 'Cessation_of_Operation',
663 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_With‐
664 drawn', 'AA_Compromise'
665 reasons = ['Unspecified', 'Key_Compromise', 'CA_Compromise',
667 'Affiliation_Changed', 'Superseded', 'Cessation_of_Operation',
668 'Certificate_Hold', 'Remove_from_CRL', 'Privilege_Withdrawn',
669 'AA_Compromise']
670 class pki.cert.CertSearchRequest(**cert_search_params)
672 Bases: object
673 An object of this class is used to store the search parameters
675 and send them to server.
676 search_params = {'valid_not_before_from': 'validNotBeforeFrom',
678 'cert_type_ssl_client': 'certTypeSSLClient', 'common_name':
679 'commonName', 'serial_to': 'serialTo', 'validity_unit': 'validi‐
680 tyUnit', 'cert_type_sub_ssl_ca': 'certTypeSubSSLCA', 'user_id':
681 'userID', 'locality': 'locality', 'org_unit': 'orgUnit',
682 'issued_by': 'issuedBy', 'revocation_reason': 'revocationRea‐
683 son', 'state': 'state', 'validity_operation': 'validityOpera‐
684 tion', 'email': 'eMail', 'status': 'status',
685 'valid_not_after_from': 'validNotAfterFrom', 'match_exactly':
686 'matchExactly', 'valid_not_before_to': 'validNotBeforeTo',
687 'revoked_on_from': 'revokedOnFrom', 'validity_count': 'validity‐
688 Count', 'org': 'org', 'cert_type_ssl_server': 'certType‐
689 SSLServer', 'issued_on_from': 'issuedOnFrom',
690 'cert_type_sub_email_ca': 'certTypeSubEmailCA', 'serial_from':
691 'serialFrom', 'country': 'country', 'issued_on_to': 'issue‐
692 dOnTo', 'revoked_by': 'revokedBy', 'valid_not_after_to': 'valid‐
693 NotAfterTo', 'cert_type_secure_email': 'certTypeSecureEmail',
694 'revoked_on_to': 'revokedOnTo'}
695 pki.cert.main()
697 client Module
699 class pki.client.PKIConnection(protocol='http', hostname='localhost',
700 port='8080', subsystem='ca', accept='application/json', trust_env=None)
701 Class to encapsulate the connection between the client and a
702 Dogtag subsystem.
703 authenticate(username=None, password=None)
705 Set the parameters used for authentication if user‐
706 name/password is to be used. Both username and password
707 must not be None. Note that this method only sets the
708 parameters. Actual authentication occurs when the con‐
709 nection is attempted,
710 Parameters
712 · username -- username to authenticate connection
714 · password -- password to authenticate connection
716 Returns
718 None
719 delete(*args, **kwargs)
721 Uses python-requests to issue a DEL request to the
722 server.
723 Parameters
725 · path (str) -- path URI for the DEL request
727 · headers (dict) -- headers for the DEL request
729 · use_root_uri (boolean) -- use root URI instead
731 of subsystem URI as base
732 Returns
734 request.response -- response from the server
735 Raises Exception from python-requests in case the DEL was
737 not successful, or returns an error code.
738 get(*args, **kwargs)
740 Uses python-requests to issue a GET request to the
741 server.
742 Parameters
744 · path (str) -- path URI for the GET request
746 · headers (dict) -- headers for the GET request
748 · params (dict or bytes) -- Query parameters for
750 the GET request
751 · payload (dict, bytes, file-like object) -- data
753 to be sent in the body of the request
754 · use_root_uri (boolean) -- use root URI instead
756 of subsystem URI as base
757 Returns
759 request.response -- response from the server
760 Raises Exception from python-requests in case the GET was
762 not successful, or returns an error code.
763 post(*args, **kwargs)
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(*args, **kwargs)
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 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 generate_nonce_iv(mechanism)
858 Create a random initialization vector
859 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 generate_symmetric_key(mechanism=None, size=0)
865 Generate and return a symmetric key
866 get_cert(cert_nick)
868 Get the certificate for the specified cert_nick.
869 get_supported_algorithm_keyset()
871 returns highest supported algorithm keyset
872 initialize()
874 Initialization code
875 key_unwrap(mechanism, data, wrapping_key, nonce_iv)
877 Unwrap data that has been key wrapped using AES KeyWrap
878 set_algorithm_keyset(level)
880 sets required keyset
881 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 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.multibackend.Multi‐
897 Backend object at 0xf5c539ac>)
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, ensure_ascii=True,
1055 check_circular=True, allow_nan=True, sort_keys=False, indent=None, sep‐
1056 arators=None, encoding='utf-8', 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 pki.encoder.decode_cert(data)
1089 base64 decode X.509 certificate
1090 Parameters
1092 data (str, bytes) -- data as bytes or ASCII text
1093 Return type
1095 bytes
1096 pki.encoder.encode_cert(data)
1098 base64 encode X.509 certificate
1099 Python 3's base64.b64encode() doesn't support ASCII text.
1101 Parameters
1103 data (str, bytes) -- data as bytes or ASCII text
1104 Return type
1106 bytes
1107 key Module
1109 Module containing the Python client classes for the KeyClient and
1110 KeyRequestClient REST API on a DRM
1111 class pki.key.AsymKeyGenerationRequest(client_key_id=None,
1113 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1114 sion_key=None, realm=None)
1115 Bases: pki.ResourceMessage
1116 Class representing the data sent to the DRM when generating and
1118 archiving asymmetric keys in the DRM.
1119 DECRYPT_USAGE = 'decrypt'
1121 DERIVE_USAGE = 'derive'
1123 ENCRYPT_USAGE = 'encrypt'
1125 SIGN_RECOVER_USAGE = 'sign_recover'
1127 SIGN_USAGE = 'sign'
1129 UNWRAP_USAGE = 'unwrap'
1131 VERIFY_RECOVER_USAGE = 'verify_recover'
1133 VERIFY_USAGE = 'verify'
1135 WRAP_USAGE = 'wrap'
1137 class pki.key.Key(key_data)
1139 Bases: object
1140 An instance of this class stores the decoded encrypted secret
1142 present in the KeyData object passed in the constructor. All
1143 the key retrieval requests return this object.
1144 class pki.key.KeyArchivalRequest(client_key_id=None, data_type=None,
1146 wrapped_private_data=None, trans_wrapped_session_key=None, pki_ar‐
1147 chive_options=None, algorithm_oid=None, symkey_params=None, key_algo‐
1148 rithm=None, key_size=None, realm=None)
1149 Bases: pki.ResourceMessage
1150 Class representing the object sent to the DRM when archiving a
1152 secret.
1153 class pki.key.KeyClient(connection, crypto, transport_cert_nick=None,
1155 info_client=None)
1156 Bases: object
1157 Class that encapsulates and mirrors the functions in the KeyRe‐
1159 source and KeyRequestResource Java classes in the DRM REST API.
1160 AES_ALGORITHM = 'AES'
1162 ASYMMETRIC_KEY_TYPE = 'asymmetricKey'
1164 DES3_ALGORITHM = 'DES3'
1166 DESEDE_ALGORITHM = 'DESede'
1168 DES_ALGORITHM = 'DES'
1170 DSA_ALGORITHM = 'DSA'
1172 KEY_STATUS_ACTIVE = 'active'
1174 KEY_STATUS_INACTIVE = 'inactive'
1176 PASS_PHRASE_TYPE = 'passPhrase'
1178 RC2_ALGORITHM = 'RC2'
1180 RC4_ALGORITHM = 'RC4'
1182 RSA_ALGORITHM = 'RSA'
1184 SYMMETRIC_KEY_TYPE = 'symmetricKey'
1186 approve_request(inst, *args, **kwargs)
1188 Approve a secret recovery request
1189 archive_encrypted_data(inst, *args, **kwargs)
1191 Archive a secret (symmetric key or passphrase) on the
1192 DRM.
1193 Refer to archive_key() comments for a description of
1195 client_key_id, data_type, key_algorithm and key_size.
1196 The following parameters are also required:
1198 · encrypted_data - which is the data encrypted by
1200 a session key (168 bit 3DES symmetric key)
1201 · wrapped_session_key - the above session key
1203 wrapped by the DRM transport certificate public
1204 key.
1205 · the algorithm_oid string for the symmetric key
1207 wrap
1208 · the nonce_iv for the symmetric key wrap
1210 This function is useful if the caller wants to do their
1212 own wrapping of the secret, or if the secret was gener‐
1213 ated on a separate client machine and the wrapping was
1214 done there.
1215 The function returns a KeyRequestResponse object contain‐
1217 ing a KeyRequestInfo object with details about the
1218 archival request and key archived.
1219 archive_key(inst, *args, **kwargs)
1221 Archive a secret (symmetric key or passphrase) on the
1222 DRM.
1223 Requires a user-supplied client ID. There can be only
1225 one active key with a specified client ID. If a record
1226 for a duplicate active key exists, a BadRequestException
1227 is thrown.
1228 data_type can be one of the following:
1230 KeyClient.SYMMETRIC_KEY_TYPE, KeyClient.ASYMMET‐
1231 RIC_KEY_TYPE, KeyClient.PASS_PHRASE_TYPE
1232 key_algorithm and key_size are applicable to symmetric
1234 keys only. If a symmetric key is being archived, these
1235 parameters are required.
1236 private_data is the raw secret to be archived. It will
1238 be wrapped and sent to the DRM.
1239 The function returns a KeyRequestResponse object contain‐
1241 ing a KeyRequestInfo object with details about the
1242 archival request and key archived.
1243 archive_pki_options(inst, *args, **kwargs)
1245 Archive a secret (symmetric key or passphrase) on the
1246 DRM.
1247 Refer to archive_key() comments for a description of
1249 client_key_id, data_type, key_algorithm and key_size.
1250 pki_archive_options is the data to be archived wrapped in
1252 a PKIArchiveOptions structure,
1253 The function returns a KeyRequestResponse object contain‐
1255 ing a KeyRequestInfo object with details about the
1256 archival request and key archived.
1257 cancel_request(inst, *args, **kwargs)
1259 Cancel a secret recovery request
1260 generate_asymmetric_key(inst, *args, **kwargs)
1262 Generate and archive asymmetric keys in the DRM. Sup‐
1263 ports algorithms RSA and DSA. Valid key size for RSA =
1264 256 + (16 * n), where n: 0-496 Valid key size for DSA =
1265 512, 768, 1024. p,q,g params are not supported.
1266 Return a KeyRequestResponse which contains a KeyRe‐
1268 questInfo object that describes the URL for the request
1269 and generated keys.
1270 generate_symmetric_key(inst, *args, **kwargs)
1272 Generate and archive a symmetric key on the DRM.
1273 Return a KeyRequestResponse which contains a KeyRe‐
1275 questInfo object that describes the URL for the request
1276 and generated key.
1277 get_active_key_info(inst, *args, **kwargs)
1279 Get the info in the KeyRecord for the active secret in
1280 the DRM.
1281 get_client_keyset()
1283 get_key_info(inst, *args, **kwargs)
1285 Get the info in the KeyRecord for a specific secret in
1286 the DRM.
1287 get_request_info(inst, *args, **kwargs)
1289 Return a KeyRequestInfo object for a specific request.
1290 get_server_keyset()
1292 list_keys(inst, *args, **kwargs)
1294 List/Search archived secrets in the DRM.
1295 See KRAClient.list_keys for the valid values of status.
1297 Returns a KeyInfoCollection object.
1298 list_requests(inst, *args, **kwargs)
1300 List/Search key requests in the DRM.
1301 See KRAClient.list_requests for the valid values of
1303 request_state and request_type. Returns a KeyRequestIn‐
1304 foCollection object.
1305 modify_key_status(inst, *args, **kwargs)
1307 Modify the status of a key
1308 process_returned_key(inst, *args, **kwargs)
1310 Decrypt the returned key and place in key.data
1311 The data will either by encrypted using an encryption
1313 algorithm - in which case, the key data will contain an
1314 encryption algorithm OID, or it will be key wrapped - in
1315 which case, the key data will contain a key wrap mecha‐
1316 nism name.
1317 Only one of these should be present. If we are talking
1319 to an older server, and none is present, we will assume
1320 encryption.
1321 recover_key(inst, *args, **kwargs)
1323 Create a request to recover a secret.
1324 To retrieve a symmetric key or passphrase, the only
1326 parameter that is required is the keyId. It is possible
1327 (but not required) to pass in the session keys/passphrase
1328 and nonceData for the retrieval at this time. Those
1329 parameters are documented in the docstring for
1330 retrieve_key below.
1331 To retrieve an asymmetric key, the keyId and the the
1333 base-64 encoded certificate is required.
1334 reject_request(inst, *args, **kwargs)
1336 Reject a secret recovery request.
1337 retrieve_key(inst, *args, **kwargs)
1339 Retrieve a secret (passphrase or symmetric key) from the
1340 DRM.
1341 This method will retrieve a key from the KRA given the
1343 key_id or request_id (one of which must be specified).
1344 The data is returned as a KeyData object (which is recast
1345 to a Key object).
1346 If request_id is specified, then the value of key_id is
1348 ignored. Exceptions will be thrown if the caller is not
1349 the originator of the request, or the request is not
1350 approved.
1351 If key_id is specified instead, the following behavior
1353 applies:
1354 · If the key can be retrieved synchronously - ie. only
1356 one agent's approval is required, then the KeyData will
1357 include the secret.
1358 · If the key cannot be retrieved synchronously - ie. if
1360 more than one approval is needed, then the KeyData
1361 object will include the request ID for a recovery
1362 request that was created on the server. When that
1363 request is approved, callers can retrieve the key using
1364 retrieve_key() and setting the request_id.
1365 To ensure data security in transit, the data will be
1367 returned encrypted by a session key (168 bit 3DES symmet‐
1368 ric key) - which is first wrapped (encrypted) by the pub‐
1369 lic key of the DRM transport certificate before being
1370 sent to the DRM. The parameter trans_wrapped_session_key
1371 refers to this wrapped session key.
1372 If the trans_wrapped_session_key is not provided by call‐
1374 er, the method will call CryptoProvider methods to gener‐
1375 ate and wrap the session key. The function will return
1376 the KeyData object with a private_data attribute which
1377 stores the unwrapped key information.
1378 If the trans_wrapped_session_key is provided by the call‐
1380 er, the method will simply pass the data to the KRA, and
1381 will return the secret wrapped in the session key. The
1382 secret will still need to be unwrapped by the caller.
1383 The function will return the KeyData object, where the
1384 KeyData structure includes the wrapped secret and some
1385 nonce data to be used as a salt when unwrapping.
1386 retrieve_key_by_passphrase(inst, *args, **kwargs)
1388 Retrieve a secret (passphrase or symmetric key) from the
1389 DRM using a passphrase.
1390 This function generates a key recovery request, approves
1392 it, and retrieves the secret referred to by key_id. This
1393 assumes that only one approval is required to authorize
1394 the recovery.
1395 The secret is secured in transit by wrapping the secret
1397 with a passphrase using PBE encryption.
1398 There are two ways of using this function:
1400 1. A passphrase is provided by the caller.
1402 In this case, CryptoProvider methods will be called to
1404 create the data to securely send the passphrase to the
1405 DRM. Basically, three pieces of data will be sent:
1406 · the passphrase wrapped by a 168 bit 3DES symmetric
1408 key (the session key). This is referred to as the
1409 parameter session_wrapped_passphrase.
1410 · the session key wrapped with the public key in the
1412 DRM transport certificate. This is referred to as
1413 the trans_wrapped_session_key.
1414 · ivps nonce data, referred to as nonce_data
1416 The function will return the tuple (KeyData,
1418 unwrapped_secret)
1419 2. The caller provides the trans_wrapped_session_key,
1421 session_wrapped_passphrase and nonce_data.
1422 In this case, the data will simply be passed to the
1424 DRM. The function will return the secret encrypted by
1425 the passphrase using PBE Encryption. The secret will
1426 still need to be decrypted by the caller.
1427 The function will return the tuple (KeyData, None)
1429 retrieve_key_by_pkcs12(inst, *args, **kwargs)
1431 Retrieve an asymmetric private key and return it as
1432 PKCS12 data.
1433 This function generates a key recovery request, approves
1435 it, and retrieves the secret referred to by key_id in a
1436 PKCS12 file. This assumes that only one approval is
1437 required to authorize the recovery.
1438 This function requires the following parameters: - key_id
1440 : the ID of the key - certificate: the certificate asso‐
1441 ciated with the private key - passphrase: A passphrase
1442 for the pkcs12 file.
1443 The function returns a KeyData object.
1445 retrieve_key_data(inst, *args, **kwargs)
1447 Retrieve a secret from the DRM.
1448 @param: data - a KeyRecoveryRequest containing the keyId
1450 of the secret being retrieved, the request_id of the
1451 approved recovery request and a wrapping mechanism. More
1452 details at KRAClient.retrieve_key.
1453 Returns a KeyData object containing the wrapped secret.
1455 set_crypto_algorithms(inst, *args, **kwargs)
1457 set_transport_cert(transport_cert_nick)
1459 Set the transport certificate for crypto operations
1460 submit_request(inst, *args, **kwargs)
1462 Submit an archival, recovery or key generation request to
1463 the DRM.
1464 @param request - is either a KeyArchivalRequest, KeyRe‐
1466 coverRequest, SymKeyGenerationRequest or AsymKeyGenera‐
1467 tionRequest.
1468 returns a KeyRequestResponse object.
1470 class pki.key.KeyData
1472 Bases: object
1473 This is the object that contains the encoded wrapped secret when
1475 that secret is retrieved. It is used by the DRM to send informa‐
1476 tion of the key in the key retrieval requests.
1477 classmethod from_json(attr_list)
1479 Return a KeyData object from a JSON dict
1480 json_attribute_names = {'wrappedPrivateData': 'wrapped_pri‐
1482 vate_data', 'encryptAlgorithmOID': 'encrypt_algorithm_oid',
1483 'publicKey': 'public_key', 'nonceData': 'nonce_data',
1484 'requestID': 'request_id', 'wrapAlgorithm': 'wrap_algorithm'}
1485 class pki.key.KeyInfo
1487 Bases: object
1488 This is the object that contains information stored in the data‐
1490 base record for an archived secret. It does not contain the
1491 secret itself.
1492 classmethod from_json(attr_list)
1494 Return KeyInfo from JSON dict
1495 get_key_id()
1497 Return the key ID as parsed from key URL
1498 json_attribute_names = {'publicKey': 'public_key', 'clien‐
1500 tKeyID': 'client_key_id', 'ownerName': 'owner_name', 'keyURL':
1501 'key_url'}
1502 class pki.key.KeyInfoCollection
1504 Bases: object
1505 This class represents data returned when searching the DRM
1507 archived secrets. Essentially, its a list of KeyInfo objects.
1508 classmethod from_json(json_value)
1510 Return a KeyInfoCollection object from its JSON represen‐
1511 tation
1512 class pki.key.KeyRecoveryRequest(key_id=None, request_id=None,
1514 trans_wrapped_session_key=None, session_wrapped_passphrase=None,
1515 nonce_data=None, certificate=None, passphrase=None, payload_wrap‐
1516 ping_name=None, payload_encryption_oid=None)
1517 Bases: pki.ResourceMessage
1518 Class representing the data sent to the DRM when either creating
1520 a request for the recovery of a secret, or, once the request is
1521 approved, retrieving the secret.
1522 class pki.key.KeyRequestInfo
1524 Bases: object
1525 This class represents data about key requests (archival, recov‐
1527 ery, key generation etc.) in the DRM.
1528 classmethod from_json(attr_list)
1530 Return a KeyRequestInfo object from a JSON dict.
1531 get_key_id()
1533 Return the ID of the secret referred to by this request.
1534 get_request_id()
1536 Return the request ID by parsing the request URL.
1537 json_attribute_names = {'requestType': 'request_type', 'request‐
1539 Status': 'request_status', 'requestURL': 'request_url',
1540 'keyURL': 'key_url'}
1541 class pki.key.KeyRequestInfoCollection
1543 Bases: object
1544 This class represents the data returned when searching the key
1546 requests in the DRM. Essentially, its a list of KeyRequestInfo
1547 objects.
1548 classmethod from_json(json_value)
1550 Return a KeyRequestInfoCollection object from its JSON
1551 representation.
1552 class pki.key.KeyRequestResponse
1554 Bases: object
1555 This class is returned when an archival, recovery or key genera‐
1557 tion request is created. It includes a KeyRequestInfo object
1558 with information about the created request, and a KeyData struc‐
1559 ture which contains the wrapped secret (if that operation is
1560 supported).
1561 classmethod from_json(json_value)
1563 Return a KeyRequestResponse object from its JSON repre‐
1564 sentation.
1565 get_key_id()
1567 Return the id for the key archived, recovered or gener‐
1568 ated
1569 get_request_id()
1571 Return the id for the created request
1572 class pki.key.RequestId(req_id)
1574 Bases: object
1575 Class representing a Request ID
1577 class pki.key.SymKeyGenerationRequest(client_key_id=None,
1579 key_size=None, key_algorithm=None, key_usages=None, trans_wrapped_ses‐
1580 sion_key=None, realm=None)
1581 Bases: pki.ResourceMessage
1582 Class representing the data sent to the DRM when generating and
1584 archiving a symmetric key in the DRM.
1585 DECRYPT_USAGE = 'decrypt'
1587 ENCRYPT_USAGE = 'encrypt'
1589 SIGN_USAGE = 'sign'
1591 UNWRAP_USAGE = 'unwrap'
1593 VERIFY_USAGE = 'verify'
1595 WRAP_USAGE = 'wrap'
1597 pki.key.main()
1599 Some unit tests - basically printing different types of requests
1600 kra Module
1602 Module containing KRAClient class. This class should be used by Python
1603 clients to interact with the DRM to expose the functionality of the
1604 KeyClient and KeyRequestResource REST APIs.
1605 class pki.kra.KRAClient(connection, crypto, transport_cert_nick=None)
1607 Bases: object
1608 Client class that models interactions with a KRA using the Key
1610 and KeyRequest REST APIs.
1611 profile Module
1613 class pki.profile.Descriptor(syntax=None, constraint=None, descrip‐
1614 tion=None, default_value=None)
1615 Bases: object
1616 This class represents the description of a ProfileAttribute. It
1618 stores information such as the syntax, constraint and default
1619 value of a profile attribute.
1620 classmethod from_json(attr_list)
1622 json_attribute_names = {'DefaultValue': 'default_value', 'Con‐
1624 straint': 'constraint', 'Description': 'description', 'Syntax':
1625 'syntax'}
1626 class pki.profile.PolicyConstraint(name=None, description=None,
1628 class_id=None, policy_constraint_values=None)
1629 Bases: object
1630 An object of this class contains the policy constraints applied
1632 to a ProfileInput used by a certificate enrollment request.
1633 add_constraint_value(policy_constraint_value)
1635 Add a PolicyConstraintValue to the policy_constraint_val‐
1636 ues list.
1637 classmethod from_json(attr_list)
1639 get_constraint_value(policy_constraint_value_name)
1641 Returns a PolicyConstraintValue object with the given
1642 name. None, if there is no match.
1643 json_attribute_names = {'classId': 'class_id', 'id': 'name',
1645 'constraint': 'policy_constraint_values'}
1646 remove_constraint_value(policy_constraint_value_name)
1648 Removes a PolicyConstraintValue with the given name form
1649 the policy_constraint_values list.
1650 class pki.profile.PolicyConstraintValue(name=None, value=None, descrip‐
1652 tor=None)
1653 Bases: object
1654 Represents a PolicyConstraintValue
1656 classmethod from_json(attr_list)
1658 name
1660 class pki.profile.PolicyDefault(name=None, class_id=None, descrip‐
1662 tion=None, policy_attributes=None, policy_params=None)
1663 Bases: object
1664 An object of this class contains information of the default
1666 usage of a specific ProfileInput.
1667 add_attribute(policy_attribute)
1669 Add a policy attribute to the attribute list. @param
1670 policy_attribute - A ProfileAttribute object
1671 add_parameter(policy_parameter)
1673 Add a profile parameter to the parameters list. @param
1674 policy_parameter - A ProfileParameter object.
1675 classmethod from_json(attr_list)
1677 get_attribute(policy_attribute_name)
1679 Fetch the policy attribute with the given name from the
1680 attributes list.
1681 get_parameter(profile_parameter_name)
1683 Fetch a profile parameter with the given name from the
1684 parameters list.
1685 json_attribute_names = {'classId': 'class_id', 'params': 'pol‐
1687 icy_params', 'id': 'name', 'policyAttribute': 'pol‐
1688 icy_attributes'}
1689 remove_attribute(policy_attribute_name)
1691 Remove a policy attribute with the given name from the
1692 attributes list.
1693 remove_parameter(profile_parameter_name)
1695 Remove a profile parameter with the given name from the
1696 parameters list.
1697 class pki.profile.PolicySet(name=None, policy_list=None)
1699 Bases: object
1700 An object of this class contains a name value pair of the policy
1702 name and the ProfilePolicy object.
1703 add_policy(profile_policy)
1705 Add a ProfilePolicy object to the policy_list
1706 classmethod from_json(attr_list)
1708 get_policy(policy_id)
1710 Returns a ProfilePolicy object with the given profile id.
1711 json_attribute_names = {'id': 'name', 'value': 'policy_list'}
1713 remove_policy(policy_id)
1715 Removes a ProfilePolicy with the given ID from the Poli‐
1716 cySet.
1717 class pki.profile.PolicySetList(policy_sets=None)
1719 Bases: object
1720 An object of this class stores a list of ProfileSet objects.
1722 add_policy_set(policy_set)
1724 Add a PolicySet object to the policy_sets list.
1725 classmethod from_json(attr_list)
1727 get_policy_set(policy_set_name)
1729 Fetch the PolicySet object for the given name. Returns
1730 None, if not found.
1731 policy_sets
1733 remove_policy_set(policy_set_name)
1735 Remove a PolicySet object with the given name from the
1736 policy_sets list.
1737 class pki.profile.Profile(profile_id=None, class_id=None, name=None,
1739 description=None, enabled=None, visible=None, enabled_by=None, authen‐
1740 ticator_id=None, authorization_acl=None, renewal=None, xml_output=None,
1741 inputs=None, outputs=None, policy_set_list=None, link=None)
1742 Bases: object
1743 This class represents an enrollment profile.
1745 add_input(profile_input)
1747 Add a ProfileInput object to the inputs list of the Pro‐
1748 file.
1749 add_output(profile_output)
1751 Add a ProfileOutput object to the outputs list of the
1752 Profile.
1753 add_policy_set(policy_set)
1755 Add a PolicySet object to the policy_sets list of the
1756 Profile.
1757 classmethod from_json(attr_list)
1759 get_input(profile_input_id)
1761 Fetches a ProfileInput with the given ProfileInput id.
1762 Returns None, if there is no matching input.
1763 get_output(profile_output_id)
1765 Fetches a ProfileOutput with the given ProfileOutput id.
1766 Returns None, if there is no matching output.
1767 get_policy_set(policy_set_name)
1769 Fetches a ProfileInput with the given ProfileInput id.
1770 Returns None, if there is no matching input.
1771 static get_profile_data_from_file(path_to_file)
1773 Reads the file for the serialized Profile object. Cur‐
1774 rently supports only data format in json.
1775 json_attribute_names = {'classId': 'class_id', 'authentica‐
1777 torId': 'authenticator_id', 'Output': 'outputs', 'PolicySets':
1778 'policy_set_list', 'xmlOutput': 'xml_output', 'authzAcl':
1779 'authorization_acl', 'enabledBy': 'enabled_by', 'Input':
1780 'inputs', 'id': 'profile_id'}
1781 remove_input(profile_input_id)
1783 Remove a ProfileInput from the inputs list of the Pro‐
1784 file.
1785 remove_output(profile_output_id)
1787 Remove a ProfileOutput from the outputs list of the Pro‐
1788 file.
1789 remove_policy_set(policy_set_name)
1791 Remove a PolicySet from the policy_sets list of the Pro‐
1792 file.
1793 class pki.profile.ProfileAttribute(name=None, value=None, descrip‐
1795 tor=None)
1796 Bases: object
1797 Represents a profile attribute of a ProfileInput.
1799 classmethod from_json(attr_list)
1801 json_attribute_names = {'Descriptor': 'descriptor', 'Value':
1803 'value'}
1804 class pki.profile.ProfileClient(connection)
1806 Bases: object
1807 This class consists of methods for accessing the ProfileRe‐
1809 source.
1810 create_profile(inst, *args, **kwargs)
1812 Create a new profile for the given Profile object.
1813 create_profile_from_file(path_to_file)
1815 Reads the file for the serialized Profile object. Per‐
1816 forms the profile create operation. Currently supports
1817 only data format in json.
1818 delete_profile(inst, *args, **kwargs)
1820 Delete a profile with the given Profile Id.
1821 disable_profile(inst, *args, **kwargs)
1823 Disables a profile.
1824 enable_profile(inst, *args, **kwargs)
1826 Enables a profile.
1827 get_profile(inst, *args, **kwargs)
1829 Fetches information for the profile for the given profile
1830 id. Returns a ProfileData object.
1831 list_profiles(inst, *args, **kwargs)
1833 Fetches the list of profiles. The start and size argu‐
1834 ments provide pagination support. Returns a Profile‐
1835 DataInfoCollection object.
1836 modify_profile(inst, *args, **kwargs)
1838 Modify an existing profile with the given Profile object.
1839 modify_profile_from_file(path_to_file)
1841 Reads the file for the serialized Profile object. Per‐
1842 forms the profile modify operation. Currently supports
1843 only data format in json.
1844 class pki.profile.ProfileDataInfo
1846 Bases: object
1847 Stores information about a profile
1849 classmethod from_json(attr_list)
1851 json_attribute_names = {'profileDescription': 'profile_descrip‐
1853 tion', 'profileId': 'profile_id', 'profileURL': 'profile_url',
1854 'profileName': 'profile_name'}
1855 class pki.profile.ProfileDataInfoCollection
1857 Bases: object
1858 Represents a collection of ProfileDataInfo objects. Also encap‐
1860 sulates the links for the list of the objects stored.
1861 classmethod from_json(attr_list)
1863 class pki.profile.ProfileInput(profile_input_id=None, class_id=None,
1865 name=None, text=None, attributes=None, config_attributes=None)
1866 Bases: object
1867 This class encapsulates all the attributes of a profile to gen‐
1869 erate a specific property of a certificate. Ex. Subject name,
1870 Requestor Information etc.
1871 add_attribute(profile_attribute)
1873 Add a ProfileAttribute object to the attributes list.
1874 add_config_attribute(profile_attribute)
1876 Add a ProfileAttribute object to the config_attributes
1877 list.
1878 classmethod from_json(attr_list)
1880 get_attribute(profile_attribute_name)
1882 Returns a ProfileAttribute object for the given name.
1883 None, if no match.
1884 get_config_attribute(config_attribute_name)
1886 Returns a ProfileAttribute object with the given name.
1887 None, if there is no match in the config_attributes list.
1888 json_attribute_names = {'ClassID': 'class_id', 'Name': 'name',
1890 'Text': 'text', 'ConfigAttribute': 'config_attributes',
1891 'Attribute': 'attributes', 'id': 'profile_input_id'}
1892 remove_attribute(profile_attribute_name)
1894 Remove a ProfileAttribute object with the given name from
1895 the attributes list.
1896 remove_config_attribute(config_attribute_name)
1898 Remove a ProfileAttribute object with the given name from
1899 the config_attributes list.
1900 class pki.profile.ProfileOutput(profile_output_id=None, name=None,
1902 text=None, class_id=None, attributes=None)
1903 Bases: object
1904 This class defines the output of a certificate enrollment
1906 request using a profile.
1907 add_attribute(profile_attribute)
1909 Add a ProfileAttribute object to the attributes list.
1910 classmethod from_json(attr_list)
1912 get_attribute(profile_attribute_name)
1914 Returns a ProfileAttribute object for the given name.
1915 None, if no match.
1916 json_attribute_names = {'classId': 'class_id', 'id': 'pro‐
1918 file_output_id'}
1919 remove_attribute(profile_attribute_name)
1921 Remove a ProfileAttribute object with the given name from
1922 the attributes list.
1923 class pki.profile.ProfileParameter(name=None, value=None)
1925 Bases: object
1926 classmethod from_json(attr_list)
1928 class pki.profile.ProfilePolicy(policy_id=None, policy_default=None,
1930 policy_constraint=None)
1931 Bases: object
1932 This class represents the policy a profile adheres to. An
1934 object of this class stores the default values for profile and
1935 the constraints present on the values of the attributes of the
1936 profile submitted for an enrollment request.
1937 classmethod from_json(attr_list)
1939 json_attribute_names = {'id': 'policy_id', 'def': 'pol‐
1941 icy_default', 'constraint': 'policy_constraint'}
1942 class pki.profile.ProfilePolicySet
1944 Bases: object
1945 Stores a list of ProfilePolicy objects.
1947 classmethod from_json(attr_list)
1949 pki.profile.main()
1951 system Module
1953 class pki.system.ConfigurationRequest
1954 Bases: object
1955 Class used to represent a configuration request to be submitted
1957 to the Java installation servlet during the execution of
1958 pkispawn.
1959 This class is the python equivalent of the Java class: com.net‐
1961 scape.certsrv.system.ConfigurationRequest
1962 class pki.system.ConfigurationResponse
1964 Bases: object
1965 Class used to represent the response from the Java configuration
1967 servlet during the execution of pkispawn.
1968 This class is the python equivalent of the Java class: com.net‐
1970 scape.certsrv.system.ConfigurationRequest
1971 class pki.system.SecurityDomainClient(connection)
1973 Bases: object
1974 Client used to get the security domain from a security domain
1976 CA. The connection details for the security domain CA are spec‐
1977 ified in a PKIConnection object used to construct this client.
1978 get_old_security_domain_info()
1980 Contact the security domain CA specified in the connec‐
1981 tion object used to construct this client and get the
1982 security domain using the old servlet-based interface.
1983 This method is useful when contacting old servers which
1984 do not provide the REST API.
1985 Returns
1987 pki.system.SecurityDomainInfo
1988 get_security_domain_info()
1990 Contact the security domain CA specified in the connec‐
1991 tion object used to construct this client and get the
1992 security domain using the REST API.
1993 Returns
1995 pki.system.SecurityDomainInfo
1996 class pki.system.SecurityDomainHost
1998 Bases: object
1999 Class representing a security domain host.
2001 classmethod from_json(json_value)
2003 Constructs a SecurityDomainHost object from JSON.
2004 Parameters
2006 json_value (str) -- JSON string representing a
2007 security domain host.
2008 Returns
2010 SecurityDomainHost
2011 class pki.system.SecurityDomainInfo
2013 Bases: object
2014 Class representing the entire security domain. This is essen‐
2016 tially a list of SecurityDomainSubsystem components.
2017 classmethod from_json(json_value)
2019 Create a SecurityDomainInfo object from JSON.
2020 Parameters
2022 json_value (str) -- JSON representation of a secu‐
2023 rity domain.
2024 Returns
2026 SecurityDomainInfo
2027 class pki.system.SecurityDomainSubsystem
2029 Bases: object
2030 Class representing a security domain subsystem. This is essen‐
2032 tially a list of SecurityDomainHost objects of a particular sub‐
2033 system type (ca, kra, tps, tks, ocsp).
2034 classmethod from_json(json_value)
2036 Constructs a SecurityDomainSubsystem from a JSON repre‐
2037 sentation.
2038 Parameters
2040 json_value (str) -- JSON representation of the
2041 Security Domain Subsystem
2042 Returns
2044 SecurityDomainSubsystem
2045 class pki.system.SystemCertData
2047 Bases: object
2048 Class used to represent the data for a system certificate, which
2050 is used in the data passed into and returned from the Java
2051 installation servlet during the execution of pkispawn.
2052 This class is the python equivalent of the Java class: com.net‐
2054 scape.certsrv.system.SystemCertData
2055 class pki.system.SystemConfigClient(connection)
2057 Bases: object
2058 Client used to interact with the Java configuration servlet to
2060 configure a Dogtag subsystem during the execution of pkispawn.
2061 The connection details for the system being configured are
2063 passed in the PKIConnection object used when constructing this
2064 object.
2065 configure(data)
2067 Contacts the server and invokes the Java configuration
2068 REST API to configure a Dogtag subsystem.
2069 Parameters
2071 data (ConfigurationRequest) -- Configuration
2072 request containing all the input needed to config‐
2073 ure the subsystem
2074 Returns
2076 ConfigurationResponse -- response from configura‐
2077 tion servlet.
2078 class pki.system.SystemStatusClient(connection)
2080 Bases: object
2081 Client used to check the status of a Dogtag subsystem.
2083 get_status()
2085 Checks the status of the subsystem by calling the getSta‐
2086 tus() servlet. This is used to determine if the server
2087 is up and ready to receive and process requests.
2088 Returns
2090 str - getStatus response
2091 systemcert Module
2093 Module containing the Python client classes for the SystemCert REST API
2094 class pki.systemcert.SystemCertClient(connection)
2096 Bases: object
2097 Class encapsulating and mirroring the functionality in the Sys‐
2099 temCertResource Java interface class defining the REST API for
2100 system certificate resources.
2101 get_transport_cert(inst, *args, **kwargs)
2103 Return transport certificate.
2104 Returns
2106 pki.cert.CertData -- transport certificate data
2107 upgrade Module
2109 class pki.upgrade.PKIUpgradeScriptlet
2110 Bases: object
2111 backup(path)
2113 can_upgrade()
2115 get_backup_dir()
2117 init()
2119 revert()
2121 update_tracker()
2123 upgrade()
2125 upgrade_system()
2127 class pki.upgrade.PKIUpgradeTracker(name, filename, delimiter='=', ver‐
2129 sion_key='PKI_VERSION', index_key='PKI_UPGRADE_INDEX')
2130 Bases: object
2131 get_index()
2133 get_version()
2135 remove()
2137 remove_index()
2139 remove_version()
2141 set(version)
2143 set_index(index)
2145 set_version(version)
2147 show()
2149 class pki.upgrade.PKIUpgrader(upgrade_dir='/usr/share/pki/upgrade',
2151 version=None, index=None, silent=False)
2152 Bases: object
2153 all_versions()
2155 get_current_version()
2157 get_target_version()
2159 get_tracker()
2161 is_complete()
2163 remove_tracker()
2165 reset_tracker()
2167 revert()
2169 revert_version(version)
2171 scriptlets(version)
2173 set_tracker(version)
2175 show_tracker()
2177 status()
2179 upgrade()
2181 upgrade_version(version)
2183 version_dir(version)
2185 versions()
2187 util Module
2189 Module containing utility functions and classes for the Dogtag python
2190 code
2191 class pki.util.Version(obj)
2193 Bases: object
2194 pki.util.chmod(path, perms)
2196 Change permissions of a file or folder recursively.
2197 pki.util.chown(path, uid, gid)
2199 Change ownership of a file or folder recursively.
2200 pki.util.copy(source, dest)
2202 Copy a file or a folder and its contents.
2203 pki.util.copydirs(source, dest)
2205 Copy a folder and its parents while preserving their attributes.
2206 pki.util.copyfile(source, dest, overwrite=True)
2208 Copy a file or link while preserving its attributes.
2209 pki.util.copytree(src, dst, symlinks=False, ignore=None)
2211 Recursively copy a directory tree using copy2().
2212 PATCH: This code was copied from 'shutil.py' and patched to
2214 allow 'The destination directory to already exist.'
2215 If exception(s) occur, an Error is raised with a list of rea‐
2217 sons.
2218 If the optional symlinks flag is true, symbolic links in the
2220 source tree result in symbolic links in the destination tree; if
2221 it is false, the contents of the files pointed to by symbolic
2222 links are copied.
2223 The optional ignore argument is a callable. If given, it is
2225 called with the src parameter, which is the directory being vis‐
2226 ited by copytree(), and names which is the list of src contents,
2227 as returned by os.listdir():
2228 callable(src, names) -> ignored_names
2229 Since copytree() is called recursively, the callable will be
2231 called once for each directory that is copied. It returns a list
2232 of names relative to the src directory that should not be
2233 copied.
2234 Consider this example code rather than the ultimate tool.
2236 pki.util.customize_file(input_file, output_file, params)
2238 Customize a file with specified parameters.
2239 pki.util.load_properties(filename, properties)
2241 pki.util.read_environment_files(env_file_list=None)
2243 pki.util.store_properties(filename, properties)
2245 · genindex
2247 · modindex
2249 · search
2251
2253 Dogtag PKI Project Team
2254
2256 2014, Dogtag PKI Team
2257@APPLICATION_VERSION@ March 14, 2019 PKI-PYTHON-CLIENT(1)