Creating a Canonical Request

You can standardize the information of your request in a canonical format.

You need to use a canonical format for your request because 3DS OUTSCALE uses the same format to recalculate your signature when you send your request.

Once the canonical request is hashed, you need to add it to the string to sign that you create in Creating a String to Sign.

You do not need to do this procedure if you use OSC CLI, AWS CLI, or an SDK for your API request.

  1. Specify the HTTP request method (GET or POST) following this syntax (where \n is a newline character):

    Example of request method
    GET\n
  2. Add the canonical URI following this syntax (where \n is a newline character):

    Example of canonical URI with encoding
    /documents%2520and%2520settings/\n
    • The canonical URI is the URI-encoded version of the URI absolute path. This corresponds to everything between the HTTP host and the question mark character ("?") which begins the query string parameters.

    • You must normalize URI paths according to the RFC 3986. Therefore, you must remove all redundant and relative path components.

    If the absolute path is empty, use a slash (/):

    Example of canonical URI
    /\n
  3. Add the canonical query string following this syntax (where \n is a newline character):

    Example of canonical query string
    Action=DescribeInstances&Version=2016-09-15\n

    To build this canonical query string:

    1. Sort the names of the parameters by character code point, in ascending order.

    2. URI-encode each parameter name and value according to the following rules:

      • Do not URI-encode the authorized characters defined in the RFC 3986: a-z, A-Z, 0-9 et -_.~

      • Percent-encode all the other characters: %XY, where X and Y are hexadecimal characters (0 to 9 and A to F). For example, the space character must be encoded %20.

    3. Build the canonical query string starting with the name of the first parameter in the sorted list.

    4. For each parameter, append the URI-encoded parameter name, followed by the equal sign (=), followed by the value of the URI-encoded parameter. For parameters with no value, use an empty string.

    5. Append the ampersand character (&) after each parameter value, except for the last value of the list.

      If the request does not contain a query string, use an empty string.

  4. Add the canonical headers following this syntax (where \n is a newline character):

    Example of signed headers
    content-type:application/x-www-form-urlencoded; charset=utf-8\n
    host:fcu.eu-west-2.outscale.com\n
    x-amz-date:20180915T163400Z\n

    The canonical headers correspond to the list of all the HTTP headers contained in the signed request.

    The host header is mandatory. Other standard headers such as content-type are optional.

    To build the list of canonical headers, refer to the following pseudocode:

    Example of signed headers
    CanonicalHeaders =
    CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + ... + CanonicalHeadersEntryN
    CanonicalHeadersEntry =
    Lowercase(HeaderName) + ':' + Trimall(HeaderValue) + '\n'

    The Lowercase function converts all characters to lowercase. The Trimall function removes extra spaces before and after values, and converts sequential spaces into single spaces.

    Build the list of canonical headers by sorting the headers by character code, and then by iterating through their names.

    Build each header according to the following rules:

    • Append the header name in lowercase, followed by a colon (":")

    • Append the list of values separated by semicolons (";") for that header. Do not sort values in the headers that have several values.

    • Append a new line character (\n)

    Example of original headers
    Host:fcu.eu-west-2.outscale.com\n
    Content-Type:application/x-www-form-urlencoded; charset=utf-8\n
    My-header1:    a   b   c  \n
    X-Amz-Date:20180915T163400Z\n
    My-Header2:    "a   b   c"  \n
    Example of headers in canonical format
    content-type:application/x-www-form-urlencoded; charset=utf-8\n
    host:fcu.eu-west-2.outscale.com\n
    my-header1:a b c\n
    my-header2:"a b c"\n
    x-amz-date:20180915T163400Z\n
  5. Add the signed headers following this syntax (where \n is a newline character):

    Example of signed headers
    content-type;host;x-amz-date\n

    Signed headers correspond to the list of headers you included in the canonical headers.

    The host header is a mandatory signed header. If you want to add a date or an x-amz-date header, you must also include this header in the list of signed headers.

    To build the list of signed headers, refer to the following pseudocode:

    Example of signed headers
    SignedHeaders =
    Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ... + Lowercase(HeaderNameN)

    Convert all header names into lowercase with the Lowercase function, sort them by character code and use a semicolon (";") to separate header names.

  6. Use a hash function to create a hash value from the payload in the body of the HTTP request.

    Sample of structure of a payload
    HashedPayload = Lowercase(HexEncode(Hash(requestPayload)))
    • The hashed payload must be a lowercase hexadecimal string.

    • If the payload is empty, use an empty string for the hash function. In our example, the payload is empty.

    The payload is hashed.

    Example of hashed payload (empty string)
    ae14e49469bac4395994faf4b0b3e9824c41b724914c1fc98c69585b2729fb58
  7. To build the canonical request, combine all the elements from the previous steps:

    Example of canonical request
    GET
    /
    Action=DescribeInstances&Version=2016-09-15
    content-type:application/x-www-form-urlencoded; charset=utf-8
    host:fcu.eu-west-2.outscale.com
    x-amz-date:20180915T163400Z
    
    content-type;host;x-amz-date
    ae14e49469bac4395994faf4b0b3e9824c41b724914c1fc98c69585b2729fb58
  8. Hash the canonical request with the same algorithm you used to hash the payload.

    Example of hashed canonical request
    0547bdda2966fc9a3a76269a3193bed373a56072cfa77949936bc2a556016f32

    The canonical request is hashed. You then need to add it to the string to sign that you create in Creating a String to Sign.

Related Pages

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.