Authorization

Introduction

All requests sent to SiGa application must be signed with a previously agreed secret key that is unique to given e-service. The signature is calculated as an HMAC value over the mandatory "Authentication-X-..." headers and the request body contents. For requests that do not contain a payload the body contents are considered as an empty byte array.

Each e-service must be preregistered in the SiGa service. Each e-service is issued a unique service identifier (UUID) and a secret. The secret is shared between the e-service provider and SiGa backend. The secret is encrypted before being stored in service-database. The secret encryption key is stored in Vault and read once on application startup.

In addition to the request payload, the e-service provider must send the following mandatory HTTP headers with every request:

• X-Authorization-Timestamp
• X-Authorization-ServiceUUID
• X-Authorization-Hmac-Algorithm (optional, defaults to "HmacSHA256")
• X-Authorization-Signature

The signature must be calculated before any transformations or compression is applied to the request body.

Headers

Mandatory headers are same for all API requests. Content-Type may change in case of GET request.

Header	Mandatory	Default value	Description
X-Authorization-Timestamp	+	-	Timestamp of request generation from client side. UTC timestamp of client system with precision 1 second.
X-Authorization-ServiceUUID	+	-	Unique identifier of the relying party e-service. Used to determine client and e-service making the actual request.
X-Authorization-Signature	+	-	Hex encoded value of hmac hash of the canonicalized request data (authentication headers and body contents).
X-Authorization-Hmac-Algorithm	-	HmacSHA256	Unique identifier of the relying party e-service. Used to determine client and e-service making the actual request.
Content-Type	for POST and PUT only	-	The Media type of the body of the request (used with POST and PUT requests). Only supported value is application/json; charset=UTF-8

Signature creation process

1. Given the following example container creation request:

POST https://siga.ria.ee/v1/hashcodecontainers HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json; charset=UTF-8
Content-Length: 370
Host: siga.ria.ee
Connection: Keep-Alive
User-Agent: Example service
X-Authorization-Hmac-Algorithm: HmacSHA256

{
   "dataFiles":    {
      "fileName": "document.doc",
      "fileHashSha256": "daacfc16653efa09d363d3d0a4a4bd9348add16c11d876465b6a106872dd34d4",
      "fileHashSha512": "4f029e65480e3fc39355267060e63d1059887b3dfce923d06b6ceeffe558c8408f74bd520f0d4593ca8cffb262be2786e195de8334a91faa7dec008cecedcf33",
      "fileSize": "1024"
   }
}

2. Prepare the current timestamp and ServiceUUID headers for the request:

X-Authorization-Timestamp: 1551102625
X-Authorization-ServiceUUID: 13d03497-67bf-4879-8382-e8072ea04a09

3. Prepare the request url and extract the context path with query parameters Note that the context path string should be extracted after URL Encoring rules are applied:

urlContextPath = "/hashcodecontainers?someParam=value%20with%20space"

4. Extract HTTP method name in uppercase

reqeustMethod = "POST"

5. Concatenate the values of X-Authorization-ServiceUUID header, X-Authorization-Timestamp header, urlContextPath and requestBody("UTF-8") with the delimiter ':' in the following manner to generate the plaintext for signature calculation:

plaintext = "13d03497-67bf-4879-8382-e8072ea04a09" + ":" + "1551102625" + ":" + "POST" + ":" + "hashcodecontainers?someParam=value%20with%20space" + ":" + requestBody("UTF-8")

6. With the signing secret key, calculcate the HmacSHA256 value for given plaintext

signingSecret = "112233445566778899"
authSignature = HmacSHA256(plaintext, signigSecret)

7. Add the signature value to the request header X-Authorization-Signature to construct the final request

POST https://siga.ria.ee/v1/hashcodecontainers HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json; charset=UTF-8
Content-Length: 370
Host: siga.ria.ee
Connection: Keep-Alive
User-Agent: Example service
X-Authorization-Timestamp: 1551102625
X-Authorization-ServiceUUID: 13d03497-67bf-4879-8382-e8072ea04a09
X-Authorization-Hmac-Algorithm: HmacSHA256
X-Authorization-Signature: 5d57258d493b49bdaf0911e9aa20f5b9c1e25d6a1472779292828fe2ffd0518c

{
   "dataFiles":    {
      "fileName": "document.doc",
      "fileHashSha256": "daacfc16653efa09d363d3d0a4a4bd9348add16c11d876465b6a106872dd34d4",
      "fileHashSha512": "4f029e65480e3fc39355267060e63d1059887b3dfce923d06b6ceeffe558c8408f74bd520f0d4593ca8cffb262be2786e195de8334a91faa7dec008cecedcf33",
      "fileSize": "1024"
   }
}

Url encoding rules

• Do not URL encode any of the unreserved characters that RFC 3986 defines. These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).
• Percent encode extended UTF-8 characters in the form %XY%ZA.
• Percent encode the space character as %20 (and not +, as common encoding schemes do).
• Percent encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F.