Difference between revisions of "DRM Symmetric Key REST Design"

From Dogtag
Jump to: navigation, search
Line 3: Line 3:
  
 
=== Archiving a Symmetric Key or Passphrase ===
 
=== Archiving a Symmetric Key or Passphrase ===
POST /pki/keyrequest/archive
+
'''POST /pki/keyrequest/archive'''
 
==== Input ====
 
==== Input ====
 
* factory URL to create archival requests
 
* factory URL to create archival requests
Line 25: Line 25:
 
** include an error string (error="") for error conditions as needed, such as processing errors in creating request, errors in processing request  
 
** include an error string (error="") for error conditions as needed, such as processing errors in creating request, errors in processing request  
  
==== Operation: ====
+
==== Operation ====
 
* authenticates the agent issuing the request.  Agent must provide a client cert.
 
* 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.  
 
* 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.
 
* Get the KRA request queue and generate a new Request object.
 
** req = queue.newRequest(KRAService.ARCHIVAL)  ?
 
** req = queue.newRequest(KRAService.ARCHIVAL)  ?
Line 40: Line 41:
 
*** clientID: clientID
 
*** clientID: clientID
 
* Get the request ID
 
* Get the request ID
** reqID = req.getRequestID().toString().  This will be returned as self reference.
+
** reqID = req.getRequestID().toString().  This will be returned.
 
* Immediately Process the request
 
* Immediately Process the request
 
** queue.processRequest(req)
 
** queue.processRequest(req)
Line 47: Line 48:
 
** keyId = req.getExtData(key_id)
 
** keyId = req.getExtData(key_id)
 
* construct the urls to be returned - and return relevant status.
 
* 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 ====
 +
* output is xml/json with the following fields:
 +
** status=201 (Created)
 +
** reqURL = https://hostname/pki/keyrequest/$request_id   
 +
** keyURL = https://hostname/pki/key/$key_id
 +
 +
==== 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.

Revision as of 21:57, 28 November 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)
    • 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.