| PKI-PYTHON-CLIENT(1) | Dogtag Certificate System | PKI-PYTHON-CLIENT(1) |
pki-python-client - Dogtag Python Client API
Dogtag is an enterprise software system designed to manage enterprise Public Key Infrastructure (PKI) deployments. These pages document the Python client API that can be used to interact with Dogtag's REST API to request and issue certificates, store secrets in the KRA etc.
This module contains top-level classes and functions used by the Dogtag project.
Class representing a key/value pair.
This object is the basis of the representation of a ResourceMessage.
Class representing a list of attributes.
This class is needed because of a JavaMapper used in the REST API.
Bad Request Exception: return code = 400
Cert Not Found Exception: return code = 404
Conflicting Operation Exception: return code = 409
Forbidden Exception: return code = 403
Group Not Found Exception: return code = 404
Gone Exception: return code = 410
Key Not Found Exception: return code 404
Stores the information of the resteasy's Link object sent by the server for a resource.
Base exception class for REST Interface
Profile Not Found Exception: return code = 404
Class to manage property files The contents of the property file are maintained internally as a list of properties.
Properties are strings of the format <name> <delimiter> <value> where '=' is the default delimiter.
Request Not Found Exception: return code = 404
This class is the basis for the various types of key requests. It is essentially a list of attributes.
Not Found Exception: return code = 404
Unauthorized Exception: return code = 401
User Not Found Exception: return code = 404
See also: - https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.Name - https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.RelativeDistinguishedName - https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.NameAttribute - https://cryptography.io/en/latest/x509/reference.html#cryptography.x509.ObjectIdentifier
See sftk_newPinCheck() in the following file: https://dxr.mozilla.org/nss/source/nss/lib/softoken/fipstokn.c
The minimum password length is FIPS_MIN_PIN Unicode characters.
If an ASCII uppercase letter is the first character of the password, the uppercase letter is not counted toward its character class.
If a digit is the last character of the password, the digit is not counted toward its character class.
The FIPS_MIN_PIN is defined in the following file: https://dxr.mozilla.org/nss/source/nss/lib/softoken/pkcs11i.h
#define FIPS_MIN_PIN 7
Class used to associate an authentication session variable with a connection.
Class encapsulating and mirroring the functionality in the CertResource Java interface class defining the REST API for Certificate resources.
Calling this method with valid arguments, creates an enrollment request, submits it to the server, approves the certificate requests generated for the enrollment and returns a list of CertData objects for all the certificates generated as part of this enrollment.
Note: This method supports only certificate enrollment where only one agent approval is sufficient.
Requires an agent level authentication. Returns a list of CertEnrollmentResult objects.
Class containing certificate data as returned from getCert()
Class containing information contained in a CertRecord on the CA. This data is returned when searching/listing certificate records.
Class containing list of CertDataInfo objects and their respective link objects. This data is returned when searching/listing certificate records in the CA.
Class containing results of an enrollment request.
This structure contains information about the cert request generated and any certificates issued.
An object of this class stores represents a certificate request.
Class containing list of CertRequestInfo objects. This data is returned when listing certificate request records in the CA.
An object of this class represent the response from the server when reviewing a certificate enrollment request. It contains a nonce required to perform action on the request.
An object of this class encapsulates all the parameters required for revoking a certificate.
An object of this class is used to store the search parameters and send them to server.
Class to encapsulate the connection between the client and a Dogtag subsystem.
Custom SSLContext Adapter for requests
This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.
PKIConnection is not able to verify HTTPS connections yet. This decorator catches the warning.
Module containing crypto classes.
Abstract class containing methods to do cryptographic operations.
The mechanism is the type of symmetric key, which defaults to a 56 bit DES3 key.
We expect the data and nonce_iv values to be base64 encoded. The mechanism is the type of key used to do the wrapping. It defaults to a 56 bit DES3 key.
Class that defines python-cryptography implementation of CryptoProvider. Requires a PEM file containing the agent cert to be initialized.
Note that all inputs and outputs are unencoded.
Wrap (encrypt) data using the supplied asymmetric key
Unwrap the encrypted data which has been wrapped using a KeyWrap mechanism.
Unwrap (decrypt) data using the supplied symmetric key
Wrap (encrypt) data using the supplied symmetric key
Class that defines NSS implementation of CryptoProvider. Requires an NSS database to have been set up and initialized.
Note that all inputs and outputs are unencoded.
Wrap (encrypt) data using the supplied asymmetric key
Note that for fixed length keys, this length should be 0. If no length is provided, then the function will either use 0 (for fixed length keys) or the maximum available length for that algorithm and the token.
Searches NSS database and returns SecItem object for this certificate.
Return unwrapped data for data that has been keywrapped. For NSS, we only support 3DES - so something that has been keywrapped can be decrypted. This is precisely what we used to do before.
Unwrap (decrypt) data using the supplied symmetric key
Wrap (encrypt) data using the supplied symmetric key
A custom JSONEncoder class that knows how to encode core custom objects.
Custom objects are encoded as JSON object literals (ie, dicts) with one key, 'TypeName' where 'TypeName' is the actual name of the type to which the object belongs. That single key maps to another object literal which is just the __dict__ of the object encoded.
Reason for ignoring the error: E0202 - An attribute affected in json.encoder line 157 hide this method reported by pylint:
The error is in json.encoder.JSONEncoder class. There is a default method (which is overridden here) and also a class attribute self.default initialized in the init method of the class. The intention of such usage being that a custom default method object can be passed to init when creating an instance of JSONEncoder, which is then assigned to class's default method. (which is valid) But pylint raises an issue due to the usage of same name for a method and an attribute in which case the attribute definition hides the method. The reason and example for the issue: (top rated comment)
For example, to support arbitrary iterators, you could implement default like this:
def default(self, o):
try:
iterable = iter(o)
except TypeError:
pass
else:
return list(iterable)
# Let the base class default method raise the TypeError
return JSONEncoder.default(self, o)
Python 3's base64.b64encode() doesn't support ASCII text.
Module containing the Python client classes for the KeyClient and KeyRequestClient REST API on a DRM
Class representing the data sent to the DRM when generating and archiving asymmetric keys in the DRM.
An instance of this class stores the decoded encrypted secret present in the KeyData object passed in the constructor. All the key retrieval requests return this object.
Class representing the object sent to the DRM when archiving a secret.
Class that encapsulates and mirrors the functions in the KeyResource and KeyRequestResource Java classes in the DRM REST API.
Refer to archive_key() comments for a description of client_key_id, data_type, key_algorithm and key_size.
This function is useful if the caller wants to do their own wrapping of the secret, or if the secret was generated on a separate client machine and the wrapping was done there.
The function returns a KeyRequestResponse object containing a KeyRequestInfo object with details about the archival request and key archived.
Requires a user-supplied client ID. There can be only one active key with a specified client ID. If a record for a duplicate active key exists, a BadRequestException is thrown.
key_algorithm and key_size are applicable to symmetric keys only. If a symmetric key is being archived, these parameters are required.
private_data is the raw secret to be archived. It will be wrapped and sent to the DRM.
The function returns a KeyRequestResponse object containing a KeyRequestInfo object with details about the archival request and key archived.
Refer to archive_key() comments for a description of client_key_id, data_type, key_algorithm and key_size.
pki_archive_options is the data to be archived wrapped in a PKIArchiveOptions structure,
The function returns a KeyRequestResponse object containing a KeyRequestInfo object with details about the archival request and key archived.
Return a KeyRequestResponse which contains a KeyRequestInfo object that describes the URL for the request and generated keys.
Return a KeyRequestResponse which contains a KeyRequestInfo object that describes the URL for the request and generated key.
See KRAClient.list_keys for the valid values of status. Returns a KeyInfoCollection object.
See KRAClient.list_requests for the valid values of request_state and request_type. Returns a KeyRequestInfoCollection object.
The data will either by encrypted using an encryption algorithm - in which case, the key data will contain an encryption algorithm OID, or it will be key wrapped - in which case, the key data will contain a key wrap mechanism name.
Only one of these should be present. If we are talking to an older server, and none is present, we will assume encryption.
To retrieve a symmetric key or passphrase, the only parameter that is required is the keyId. It is possible (but not required) to pass in the session keys/passphrase and nonceData for the retrieval at this time. Those parameters are documented in the docstring for retrieve_key below.
To retrieve an asymmetric key, the keyId and the the base-64 encoded certificate is required.
This method will retrieve a key from the KRA given the key_id or request_id (one of which must be specified). The data is returned as a KeyData object (which is recast to a Key object).
If request_id is specified, then the value of key_id is ignored. Exceptions will be thrown if the caller is not the originator of the request, or the request is not approved.
If key_id is specified instead, the following behavior applies:
To ensure data security in transit, the data will be returned encrypted by a session key (168 bit 3DES symmetric key) - which is first wrapped (encrypted) by the public key of the DRM transport certificate before being sent to the DRM. The parameter trans_wrapped_session_key refers to this wrapped session key.
If the trans_wrapped_session_key is not provided by caller, the method will call CryptoProvider methods to generate and wrap the session key. The function will return the KeyData object with a private_data attribute which stores the unwrapped key information.
If the trans_wrapped_session_key is provided by the caller, the method will simply pass the data to the KRA, and will return the secret wrapped in the session key. The secret will still need to be unwrapped by the caller. The function will return the KeyData object, where the KeyData structure includes the wrapped secret and some nonce data to be used as a salt when unwrapping.
This function generates a key recovery request, approves it, and retrieves the secret referred to by key_id. This assumes that only one approval is required to authorize the recovery.
The secret is secured in transit by wrapping the secret with a passphrase using PBE encryption.
There are two ways of using this function:
In this case, CryptoProvider methods will be called to create the data to securely send the passphrase to the DRM. Basically, three pieces of data will be sent:
The function will return the tuple (KeyData, unwrapped_secret)
In this case, the data will simply be passed to the DRM. The function will return the secret encrypted by the passphrase using PBE Encryption. The secret will still need to be decrypted by the caller.
The function will return the tuple (KeyData, None)
This function generates a key recovery request, approves it, and retrieves the secret referred to by key_id in a PKCS12 file. This assumes that only one approval is required to authorize the recovery.
This function requires the following parameters: - key_id : the ID of the key - certificate: the certificate associated with the private key - passphrase: A passphrase for the pkcs12 file.
The function returns a KeyData object.
@param: data - a KeyRecoveryRequest containing the keyId of the secret being retrieved, the request_id of the approved recovery request and a wrapping mechanism. More details at KRAClient.retrieve_key.
Returns a KeyData object containing the wrapped secret.
@param request - is either a KeyArchivalRequest, KeyRecoverRequest, SymKeyGenerationRequest or AsymKeyGenerationRequest.
returns a KeyRequestResponse object.
This is the object that contains the encoded wrapped secret when that secret is retrieved. It is used by the DRM to send information of the key in the key retrieval requests.
This is the object that contains information stored in the database record for an archived secret. It does not contain the secret itself.
This class represents data returned when searching the DRM archived secrets. Essentially, its a list of KeyInfo objects.
Class representing the data sent to the DRM when either creating a request for the recovery of a secret, or, once the request is approved, retrieving the secret.
This class represents data about key requests (archival, recovery, key generation etc.) in the DRM.
This class represents the data returned when searching the key requests in the DRM. Essentially, its a list of KeyRequestInfo objects.
This class is returned when an archival, recovery or key generation request is created. It includes a KeyRequestInfo object with information about the created request, and a KeyData structure which contains the wrapped secret (if that operation is supported).
Class representing a Request ID
Class representing the data sent to the DRM when generating and archiving a symmetric key in the DRM.
Module containing KRAClient class. This class should be used by Python clients to interact with the DRM to expose the functionality of the KeyClient and KeyRequestResource REST APIs.
Client class that models interactions with a KRA using the Key and KeyRequest REST APIs.
This class represents the description of a ProfileAttribute. It stores information such as the syntax, constraint and default value of a profile attribute.
An object of this class contains the policy constraints applied to a ProfileInput used by a certificate enrollment request.
Represents a PolicyConstraintValue
An object of this class contains information of the default usage of a specific ProfileInput.
An object of this class contains a name value pair of the policy name and the ProfilePolicy object.
An object of this class stores a list of ProfileSet objects.
This class represents an enrollment profile.
Represents a profile attribute of a ProfileInput.
This class consists of methods for accessing the ProfileResource.
Represents a collection of ProfileDataInfo objects. Also encapsulates the links for the list of the objects stored.
This class encapsulates all the attributes of a profile to generate a specific property of a certificate. Ex. Subject name, Requestor Information etc.
This class defines the output of a certificate enrollment request using a profile.
This class represents the policy a profile adheres to. An object of this class stores the default values for profile and the constraints present on the values of the attributes of the profile submitted for an enrollment request.
Stores a list of ProfilePolicy objects.
Class representing the entire security domain. This is essentially a list of SecurityDomainSubsystem components.
Client used to get the security domain from a security domain CA. The connection details for the security domain CA are specified in a PKIConnection object used to construct this client.
Class representing a security domain host.
Class representing a security domain subsystem. This is essentially a list of SecurityDomainHost objects of a particular subsystem type (ca, kra, tps, tks, ocsp).
Class used to represent the data for a system certificate, which is used in the data passed into and returned from the Java installation servlet during the execution of pkispawn.
This class is the python equivalent of the Java class: com.netscape.certsrv.system.SystemCertData
Client used to interact with the Java configuration servlet to configure a Dogtag subsystem during the execution of pkispawn.
The connection details for the system being configured are passed in the PKIConnection object used when constructing this object.
Client used to check the status of a Dogtag subsystem.
Module containing the Python client classes for the SystemCert REST API
Class encapsulating and mirroring the functionality in the SystemCertResource Java interface class defining the REST API for system certificate resources.
Module containing utility functions and classes for the Dogtag python code
If exception(s) occur, an Error is raised with a list of reasons.
If the optional symlinks flag is true, symbolic links in the source tree result in symbolic links in the destination tree; if it is false, the contents of the files pointed to by symbolic links are copied.
The optional ignore argument is a callable. If given, it is called with the src parameter, which is the directory being visited by copytree(), and names which is the list of src contents, as returned by os.listdir():
Since copytree() is called recursively, the callable will be called once for each directory that is copied. It returns a list of names relative to the src directory that should not be copied.
Consider this example code rather than the ultimate tool.
Dogtag PKI Project Team
2021, Dogtag PKI Team
| April 14, 2021 | @APPLICATION_VERSION@ |