Identity/AttachedServices/KeyServerProtocol: Difference between revisions

→‎Creating a Session: explain new shared-tokenID way to use authTokens
(→‎Creating a Session: explain new shared-tokenID way to use authTokens)
Line 169: Line 169:
[[File:PICL-IdPAuth-encrypt-sessionToken.png|Decrypting the sessionToken and keyFetchToken]]
[[File:PICL-IdPAuth-encrypt-sessionToken.png|Decrypting the sessionToken and keyFetchToken]]


The authToken is used to derive four values:
For calls which accept an authToken, the client uses authToken to derive three values:


* tokenID
* tokenID
* reqHMACkey
* reqHMACkey
* requestKey
The client uses tokenID and reqHMACkey for a HAWK (https://github.com/hueniverse/hawk/) request to the "POST /session/create" API, using tokenID as "credentials.id" and reqHMACkey as "credentials.key". The server uses tokenID to look up the corresponding token, then derives reqHMACkey to validate the request.
Each authToken-using call then derives additional API-specific values from requestKey. /session/create uses two derived values:
* respHMACkey
* respHMACkey
* respXORkey
* respXORkey


The client uses tokenID and reqHMACkey for a HAWK (https://github.com/hueniverse/hawk/) request to the "POST /session/create" API, using tokenID as "credentials.id" and reqHMACkey as "credentials.key". The server uses tokenID to look up the corresponding token, then derives reqHMACkey to validate the request. The server allocates sessionToken and keyFetchToken, concatenates them, encrypts the pair by XORing it with the derived respXORkey, and attaches a MAC generated with respHMACkey. The encrypted MACed bundle is returned to the client.
 
When the server receives a valid /session/create request, it allocates sessionToken and keyFetchToken, concatenates them, encrypts the pair by XORing it with the derived respXORkey, and attaches a MAC generated with respHMACkey. The encrypted MACed bundle is returned to the client.


The client recomputes the MAC, compares it (throwing an error if it doesn't match), extracts the ciphertext, XORs it with the derived respXORkey, then splits it into the separate keyFetchToken and sessionToken values.
The client recomputes the MAC, compares it (throwing an error if it doesn't match), extracts the ciphertext, XORs it with the derived respXORkey, then splits it into the separate keyFetchToken and sessionToken values.
Line 182: Line 190:
Each authToken is single-use: once a successful request has been made with it, the authToken and its corresponding ID is removed from the server's memory, and subsequent attempts to use it will return a "no such token" error. The token is consumed even if the request fails (e.g. the MAC did not match).
Each authToken is single-use: once a successful request has been made with it, the authToken and its corresponding ID is removed from the server's memory, and subsequent attempts to use it will return a "no such token" error. The token is consumed even if the request fails (e.g. the MAC did not match).


Since the authToken can be used by multiple APIs, the server ought to maintain a table that maps the various flavors of tokenIDs (computed for the different APIs) back to the authToken. When a HAWK request with one of these IDs appears, it should look up the tokenID in the corresponding table, retrieve the authToken, compute the associated values (reqHMACkey, etc), create the response, then delete the entire row.
The authToken can be used (once) by multiple APIs. The server only needs to maintain one table mapping tokenID to authToken, because all these APIs share the same method of deriving a tokenID and reqHMACkey from the authToken.
 
When a HAWK request appears, it should look up the tokenID in this table, retrieve the authToken, recompute reqHMACkey and requestKey, validate the request, delete the table entry, then hand the HTTP request and requestKey to the specific API handler. That handler should derive the API-specific values (respHMACkey, respXORkey, etc) to process the request or construct the response.


The server can support multiple sessions per account (typically one per client device, plus perhaps others for account-management portals). There can also be multiple outstanding keyFetchTokens. The sessionToken lasts forever (until revoked by a password change or explicit revocation command), and can be used an unlimited number of times. The keyFetchToken expires after 60 seconds, and is single-use.
The server can support multiple sessions per account (typically one per client device, plus perhaps others for account-management portals). There can also be multiple outstanding keyFetchTokens. The sessionToken lasts forever (until revoked by a password change or explicit revocation command), and can be used an unlimited number of times. The keyFetchToken expires after 60 seconds, and is single-use.
Confirmed users
471

edits