HMAC Authentication
Elgg’s RESTful API framework provides functions to support a HMAC signature scheme for API authentication. The client must send the HMAC signature together with a set of special HTTP headers when making a call that requires API authentication. This ensures that the API call is being made from the stated client and that the data has not been tampered with.
The HMAC must be constructed over the following data:
The public API key identifying you to the Elgg api server as provided by the APIAdmin plugin
The private API Key provided by Elgg (that is companion to the public key)
The current unix time in seconds
A nonce to guarantee two requests the same second have different signatures
URL encoded string representation of any GET variable parameters, eg
method=test.test&foo=bar
If you are sending post data, the hash of this data
Some extra information must be added to the HTTP header in order for this data to be correctly processed:
X-Elgg-apikey - The public API key
X-Elgg-time - Unix time used in the HMAC calculation
X-Elgg-nonce - a random string
X-Elgg-hmac - The HMAC as base64 encoded
X-Elgg-hmac-algo - The algorithm used in the HMAC calculation
If you are sending POST data you must also send:
X-Elgg-posthash - The hash of the POST data
X-Elgg-posthash-algo - The algorithm used to produce the POST data hash
Content-type - The content type of the data you are sending (this can be
application/x-www-form-urlencoded
ormultipart/form-data
)Content-Length - The length in bytes of your POST data
Elgg provides a sample API client that implements this HMAC signature: \Elgg\WebServices\ElggApiClient
. It serves as a good
reference on how to implement it.
Supported hashing algorithms
sha256
: recommendedsha1
: fast however less securemd5
: weak and will be removed in the future
POST hash calculation
When sending the POST data as Content-Type: application/x-www-form-urlencoded;
the post hash needs to be calculated
over all the post data using one of the supported hashing algorithms.
When sending the POST data as Content-Type: multipart/form-data;
the post hash needs to be calculated
over an empty string.
The result of the hashing needs to be reported in the X-Elgg-posthash
header and the used hashing algorithm must be
reported in the X-Elgg-posthash-algo
header.
Warnung
Since the POST hash isn’t calculated when using Content-Type: multipart/form-data;
only use this when calling
APIs that need an file input.
HMAC hash calculation
The overall HMAC needs to be calculated over the following data (in order) using the API secret as the HMAC secret and with one of the supported hashing algorithms:
a UNIX timestamp, report this timestamp in the
X-Elgg-time
headera random string, report this string in the
X-Elgg-nonce
headerthe public API key, report this API key in the
X-Elgg-apikey
headerthe url query string (for example
method=test.test&foo=bar
)when the request is a POST add the
posthash
as reported in theX-Elgg-posthash
header
The resulting string needs to be base64 encoded and then url encoded and be reported in the X-Elgg-hmac
header.
The used hashing algorithm needs to be reported in the X-Elgg-hmac-algo
.
Hashing cache
For security reasons each HMAC hash needs to be unique, all submitted hashes are stored for 25 hours to prevent reuse.