Speech Cloud Documentation

Signing POST Requests

To properly retrieve data from IVONA Speech Cloud, requests must be signed. Authentication is based on AWS Signature Version 4. The Java SDK handles request signing automatically. For more information, please refer to the Java SDK step of the guide. If usage of the SDK is not possible, request signing must be implemented manually. The exact specification of the signing process, including all details needed to properly implement AWSv4 Signing, are available in Amazon AWS documentation Signature Version 4 Signing Process.

Caution

This document is intended as a supplement to the AWS documentation and contains only details specific to IVONA Speech Cloud. To fully understand the signing process, be sure to read Signature Version 4 Signing Process.

The signing process is divided into steps. Each step contains an example that can be used to check the correctness of the code at each stage with a full request example provided at the end. An Access Key and Secret Key are required to sign the request. Please see the Credentials section for information on obtaining credentials.

In these examples, the following authorization keys are used to illustrate the signing process:

  • Access Key: 12345

  • Secret Key: 67890

In your application, use keys retrieved from the Credentials page of IVONA Speech Cloud.

Date used in examples:

  • date: 13.09.2013 9:20:54 UTC (20130913T092054Z)

Request Signing Example

Only partial results are shown. Please follow the links in each task for details. The data used for the synthesis is expected to be in JSON format as described in IVONA Speech Cloud API Reference.

Hello world request (unsigned)
POST /CreateSpeech HTTP/1.1
Host: tts.eu-west-1.ivonacloud.com
Content-type: application/json
X-Amz-Date: 20130913T092054Z
Content-Length: 32

{"Input":{"Data":"Hello world"}}
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>.

Task 1: Create a canonical request.

Rearrange the HTTPS request into standard/canonical format.

For a detailed description, see Task 1: Create a Canonical Request

IVONA Speech Cloud requires the following headers to be signed as part of the request:

  • content-type

  • host

  • x-amz-content-sha256

  • x-amz-date

The algorithm used for hash computation is:

  • SHA-256

Canonicalized request format
<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 header names>
Hex(SHA256Hash(<payload>))
Canonical request example created from "Hello world" request:
POST
/CreateSpeech

content-type:application/json
host:tts.eu-west-1.ivonacloud.com
x-amz-content-sha256:f43e25253839f2c3feae433c5e477d79f7dfafdc0e4af19a952adb44a60265ba
x-amz-date:20130913T092054Z

content-type;host;x-amz-content-sha256;x-amz-date
f43e25253839f2c3feae433c5e477d79f7dfafdc0e4af19a952adb44a60265ba

Task 2: Create a string to sign

For a detailed description, see Task 2: Create a String to Sign

The service name for IVONA Speech Cloud is:

  • tts

Algorithm required for calculating the hash value:

  • AWS4-HMAC-SHA256

Time zone required by IVONA Speech Cloud:

  • Coordinated Universal Time (UTC)

For a list of the available IVONA Speech Cloud regions, see Speech Cloud Endpoints page.

String To Sign format
AWS4-HMAC-SHA256
<Date>
<yyyyMMdd>/<aws region>/tts/aws4_request
Hex(SHA256Hash(<canonical request>))
String To Sign example
AWS4-HMAC-SHA256
20130913T092054Z
20130913/eu-west-1/tts/aws4_request
73ff17c0bf9da707afb02bbceb77d359ab945a460b5ac9fff7a0a61cfaab95e6

Task 3: Create a signature

For a detailed description, see Task 3:Create a Signature

See Examples of How to Derive a Version 4 Signing Key for how to implement the request signing process in several popular languages. Be sure to pay attention to the order of parameters.

Create a signature for your request by using a cryptographic hash function that accepts two input strings: your string to sign (created in previous step) and the derived key.

The calculations required to prepare a final signature are as follows:

Signature calculation process
DateKey = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<yyyyMMdd>")
DateRegionKey = HMAC-SHA256("<DateKey>", "<aws region>")
DateRegionServiceKey = HMAC-SHA256("<DateRegionKey>", "tts")
SigningKey = HMAC-SHA256("<DateRegionServiceKey>", "aws4_request")
Signature = HMAC-SHA256(SigningKey, StringToSign)
Signature calculation example
DateKey = HMAC-SHA256("AWS4"+"67890", "20130913")
DateRegionKey = HMAC-SHA256("<DateKey>", "eu-west-1")
DateRegionServiceKey = HMAC-SHA256("<DateRegionKey>", "tts")
SigningKey = HMAC-SHA256("<DateRegionServiceKey>", "aws4_request")
Signature = HMAC-SHA256(SigningKey, StringToSign)
Signature calculation result example
38c394cf938da94ec503f501a91055bc9aa339d165695884b9e7e60128f6ad27
Tip

As mentioned before, values used for calculation are:

  • Secret Access Key: 67890

  • yyyyMMdd: 20130913

Task 4: Prepare a signed request

Create an authorization header and build the final signed request.

Authorization header format:
Authorization: AWS4-HMAC-SHA256 Credential=<Access Key>/<yyyyMMdd>/<aws region>/tts/aws4_request,
SignedHeaders=<List of headers names>, Signature=<Signature>
Authorization header example:
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

Task 5: Full request ready to be sent

Complete signed request
POST /CreateSpeech HTTP/1.1
Host: tts.eu-west-1.ivonacloud.com
Content-type: application/json
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
Content-Length: 32

{"Input":{"Data":"Hello world"}}
 
Copyright © 2015 IVONA Software. All rights reserved. Terms of Use | Privacy Policy