Digital signatures (txtSignature)
Requests to these API web services for applications require digital signatures, generated using a cryptographic key provided to you for that purpose. The signing process combines some parameters (different for each API) and the key together using an encryption algorithm. The resulting unique signature allows our web services to verify that any site generating requests using your application ID is authorized to do so.
Note: The signature is unique per URL, ensuring that requests that use your application ID cannot be modified without requiring a new signature to be generated.
How do I get my signing key?
Your cryptographic request-signing key will be issued with your application ID and is a "secret shared key" between you and MyWakes. To get your Application ID and your signing key, please contact MyWakes. This signing key is yours alone and unique to your allplication ID. For that reason, please keep your signing key secure. This key — though used to generate the signature — should not be passed within any requests, stored on any websites, or posted to any public forum. Anyone obtaining this signing key "in the clear" could spoof requests using your identity.
If you've lost your signing key, contact MyWakes to retrieve it.
Generating valid signatures
Attempting to access a web service with an invalid signature will result in an Error 1.
To create a valid signature for your request:
- Construct your parameters sequence of 32 characters (please refer to the documentation of the selected API) to sign.
For example, in the case of the trackstart command, the string on which to calculate the signature might be: "trackstart20101112173025titolode". This string has been obtained by including (command name) + (time) + (track title, compacting the spaces).
Note: All MyWakes services require UTF-8 character encoding (which implicitly includes ASCII).
- Retrieve your private key, which is encoded in a modified Base64 for URLs, and sign the parameters above using the HMAC-SHA1 algorithm. You may need to decode this key into its original binary format. Note that in most cryptographic libraries, the resulting signature will be in binary format.
Note: Modified Base64 for calls replaces the + and / characters of standard Base64 with - and _ respectively
- Encode the resulting binary signature using the modified Base64 for calls to convert this signature into something that can be passed within a URL.
- Attach this signature to the call within the txtSignature field.
For testing purposes, you can test the following string and private key to see if it generates the correct signature. Note that this private key is purely for testing purposes and will not be validated by any MyWakes services.
- String to sign: trackstart20101112173025titolode
- Private Key: bdg4hcpmwt98azpwgtg532mns7As8Alkq2pH
- Signature: bd-SuLLTIML6n4D96sxYUhxzqts=
- the generated string must not have any spaces as these will need to be compacted
- should the generated string exceed 32 characters all extra characters must be eliminated from the calculation
- should the generated string be less than 32 characters long, random characters shall be added until the string reaches a length of 32 characters. In this case, the same characters added to the calculation string must also be added to the txtProvider field
For the signature calculation you can see some examples of code developed in different languages: