Skip to content

PKI Key Request Python API

Endi S. Dewata edited this page Dec 17, 2020 · 2 revisions

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:

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.

Clone this wiki locally