Overview
Apstrata enforces request layer authentication. This section provides an explanation of how it works.
There are three methods for authenticating apstratabase requests:
1- Default signature: This is the most secure method of authentication because it requires hashing all content of a request along with the secret of the account or the password of the user and then sending the hash.
2- Simple signature: This is the easiest method of authentication. It requires hashing a few select parameters along with the secret of the account or the password of the user and then sending the hash. It is recommended for testing and for applications that do not have access to all parameters, like files, in a request.
3- Token-based authentication: This is the recommended method of authentication for applications that make most requests with apstrata users, as opposed to owners, for use with SSL encrypted connections over HTTP POST. It provides a similar experience to sessions since a token is generated and renewed over a period of time, without the need to generate a signature for every request.
The authentication roadmap for the apstrata database includes optional replay prevention.
Description
apstrata services only accept authenticated requests. Authenticating an apstrata service request means either sending it with the apsws.authSig parameter or a valid value for the apsdb.token parameter. Creating the signature parameter for owner requests requires the developer to know their authentication key (apsws.authKey) and their authentication secret. Creating the signature parameter for user requests requires the developer to know their authentication key (apsws.authKey), the user login, and the user password. generating tokens requires generating a user request to VerifyCredentials in order to generate a token and then sending the token with every consecutive request in order to authenticate it. The token needs to be constantly renewed and requires re-authentication when its lifetime expires. The authentication key and the secret will be provided upon registration. The user login and the password are chosen when creating an apstrata user. Note that the secret works as a password for accessing our services suite and hence your data.
Never reveal your authentication secret to a third party, an apstrata database affiliate will never ask for your secret. In case you feel that your authentication secret has been compromised, you can create a new one.
Two types of signatures exist, one which is more secure and complex to construct, and another version which is simpler to construct but less secure.
Default Signature Type
By default, apstrata database will use a secure signature which depends on the data sent. It involves most of the data in the request, and it is calculated using the secret authentication key.
To create a signature:
1. Create a standardized string of the query string to be hashed
a. URL encode both the parameters and their values
i. In case of an attachment, the value would be the URL encoded hexadecimal representation of the MD5 hash of the file bytes (all capital letters)
ii. Example:
MessageDigest messageDigest = MessageDigest.getInstance("MD5");
FileInputStream fis = new FileInputStream(filePath);
byte[] bytes = new byte[4096];
int readPos = fis.read(bytes);
while (readPos != -1) {
md5.update(bytes, 0, readPos);
readPos = fis.read(bytes);
}
String hashedValue = hexToString(messageDigest.digest()).toUpperCase();
b. Separate the encoded parameters and their values by the equals sign
c. Sort the parameters and their values by natural byte ordering (follow example below)
d. Append the name value pairs with an ampersand
2. Create the string to be hashed:
String to hash = HTTPVerb (Upper case) + "\n" + encoded Http URL + "\n" + standardized string
The HTTP URL will include the scheme, host, port (if present), and the path. It will not include any of the query strings.
3. Calculate the HMAC-SHA1 hash string using the secret authentication key
Please note that spaces and asterisk should be encoded as %20 and %2A respectively
Example:
POST http://sandbox.apstrata.com/apsdb/rest/[authentication_key]/CreateStore Host: host ......... apsdb.store=myStore&additionalParam1=value1&apsws.time=1234567890
Sorted parameters
additionalParam1=value1 apsdb.store=myStore apsws.time=1234567890
String to hash
"POST\n http%3A%2F%2Fsandbox.apstrata.com%2Fsandbox%2Dapsdb%2Frest%2Fauthenticationkey%2FCreateStore\n additionalParam1=value1&apsdb.store=myStore&apsws.time=1234567890"
Assuming that the secret authentication key is “secret”
HMAC-SHA1("secret", "POST\n http%3A%2F%2Fsandbox.apstrata.com%2Fsandbox%2Dapsdb%2Frest%2FmyKey%2FCreateStore\nadditionalParam1=value1&apsdb.store=myStore&apsws.time=1234567890")
Example (PHP)
POST http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/CreateStore
Host: host
.........
apsdb.store=myStore&additionalParam1=value1&apsws.time=1234567890
$paramArr = array();
array_push(rawurlencode("apsws.time") . "=" . rawurlencode("1234567890"));
array_push(rawurlencode("apsdb.store") . "=" . rawurlencode("myStore"));
array_push(rawurlencode("additionalParam1") . "=" . rawurlencode("value1"));
sort($paramArr);
$stringToSign = "";
for($i = 0; $i <count($paramArr); $i++)
{
$stringToSign .= $paramArr[$i];
If($i <count($paramArr) - 1)
{
$stringToSign .= "&";
}
}
$stringToSign = "POST" . "\n" . rawurlencode (http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/CreateStore)
. "\n" . $stringToSign;
// assuming that the secret authentication key has the value "secret"
$signature = hash_hmac("sha1", $stringToSign, "secret");
Simple Signature Type
In order to use the simple signature, requests should specify the authentication mode by setting the value of the parameter “apsws.authMode” to “simple”. Each request must also specify the action name and the timestamp (apsws.time). A URL example would be:
http://sandbox.apstrata.com/apsdb/rest/ [authenticationkey]/CreateStore ?&apsws.time=1234567890&apsws.authMode=simple
First, construct the text to hash by doing:
ValueToHash = [timestampValue][Authentication Key value][action name][secret]
Example:
secret = qwerty apsws.authKey = asdfg apsws.time = 1234567890 action = CreateStore valueToHash= 1234567890asdfgCreateStoreqwerty
The values are appended without a separator.
The signature is then created by generating the Md5 hash of this text and using Hexadecimal characters:
apsws.authSig = Md5hashFunction(valueToHash)
Please keep in mind that simple signature is secure only when used over a secure connection. It is highly recommended to use SSL connection when using a simple signature to avoid data interception and replay attacks. If you don’t want to use SSL connection, it is advisable to use the default signature.
Token-based authentication
A token can be used to authenticate a user in place of a signature. This allows the creation of applications that do not need access to the users password which is required for signature generation. Tokens provide a layer of simplicity, but must obey the following restrictions:
1. Token-based authentication is enabled for user requests only. Owner requests must use signatures.
2. Token-based authentication is enabled under secure (https) connections only.
Tokens can be created or renewed using VerifyCredentials and can then be passed as a parameter to requests instead of the signature.
When no longer needed, tokens can be deleted and cleared using DeleteToken
Authenticating Requests for Users
Requests can be authenticated with user credentials (username/password). In order to create a user belonging to a customer: A user must be created using the SaveUser API action with a request signed by the customer's authentication key and authentication secret; a username and password will be used to create the user.
Signing a request with the customer's authentication key, and one of his users' username and password (a hash of the password) can be used to allow rich client applications to make requests to apstrata database without giving out the customer's secret.
Default Signature: Follow the steps in the Request Authentication section, and set the parameter apsws.authKey to be the username of the created user. Then calculate the HMAC-SHA1 hash string using the MD5 hash of the created user’s password.
Token-based Authentication: Follow the steps in the Request Authentication section about token-based authentication which is only allowed for users.
Simple Signature Type: Follow the steps in the Request Authentication section, and set the parameter apsws.authKey to be the username of the created user. Then use the MD5 hash of the created user’s password when creating the signature.
By using the user's username and password:
ValueToHash = [timestampValue][username][action name] [Md5hashFunction(new user password)]
Requests signed using the authKey and the sharedSecret without a username are called "owner" requests where owner is considered to be the db owner i.e. the apstrata database customer who holds the shared secret.
Note: ACL checking is skipped when the request is performed by owner.