Speech Cloud Documentation

Signing GET requests

Note

Please read Signing POST Request first to understand this section.

It is possible to provide all request parameters, including authentication information, in a query string. This can simplify the process of request preparation in applications running on the client side (such as mobile or Adobe Flash applications), because it is much easier to invoke HTTP GET than HTTP POST requests.

Please be sure to read GET method limitations before deciding on using GET requests to understand all its limitations.

Caution
Storage of Credentials

We strongly discourage storing credential information inside a client-side application (including applications running inside a browser, such as JavaScript widgets, Java applets, and Adobe Flash applications). Storing credentials on the client side, even in an obfuscated manner, does not prevent a malicious user from extracting such credentials and gaining access to the service.

It is more secure to sign a request on the server side, where access to authentication credentials is restricted. A signed request in the form of a URI can then be passed as a parameter to the application that would retrieve the audio stream (for example, an Adobe Flash application or audio HTML tag) without exposing authentication credentials to the end user.

The AWS Sign v4 algorithm makes it possible to pass signature components as HTTP query string parameters instead of HTTP headers (see the Signing POST Requests section). Both approaches are illustrated here using the example from the mentioned section.

Note

Please note that newline characters are added for readability purposes only. When a new line has to be included in the request itself, it is always represented by <new_line>.

Tip

All the example-specific values used in this section are the same as mentioned in Signing POST Request.

Authentication using HTTP headers
X-Amz-Date: 20130913T092054Z
Authorization: AWS4-HMAC-SHA256 Credential=12345/20130913/eu-west-1/tts/aws4_request,
SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date,
Signature=38c394cf938da94ec503f501a91055bc9aa339d165695884b9e7e60128f6ad27
X-Amz-Content-Sha256: f43e25253839f2c3feae433c5e477d79f7dfafdc0e4af19a952adb44a60265ba

The same information can be provided as query string parameters:

Authentication using Query String
&X-Amz-Date=20130913T092054Z
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=12345%2F20130913%2Feu-west-1%2Ftts%2Faws4_request
&X-Amz-SignedHeaders=host
&X-Amz-Signature=38c394cf938da94ec503f501a91055bc9aa339d165695884b9e7e60128f6ad27
Tip
Query string parameters are case-sensitive

Please note that for GET requests, all parameters are case-sensitive. For example, providing an &*x-amzn-date*=20130913T092054Z instead of &*X-Amzn-Date*=20130913T092054Z parameter will result in an incorrect request.

At the very least, you must include the "host" header in the signing process. Additional headers can be added, but are optional.

The following list describes authentication parameters:

Authentication parameters description
  • X-Amz-Date - The date formatted as required by AWS Sign v4. Corresponds to <Date> in POST request.

  • X-Amz-Algorithm - AWS signature algorithm identification. In this case, it should always be AWS4-HMAC-SHA256.

  • X-Amz-Credential - Credential scope, corresponds to Credentials part in POST Authorization header.

  • X-Amz-SignedHeaders - List of header names used to calculate the signature.

  • X-Amz-Signature - Signature used to authenticate the request, calculated according to the algorithm described below.

Passing request parameters via query string

JSON data expected by IVONA Speech Cloud API Reference actions has to be encoded in the URI when using the HTTP GET method. Apply the following rules to correctly reflect the JSON structure in the query string:

  • Each attribute should be converted to a URI query parameter containing the full path in the JSON structure, where every level of depth is separated by a dot: ".". For example: Input.Data.

  • Each value should be correctly URI-encoded, including whitespace characters and all special characters (see below). For example: Does%20Mary%20have%20a%20little%20lamb%3F.

Translation example

JSON formatted CreateSpeech request
{
    "Input" : {
        "Data" : "Does Mary have a little lamb?",
        "Type" : "text/plain"
    },

    "OutputFormat" : {
        "Codec" : "MP3",
        "SampleRate" : 22050
    },

    "Parameters" : {
        "Rate" : "slow"
    },

    "Voice" : {
        "Name" : "Amy",
        "Language" : "en-GB"
    }
}
Attributes converted to query string format
&Input.Data=Does%20Mary%20have%20a%20little%20lamb%3F
&Input.Type=text%2Fplain
&OutputFormat.Codec=MP3
&OutputFormat.SampleRate=22050
&Parameters.Rate=slow
&Voice.Name=Amy
&Voice.Language=en-GB

URI character encoding of special characters

URI encoding is the process of translating non-ASCII and special characters to a form compatible with the URI specification: RFC 3986.

The process can be described as applying the following rules to all bytes:

  • The following characters do not have to be URI encoded: A-Z, a-z, 0-9, -, ., _, and ~.

  • Each byte that has to be encoded is formed by a % character and the two-digit hexadecimal value of the byte. For the space character, the encoded value is "%20". Letters in hexadecimal values should always be uppercase (for example, "%FA").

  • The slash character / should not be encoded in the resource URI (for example, /CreateSpeech or /ListVoices). In other cases, it should be encoded as "%2F".

Tip

It is important to make sure that all RFC 3986 rules are applied during the encoding process. Some built-in URI encoding functions convert the space character to "+" instead of "%20", which would result in an incorrectly calculated Signature.

Signing GET requests

The process of signature calculation is very similar to the one described in the Request Signing section.

It is composed of three steps:

  1. Preparation of the canonical request

  2. Building of the string to sign

  3. Calculation of the signature

Preparation of the canonical request

Preparation of a canonical request form is the process of building the string value containing a sequence of specifically formatted lines separated by the newline character, "\n".

The signature cannot be calculated using the original request form because the order of headers or parameters can be changed by web browsers or other intermediaries (such as gateways, proxies, and load balancers) processing the request, thus affecting the final signature.

Also, all authentication query string parameters should be included in the canonical form with the exception of X-Amz-Signature (which is not yet calculated at this stage).

Canonicalized request contents
<HTTP method name>
<'/' character followed by URI-encoded resource path>
<Query string with URI-encoded parameters>
<List of header:value pairs>
<new_line>
<List of headers>
Hex(SHA256Hash(""))
Tip

For a GET request, the payload is an empty string ("") for which the Hex value of SHA256Hash is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

The example text "Does Mary have a little lamb?" used in Query Translation Example would have the following canonicalized form:

Canonicalized GET request
GET
/CreateSpeech
Input.Data=Does%20Mary%20have%20a%20little%20lamb%3F&Input.Type=text%2Fplain
&OutputFormat.Codec=MP3&OutputFormat.SampleRate=22050&Parameters.Rate=slow
&Voice.Language=en-GB&Voice.Name=Amy&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=12345%2F20130913%2Feu-west-1%2Ftts%2Faws4_request
&X-Amz-Date=20130913T092054Z&X-Amz-SignedHeaders=host
host:tts.eu-west-1.ivonacloud.com

host
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Building the "string to sign"

After preparing the canonicalized form of the request, it is necessary to build the final string to be signed.

The process of building StringToSign is the same as described in the Task 2. Create String to sign section.

Calculating the signature

The prepared StringToSign is used in the process of calculating the signature. The exact process is the same as described in the Task 3. Create Signature section.

The calculated signature should be passed as one of the Query String authentication parameters: X-Amz-Signature.

Final signed request

After Signature calculation, the whole URI can be built containing the complete query string:

Final GET request example
https://tts.eu-west-1.ivonacloud.com/CreateSpeech
?Input.Data=Does%20Mary%20have%20a%20little%20lamb%3F
&Input.Type=text%2Fplain
&OutputFormat.Codec=MP3
&OutputFormat.SampleRate=22050
&Parameters.Rate=slow
&Voice.Name=Amy
&Voice.Language=en-GB
&X-Amz-Date=20130913T092054Z
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=12345%2F20130913%2Feu-west-1%2Ftts%2Faws4_request
&X-Amz-SignedHeaders=host
&X-Amz-Signature=38c394cf938da94ec503f501a91055bc9aa339d165695884b9e7e60128f6ad27

GET request limitations

Query string length restrictions differ between web browsers, so there is a hardcoded limit on the maximum number of characters that can be passed as an Input.Data parameter to the GET version of the CreateSpeech activity. Passing text that exceeds this limit results in an error message being returned from the service instead of the audio stream.

The actual length restriction for the Input.Data field in a request is 1024 characters (whereas for POST, the limit is 8192 characters).

 
Copyright © 2015 IVONA Software. All rights reserved. Terms of Use | Privacy Policy