PKI Key Request Python API

Overview

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:

• pki.key

KeyClient Class

Listing key requests

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.

Getting key request info

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.

Creating a key request

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 a KeyArchivalRequest,KeyRecoverRequest or SymKeyGenerationRequest.

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"
    }
}

Approving a request

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.

Rejecting a request

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.

Canceling a request

cancel_request(self, request_id)

Cancels a request with the given RequestId object.

A POST request is submitted to the url:

/kra/rest/agent/keyrequests/<requestId>/cancel

Returns the HTTP response object.