Unclear documentation for "Normalized data for HTTP requests"

[hvge]

For this time, I found out just a small issue in the signature.md documentation. There are two errors actually:

1. Your documentation doesn't reflect actual reference implementation for data normalization
2. The usage of "REQUEST_DATA" variable doesn't make sense

1. Implementation vs documentation

Your current implementation does something like this:

return (httpMethod != null ? httpMethod.toUpperCase() : "GET")
                + "&" + requestUriHash
                + "&" + applicationSecret
                + "&" + (nonce != null ? nonce : "")
                + "&" + dataBase64;

but the documentation says:

REQUEST_DATA = ${REQUEST_METHOD}&${REQUEST_URI_IDENTIFIER_HASH}&${NONCE}&${REQUEST_BODY}
DATA = ${REQUEST_DATA}&${APPLICATION_SECRET}

You can clearly see, that the APPLICATION_SECRET should be appended at the end of the normalized string, but the reference implementation has secret somewhere in the middle of the normalized string.

2. The usage of "REQUEST_DATA"

There's unclear usage of REQUEST_DATA term. It is used as a part of calculation (see that concatenation above) and also as a part of GET/POST data normalization. For GET, for example documentation says:

REQUEST_DATA = BASE64.encode(CONCAT_ALL(CONCAT(KEY[j], VALUE[j], "="), "&", j = 0 .. N))

...and that would revert all that concatenation explained before.

Solution

I would recommend to simplify the documentation to something like this (if the order of concatenation is correct):

SIGNED_DATA = ${REQUEST_METHOD}&${REQUEST_URI_IDENTIFIER_HASH}&${NONCE}&${REQUEST_DATA}&${APPLICATION_SECRET}

Where the REQUEST_DATA is that B64 encoding for POSTs or that key-value normalization for GETs.

[petrdvorak]

The documentation is correct and issue will be fixed with fixing #25.