KRA Symmetric Key REST API Design - dogtagpki/pki GitHub Wiki

Archiving a Symmetric Key or Passphrase

URL

POST /pki/keyrequest/archive

Input

  • factory URL to create archival requests

  • input is xml or json containing the following fields:

    • Envelope is SecurityData

    • clientID=<string client id> - client specified string id for this piece of data. The client may end up searching on this string.

    • transWrappedSessionKey=<url encoded wrapped key> - This client generated session key will be wrapped with the KRA’s transport cert.

    • wrappedPrivateData=<url encode wrapped key/passphrase> - This is the actual security data encrypted by the created symmetric key.

    • dataType=<type of data> - String representation of the type of data, "symmetricKey", "passPhrase" or "AsymmetricKey" (for client convenience)

    • Note: We do not care about ECC at this stage. Our proposed RSA transport key wrapping scheme should work just fine even if we want to archive an ECC key itself. The scenario that we have to worry about down the road is when we do actual ECC wrapping instead of RSA. The wrap symmetric key with transport public key thing would not be available to us and a different approach would be needed. But this is not likely to be an issue for a long time.

Output

Errors

  • status = 307 - Temporary Redirect to authentication page if no client cert provided.

  • status = 401 - Unauthorized (if authorization fails

  • status = 500 - server errors

    • include an error string (error="") for error conditions as needed, such as processing errors in creating request, errors in processing request

Operation

  • authenticates the agent issuing the request. Agent must provide a client cert.

  • checks authorization of the request based on an acl for this operation "certServer.kra.archive.request (submit)". Submit allowed for KRA agents.

  • audit all operations/auth/authz

  • Get the KRA request queue and generate a new Request object.

    • req = queue.newRequest(IRequest.SECURITY_DATA_ENROLLMENT_REQUEST → security_data_enrollment)

    • using req.setExtData(): set the fields as follows

      • requestType: IRequest.SECURITY_DATA_ENROLLMENT_REQUEST → security_data_enrollment

      • extdata-drm_trans_des_key: transWrappedSessionKey

      • extdata-requestid: not set - generated by newRequest() call.

      • ext-data-keyrecord: not set - stored by server when key is stored

      • ext-data-keysize: not set

      • extdata-wrappeduserprivate: wrappedPrivateData

      • dataType: dataType

      • clientID: clientID

  • Get the request ID

    • reqID = req.getRequestID().toString(). This will be returned.

  • Immediately Process the request

    • queue.processRequest(req) - This results in a state engine setting the request to "approved", and the code calling the relevant serviceRequest() method in SecurityDataArchivalService. As a result of this, the key will be archived and the key_id will be updated in the request record.

  • Get the key_id from the request record:

    • keyId = req.getExtData(key_id)

  • construct the urls to be returned - and return relevant status.

Recovering a symmetric key/ passphrase

URL

POST /pki/keyrequest/recover

Input

  • Input will be xml or json

  • clientID=<value> - Optional way to locate the key to be recovered. (first option)

  • serialNumber=<value> - Optional way to locate the key to be recovered. (second option)

Output

Errors

  • status = 307 - Temporary Redirect to authentication page if no client cert provided.

  • status = 401 - Unauthorized (if authorization fails

  • status = 410 - Gone. Key does not exist.

  • status = 500 - server errors

    • include an error string (error="") for error conditions as needed, such as processing errors in creating request, errors in processing request

Operation

  • authenticates the agent issuing the request. Agent must provide a client cert.

  • checks authorization of the request based on an acl for this operation "certServer.kra.recover.request (submit)". Submit allowed for KRA agents.

  • Get the KRA request queue and generate a new Recovery Request object.

    • req = queue.newRequest(IRequest.SECURITY_DATA_RECOVERY → security_data_recovery)

    • using req.setExtData(): set the fields as follows:

      • clientID = clientID

      • extdata-serialnumber = serialNumber

      • userid of agent creating recovery request

      • extdata-requestID = not set, generated by newRequest() command

      • extdata-approvingagents = agent

  • call queue.processRequest(req)

    • If nAgents is set to 1, then the request is set in the approved state. Currently, this is set by a global in CS.cfg: kra.noOfRequiredRecoveryAgents=1 which is used for the asynchronous recovery mechanism for asymmetric keys. We may want something more fine grained to allow symmetric keys and passphrases to be treated differently from asymmetric keys, for instance.

    • key record is looked up and ID is stored in the recovery request record.

  • Get the request ID

    • reqID = req.getRequestID().toString(). This will be returned in the response.

  • Get the key ID

    • keyID= req.getExtData(key_id)

  • Construct URLs to be returned, and return relevant status.

  • Need to think about nonces or other CSRF-foiling mechanism.

URL

GET /pki/key/$key_id

Input

  • Input will be xml or json

  • requestID=<value> - ID of recovery request

  • transWrappedSessionKey=<url encoded wrapped key> - This client generated session key wrapped with the KRA’s transport cert.

Output

  • output is xml/json

  • status: 200

  • self referential URL ?

  • wrappedPrivateData=<url encoded wrapped key/passphrase> - This is the returned actual security data archived in the chosen record.

Errors

  • status = 307 - Temporary Redirect to authentication page if no client cert provided.

  • status = 401 - Unauthorized (if authorization fails)

  • status = 401 - Unauthorized (if request originator != agent getting key)

  • status = 401 - Unauthorized (if request is not in approved state)

  • status = 410 - Gone. Recovery request does not exist.

  • status = 410 - Gone. Key does not exist.

  • status = 500 - server errors

    • include an error string (error="") for error conditions as needed, such as processing errors in creating request, errors in processing request

Operation

  • authenticates the agent issuing the request. Agent must provide a client cert.

  • checks authorization of the request based on an acl for this operation "certServer.kra.recover.key (read)". Read allowed for KRA agents.

  • Get the KRA request and confirm that the request exists and that the originator = agent

  • Confirm that request is in approved state.

  • Get keyID from request.

  • retrieve wrappedKey = getWrappedKey(req, transWrappedSessionKey)

  • return wrapped key.

Listing/ Searching for a Key

URL

GET /pki/keys/

Input

  • We could specify just a search string here, or we could provide specific optional fields that could be filled with patterns

  • Example of fields: clientID, status (active/inactive/all), keyID

  • We would expect IPA to do queries like clientID=foo & status=active

  • Need to ensure there is no sql-like injection here

Output

  • status 200, 204 (if not keys match criteria)

  • URLs and some basic information for keys matching search criteria, such as:

    • URL for key

    • client ID for key

    • status of key

Errors

  • status = 307 - Temporary Redirect to authentication page if no client cert provided.

  • status = 401 - Unauthorized (if authorization fails)

  • status = 500 - server errors

    • include an error string (error="") for error conditions as needed, such as errors in doing search or processing search criteria

Operation

  • authenticates the agent issuing the request. Agent must provide a client cert.

  • checks authorization of the request based on an acl for this operation "certServer.kra.list.key (read)?". Read allowed for KRA agents.

  • search the database for relevant keys, based on search criteria. Get clientID and status.

  • Generate urls for response.

Changing key state to active/inactive

URL

PUT /pki/key/$id/status

Input

  • new_status (active/ inactive)

  • $id - key ID of key

Output

  • status: 204 (No content)

Errors

  • status = 307 - Temporary Redirect to authentication page if no client cert provided.

  • status = 401 - Unauthorized (if authorization fails)

  • status = 410 - Gone (if key does not exist)

  • status = 500 - server errors

Operation

  • authenticates the agent issuing the request. Agent must provide a client cert.

  • checks authorization of the request based on an acl for this operation "certServer.kra.status.key (update)?". Read allowed for KRA agents.

  • modify the relevant key’s status.

Tip
 To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis.
⚠️ **GitHub.com Fallback** ⚠️