Skip to main content

Creating your own Relay Client Package

Introduction

An MTE Relay Client is responsible for creating encoder / decoder pairs with an MTE Relay server, managing their state, encoding requests, and decoding responses.

Headers

MTE Relay Server relies on four header values that should be included on every request.

  • x-mte-relay-server-id
    • This is a GUID issued by the server, and it is returned on all responses.
  • x-mte-relay-client-id
    • This is a GUID issued by the server, and signed with a server side secret
    • The client should maintain this value locally, and include it on every request
  • x-mte-relay-session-id
    • This is a GUID created by the client and included on every request
    • The session ID has a 1-to-1 relationship with an encoder/decoder pair.
    • The client can update this ID at any time and repair to create a new encoder/decoder pair
  • x-mte-relay-eh
    • The Encoded Headers header.
    • This value should contain an object of key:value pairs of headers that were JSON serialized into a string and MKE encoded.
    • If the request / response has a body, this value should contain the content-type of the body.
    • Optionally, it may contain other headers as well.

API Endpoints

MTE Relay Server exposes 2 APIs that the client must interact with before being able to send MTE Encoded requests.

HEAD /api/mte-relay

This should be the first request you make, and if the request is successful, then the server is a verified MTE Relay server.

Request

  • Method: HEAD
  • Headers:
    • x-mte-relay-client-id [OPTIONAL] If you were assigned a client ID in a previous session, it should be maintained locally and included in this request. If you do not have a clientID, omit this header and you will be assigned a new one in the response headers.

Example:

curl --location --head 'https://mte-relay-server.domain.com/api/mte-relay' \
--header 'x-mte-relay-client-id: 3cc660bd-9af4-4021-bcbc-c115cdcc8260.67a0f3db628748df575760f973c0ac559b8d0554eeaa54a0452a3d215f7ef901'

Response

  • If this response is not successful, this is not an MTE Relay Server, and you should throw an error.
  • If this is successful, it is an MTE Relay Server, and you may request to create Encoder/Decoder pairs with this server.
  • This request can be considered successful if
    • It's status is 200
    • It contains the headers
      • x-mte-relay-server-id
      • x-mte-relay-client-id - Save this ID an include it on every future request. This is how the server identifies unique connecting clients.

POST /api/mte-pair

Use this API to exchange instantiation data and create a new encoder/decoder pair with the server.

Request

  • Method: POST
  • Headers:
    • x-mte-relay-client-id
      • Required.
      • Use the value assigned by /api/mte-relay
    • x-mte-relay-session-id
      • Required
      • Create this on the client.
      • This value is tied to the encoder/decoder pair created by this API.
      • If this value is ever changed, you will need to call this API with the new value to create new encoder/decoder pairs using this session ID.
  • Body:
    • encoderPersonalizationStr The client-side encoder's personalization string
    • encoderPublicKey The client-side encoder's ECDH public key, as aBase64 string
    • decoderPersonalizationStr The client-side decoder's personalization string
    • decoderPublicKey The client-side decoder's ECDH public key, as aBase64 string

Example Curl:

curl --location 'http://127.0.0.1:8080/api/mte-pair' \
--header 'x-mte-relay-client-id: 3cc660bd-9af4-4021-bcbc-c115cdcc8260.67a0f3db628748df575760f973c0ac559b8d0554eeaa54a0452a3d215f7ef901' \
--header 'x-mte-relay-session-id: VDWXXi7RparXDWi0HZghQNUfwJyhVFJTGvwZ' \
--header 'Content-Type: application/json' \
--data '{"encoderPersonalizationStr":"i7sP5zyRPAjqHzP7xXrmmxQ9exvanmbv9D9Z","encoderPublicKey":"BAEFsKkl2yLGp+5Ajr0+DgoaBROhZSaEnE4MT6xca1ahNLvUomQwOebTjDsKhwkTsAZtsDX3mbT/ZYyHQcK/tck=","decoderPersonalizationStr":"JCtwalAj4UwXc2Hr3yLEzAsx7N4l8pxfUL8e","decoderPublicKey":"BEvfJoctdqgYxCHSxEsQzLll5hqk7sh50GFv3XG8EwK5fWdwcmEENhf4E1CtAGD9ywPHjtnz8iel5HWaoDzU58o="}'

Response:

The response should include:

  • Status 200
  • Headers:
    • x-mte-relay-server-id
    • x-mte-relay-client-id
    • x-mte-relay-session-id
  • JSON Body:
    • encoderNonce The server-side encoder's nonce string
    • encoderPublicKey The server-side encoder's ECDH public key, as aBase64 string
    • decoderNonce The server-side decoder's nonce string
    • decoderPublicKey The server-side decoder's ECDH public key, as aBase64 string

Example:

{
"encoderNonce": "5473069918238",
"encoderPublicKey": "BEhcMrY8IBBAn0oHQDNFiyw3tCXWr6s83eaqFbbPTFUzpaxNR4P1svv64cDFOv2Kbu1o5vSSNKVJTzLWXOvOUFw=",
"decoderNonce": "37615310760989",
"decoderPublicKey": "BFVHBOgSHe0nXao4PJGBIGCoOsKt3L6UC2SppuQLIvHWxWX+jUeOwNBox6Or3OEre2gCroEfDke8MWFigInONTw="
}

Creating an Encoder / Decoder

After sending this /api/mte-pair request successfully, both sides should have enough data to create encoder decoder pairs. Combine the client-encoder values with the server-decoder values, and vice-versa to create the correct pairs.

Saving MTE State

The ID headers should be used for maintaining MTE State. The formula for saving MTE state should be:

  • encoder.severId.sessionId
    • encoder.fc16d510-0bbb-11ee-be56-0242ac120002.0498200e-0bbc-11ee-be56-0242ac120002
  • decoder.serverId.sessionId
    • decoder.fc16d510-0bbb-11ee-be56-0242ac120002.0498200e-0bbc-11ee-be56-0242ac120002

Proxying Requests with MTE Relay

Encode Headers

If the request has a body it should also have a Content-Type header. You need to add that header to a object or dictionary that can be JSON serialized into a string. Optionally, add any other headers to this object to be encoded.

const headersToEncode = {
"Content-Type": "application/json",
Authorization: "Bearer PD&meEB0tJkS$1#oufw3K2G7@pTC9Nac",
};
const encodedHeadersStr = JSON.stringify(headersToEncode);

MKE encode the above string and attach it to the request under the header x-mte-relay-eh

request.headers["x-mte-relay-eh"] = mkeEncode(encodedHeadersStr);

Encode Request Body

If the request has a body, simply mke encode the body and attach it as the body of the request.

Send request with correct headers