/
Security

Security

Owned by Gabriel Körner
Last updated: 16 22 2024
3 min read

Browse trough security mechanics and how to use in your requests with implementation examples.

Activation of Functionalities

At the start of the partnership, use cases for the integration will be defined. It has to be made sure that requests are sent from the true partner and are not manipulated between the partner and hotelkit, therefore security measures have to be taken. This is what signing the requests is for.

Hereby the request and its parts are hashed together with a secret (privateKey) that only the partner (and hotelkit) knows. The result will be submitted in the Header x-hotelkit-api-signature. The requests are hashed by hotelkit as well and only requests are handled if the resulting hash is the same as in the header. If the result differs, a 400 response will be returned with the message that the signature is incorrect.

The private key will be presented to the partner at the start of the partnership.

Generating the Signature

The hashing algorithm used is SHA-1 within HMAC as it is fast and believed to be secure at the time. For ensuring the integrity of all the data, all data of the request has to be hashed:

  1. The method of the request (e.g. GET)

  2. The requested URI (e.g. https://api.hotelkit.net/requests?type=sampleRequest)

  3. The serialized header

  4. The payload of the request

Those components are concatenated with a ‘;’.

Annotations

  • The method MUST be used in uppercase letters: GET instead of get.

  • The payload of a GET request will be serialized with the URI as it is always attached to the URI. Payload has to be serialized to ‘[]’

Serializing of Header

The format for serializing the headers is ‘name: value’. For example, the x-hotelkit-version header with value 3.0 will be serialized to ‘x-hotelkit-api-version:3.0’.
Every header is separated with a ‘;’ from the next header.

The following header will be serialized in alphabetical order:

  1. Date

  2. x-hotelkit-api-customer-key

  3. x-hotelkit-api-nonce

  4. x-hotelkit-api-public-key

  5. x-hotelkit-api-version

The result of the serialization will be called content in this chapter. It will be hashed together with the private key via HMAC using SHA1 as digest algorithm. The corresponding hash must consist of lowercase chars only.

The hash has to be encrypted with base64 to make it a valid HTTP header value. The generation of the signature will be summarized as follows:

x-hotelkit-api-signature = BASE64(SHA1(content,privateKey));

Example

For this example the following values are set:

privateKey = "forDemoPurposesOnly" curl -H "x-hotelkit-api-version: 3.0" -H "x-hotelkit-api-public-key: demoClientNotValid" -H "x-hotelkit-api-customer-key: customerWhoIsOnlyAdemo" -H "x-hotelkit-api-nonce: bm9uY2VPZlRoZURlbW8xMjM0NTY3Mg==" -H "x-hotelkit-api-signature: signature" -H "Date: Mon, 04 Jul 2022 14:56:36 GMT" -X POST -d '{"lorem":"ipsum"}' -i https://api.hotelkit.net/hashExample?type=docu

The content of the request would be serialized as:

POST;https://api.hotelkit.net/hashExample?type=docu;Date:Mon, 04 Jul 2022 14:56:36 GMT;x-hotelkit-api-customer-key:customerWhoIsOnlyAdemo;x-hotelkit-api-nonce:bm9uY2VPZlRoZURlbW8xMjM0NTY3Mg==;x-hotelkit-api-public-key:demoClientNotValid;x-hotelkit-api-version:3.0;{"lorem":"ipsum"}

The SHA1 hash will be:

After BASE64 encoding the header will be set as the following:

Signature Implementations

PHP

 

C#

 

Ruby on Rails

 

Java

 

JavaScript/Node