PKI Key Request Python API - dogtagpki/pki GitHub Wiki
The key request resource provides clients (agents only) to perform operations to create a new request, retrieve existing requests, approve/reject/cancel requests.
The KeyRequestResource object also requires the a connection object to be passed during instantiation.
See also:
list_requests(
self,
request_state=None,
request_type=None,
client_id=None,
start=None,
page_size=None,
max_results=None,
max_time=None)
List/Search key requests in the DRM. This method call performs a GET http request to fetch the list of key requests. All the arguments passed are passed as request parameters.
Parameters:
-
request_state— State of requests to be fetched. -
request_type— Type of requests to be fetched. -
client_id— Requests having the given client_id will be listed. -
start,page_size— Parameters for pagination purposes. -
max_results— Length of the list. -
max_time— Max. time to complete the request.
Returns:
A KeyRequestInfoCollection object. All the key requests satisfying the parameters passed can be found in the entries list of the collection object.
Exceptions:
PKIException — Thrown in case of an internal failure.
Example Usage:
On calling the method list_requests('complete', 'symkeyGenRequest'),
The following http GET request is sent to the server -
http://localhost:8443/kra/rest/agent/keyrequests?requestState=complete&requestType=symkeyGenRequest
for which the response consists of list of entries of KeyRequestInfo objects with information about the keyURL, status, type and the requestURL.
get_request_info(self, request_id)
Return a KeyRequestInfo object for a specific request by sending a GET request to /kra/rest/agent/keyrequests/<request_id>
Parameters:*
-
request_id— An instance of a RequestId object with the value set to the request id of the request to be retrieved.
Returns:
A KeyRequestInfo objects with information about the keyURL, status, type and the requestURL of the key request.
Exceptions:
-
BadRequestException— if request_id is null -
PKIException— Thrown when there is an internal failure such as db connectivity or retrieval. -
RequestNotFoundException— Thrown when there is no request for the given request id.
create_request(self, request)
Submit an archival, recovery or key generation request to the DRM.
The create_request method call sends a POST request to the URL, /kra/rest/agent/keyrequests, with a recovery/archival/symmetric key generation request as payload.
Parameters:
-
request— is either aKeyArchivalRequest,KeyRecoverRequestorSymKeyGenerationRequest.
To perform a recovery request, a KeyRecoverRequest object has to be created similar to the one mentioned in the retrieve_key() method call of the KeyResource.
To perform an archival request, a KeyArchivalRequest object has to be created with the following values added as its attributes:
-
clientID- Client specified Identifier -
dataType- Type of the secret data. -
wrappedPrivateData- Secret or passphrase wrapped using the KRA transport cert. -
keyAlgorithm- Type of algorithm used in case the secret is a key, for a passphrase it is null -
keySize- Size of the key. (Incase of a pasphrase it is 0)
To perform a symmetric key generation request, a SymKeyGenerationRequest has to be created with the following values added to its attribute list.
-
client_id— Client specified identifier -
keySize— Size of the key to be generated. -
keyAlgorithm— Algorithm to be used to generate the key. -
keyUsage— Description of the usage of the key.
Returns:
A KeyRequestResponse object which contains the KeyRequestInfo and the KeyData objects generated by the request.
Exceptions:
-
BadRequestException— For request object with invalid inputs.
Example Usage:
The json representation of a key archival request for storing a passphrase looks like:
{
"Attributes": {
"Attribute": [
{
"name": "wrappedPrivateData",
"value": "oIIBMjCCAS6hFAYIKoZIhvcNAwcECG3eAXHagc30goIBAQBHxhOXxT64iSa/5jYn\r\n
i9W7+X3wT+BeNIYmpfb1U1S8EB7oFa5jFJg5hJ0jWWjJ31KJTThFBytQcbGlaGZe\r\n
FTizf+eNMhRdJyjbaJgT2N+VMlTAQErtiwhH2DygNodIE9qMI6sso/tyd8m2PgsF\r\n
JPRSzy9PUYDZejWFzKIV8lK0phFRfYpTw+aKkhWTF6yJu2Ip4fIO6Ole/6kkJqbl\r\n
jojCNLqOHOB2SJtWmMPow+CKPGa1QAKp5oJ5+YDkp9fXyO76J0p3CoeKADd09y8g\r\n
zKHR8H3XcBVgHAbJ/Oy3Ew4xQNqdjephPk4OO0uZ0UGMmrc3oPnHmjh0UqWFNwoh\r\n
314lAxEAZUdfG/M9ESo850RJ8qEgdw==\r\n"
},
{
"name": "clientID",
"value": "UUID: 123-45-6789 RKEK Fri Feb 14 11:45:13 EST 2014"
},
{
"name": "dataType",
"value": "passPhrase"
},
{
"name": "keyAlgorithm",
"value": null
},
{
"name": "keySize",
"value": "0"
}
]
},
"ClassName":"com.netscape.certsrv.key.KeyArchivalRequest"
}
For which the response consisting the KeyRequestResource object looks like:
{
"RequestInfo": {
"requestType": "securityDataEnrollment",
"requestStatus": "complete",
"requestURL": "https://localhost:8443/kra/rest/agent/keyrequests/25",
"keyURL": "https://localhost:8443/kra/rest/agent/keys/8"
}
}
approve_request(self, request_id)
Approves a request with the given RequestId object.
A POST request is submitted to the url:
/kra/rest/agent/keyrequests/<requestId>/approve
Returns the HTTP response object.
reject_request(self, request_id)
Rejects a request with the given RequestId object.
A POST request is submitted to the url:
/kra/rest/agent/keyrequests/<requestId>/reject
Returns the HTTP response object.