Difference between revisions of "DRM Symmetric Key REST Design"

From Dogtag
Jump to: navigation, search
Line 12: Line 12:
 
** wrappedPrivateData=<url encode wrapped key/passphrase> - This is the actual security data encrypted by the created symmetric key.
 
** 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)
 
** 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?
+
** 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 ====
 
==== Output ====
 
* output is xml/json with the following fields:
 
* output is xml/json with the following fields:
Line 30: Line 31:
 
* audit all operations/auth/authz
 
* audit all operations/auth/authz
 
* Get the KRA request queue and generate a new Request object.
 
* Get the KRA request queue and generate a new Request object.
** req = queue.newRequest(KRAService.ARCHIVAL) ?
+
** req = queue.newRequest(IRequest.SECURITY_DATA_ENROLLMENT_REQUEST -> security_data_enrollment)
 
** using req.setExtData(): set the fields as follows
 
** using req.setExtData(): set the fields as follows
*** requestType: "Security Data Archival?"
+
*** requestType: IRequest.SECURITY_DATA_ENROLLMENT_REQUEST -> security_data_enrollment
 
*** extdata-drm_trans_des_key: transWrappedSessionKey
 
*** extdata-drm_trans_des_key: transWrappedSessionKey
 
*** extdata-requestid: not set - generated by newRequest() call.
 
*** extdata-requestid: not set - generated by newRequest() call.
Line 43: Line 44:
 
** reqID = req.getRequestID().toString().  This will be returned.
 
** reqID = req.getRequestID().toString().  This will be returned.
 
* Immediately Process the request
 
* Immediately Process the request
** queue.processRequest(req)
+
** 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.
** 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:  
 
* Get the key_id from the request record:  
 
** keyId = req.getExtData(key_id)
 
** keyId = req.getExtData(key_id)
Line 54: Line 54:
 
==== Input ====
 
==== Input ====
 
* Input will be xml or json
 
* Input will be xml or json
* clientID=<value> - Optional way to locate the key to be recovered.
+
* clientID=<value> - Optional way to locate the key to be recovered. (first option)
* serialNumber=<value> - Optional way to locate the key to be recovered.
+
* serialNumber=<value> - Optional way to locate the key to be recovered. (second option)
 
   
 
   
 
==== Output ====
 
==== Output ====
Line 74: Line 74:
 
* checks authorization of the request based on an acl for this operation "certServer.kra.recover.request (submit)". Submit allowed for DRM agents.  
 
* 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.
 
* Get the KRA request queue and generate a new Request object.
** req = queue.newRequest(KRAService.SECURITY_DATA_RECOVERY)  ?
+
** req = queue.newRequest(IRequest.SECURITY_DATA_RECOVERY -> security_data_recovery)   
 
** using req.setExtData(): set the fields as follows:
 
** using req.setExtData(): set the fields as follows:
 
*** clientID = clientID
 
*** clientID = clientID
Line 80: Line 80:
 
*** userid of agent creating recovery request
 
*** userid of agent creating recovery request
 
*** extdata-requestID = not set, generated by newRequest() command
 
*** extdata-requestID = not set, generated by newRequest() command
*** approvers? add agent creating request
+
*** extdata-approvingagents = agent
 
* call queue.processRequest(req)
 
* call queue.processRequest(req)
 
** If nAgents is set to 1 (where is this set?), then the request is set in the approved state.
 
** If nAgents is set to 1 (where is this set?), then the request is set in the approved state.

Revision as of 02:54, 5 December 2011

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

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 DRM agents.
  • Get the KRA request queue and generate a new 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 (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.