HELP TOPIC: "8.D REST API – Authorization"

Genboree requires users to authenticate themselves with their username and password when using the web site interface; it also verifies that the user is authorized to view or even alter data to which they have access.

The REST API is no different—it too requires authentication information and verifies the user is authorized to operate on the resource indicated in the URL. The API does this in a careful and secure way. The client creates a token using secret information (the user's password) that only it has, and which the server can verify the client has (without the server actually needing to store the user's password).

The REST API requires 3 parameters be appended (in any order) to the end of all resource URLs for authentication/authorization:

1. gbLogin

Login name of a registered Genboree user with sufficient access to perform the method on the resource.

2. gbTime

Current POSIX time (a.k.a. epoch time or UNIX time) as an integer. This means your computer's time must be reasonably correct (say, within a few hours). This parameter helps avoid replay attacks.

3. gbToken

The core of the authentication scheme, the token is a single-use, location- and time-specific string resulting from a one-way SHA1 digest of the rsrcURI, a user & password digest, and the 'current' time. Genboree will use the 2 other parameters above and the resource URI to compute the same token on the server side.

NOTE: Recall that the rsrcURI is the full REST URL, minus the 3 authorization parameters described above.

The token computation is straight-forward. It requires the ability to compute SHA1 digests as hexidecimal strings, which is available as part of standard or extension libraries of most modern languages.

1. Let {rsrcURI} be the API URL so far, without the 3 required authentication parameters on the end.
2. Observe that, in all cases, {rsrcURI} contains the query-string delimiter '?' because minimally, we will be adding the 3 authentication parameters.
3. Compute {usrPwDigest} = SHA1({gbLogin} + {userPassword})
4. Let {gbTime} be the current POSIX time, as a string.
5. Compute {gbToken} = SHA1({rsrcURI} + {usrPwDigest} + {gbTime})
6. Append the 3 required parameters to {rsrcURI} to get the full API URL:
   
   {fullURL} = {rsrcURI} + '&gbLogin=' + {gbLogin} + '&gbTime=' + {gbTime} + '&gbToken=' + {gbToken}

NOTE: The SHA1() function above is assumed to output the digest value as a 40-digit hexidecimal string.

• · The token is single-use as a protection against replay attacks. Subsequent requests, even do-overs of failed requests, will need to compute a new token.
• · Incorporating the time into the token helps encourage single-use on the client side and speedy verification on the server side.
• · The token is location-specific; i.e. it is resource-specific. You can't use tokens for resources they weren't intended for.
• · The secret information the client has is the user's password. Genboree doesn't need to store that password, but can instead store the SHA1 digest of the username + password. This increases security in the face of intrusion and in the face of brute-force password attacks. Hence the need to calculate SHA1({gbLogin} + {userPassword}). This double-digesting of the secret information is also known to protect against clever offline attacks of the SHA1 digest, since not enough of the internal state of the digest can be partially pre-computed based on the known information to be useful.
• · Be careful with the user's password in your client-side programs. Minimally: avoid putting the password on the command line when calling your program since it could be seen by anyone with a process monitor (e.g. 'top', 'ps'), avoid hard-coding passwords in your application code since it can be read by viewing the source or dumping all the strings from the binary (in the case of C/C++, say), if you put the password in a configuration file or database make sure only you can read (and write) the file/database, etc.