DRM Symmetric Key REST Design

From Dogtag
Revision as of 21:57, 28 November 2011 by Alee (talk | contribs)

Jump to: navigation, search

Requirements

Design

Archiving a Symmetric Key or Passphrase

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 DRM'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)
    • Question: do we care about ECC here/ or any algorithms?

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 DRM agents.
  • audit all operations/auth/authz
  • Get the KRA request queue and generate a new Request object.
    • req = queue.newRequest(KRAService.ARCHIVAL)  ?
    • using req.setExtData(): set the fields as follows
      • requestType: "Security Data Archival?"
      • 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)
    • The relevant serviceRequest() method will be called (where will this be?), 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

POST /pki/keyrequest/recover

Input

  • Input will be xml or json
  • clientID=<value> - Optional way to locate the key to be recovered.
  • serialNumber=<value> - Optional way to locate the key to be recovered.

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 DRM agents.
  • Get the KRA request queue and generate a new Request object.
    • req = queue.newRequest(KRAService.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
      • approvers? add agent creating request
  • call queue.processRequest(req)
    • If nAgents is set to 1 (where is this set?), then the request is set in the approved state.
    • key record is looked up and ID is stored in the recovery request record.
  • Recovery request is generated. If nAgents is set to 1 (where is this set?), then the request is set in the approved state.
  • 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.

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 DRM's transport cert.

Output

  • 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 DRM 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.