Authentication

You'll need to authenticate your requests to access any of the endpoints in the Protocol API. In this guide, we'll look at how authentication works. All the authenticated requests sent to MeSomb need not be signed according to the MeSomb Standard.

Note: All requests must be sent via the https transport protocol.

Why requests are signed?

The signing process helps secure requests in the following ways:

• Verify the identity of the requester Signing makes sure that the request has been sent by someone with a valid access key.
• Protect data in transit To prevent tampering with a request while it's in transit, some of the request elements are used to calculate a hash (digest) of the request, and the resulting hash value is included as part of the request. When a MeSomb service receives the request, it uses the same information to calculate a hash and matches it against the hash value in your request. If the values don't match, MeSomb denies the request.
• Protect against potential replay attacks In most cases, a request must reach MeSomb within five minutes of the time stamp in the request. Otherwise, MeSomb denies the request.

How MeSomb Signature works

MeSomb Signature (MeSombSig) is the process to add authentication information to MeSomb API requests sent by HTTPS. For security, most requests to MeSomb must be signed with an access key. The access key consists of an access key ID and secret access key, which are commonly referred to as your security credentials.

How Signature Version 4 works

1. Create a canonical request.
2. Use the canonical request and additional metadata to create a string for signing.
3. Derive a signing key from your MeSomb secret access key. Then use the signing key, and the string from the previous step, to create a signature.
4. Add the resulting signature to the HTTP request in a header.

When a MeSomb service receives the request, it performs the same steps that you did to calculate the signature you sent in your request. MeSomb then compares its calculated signature to the one you sent with the request. If the signatures match, the request is processed. If the signatures don't match, the request is denied.

Elements of a MeSomb Signature request

Each HTTP/HTTPS request that uses MeSomb Signature must contain these elements.

• HTTP Method
• Full URL Path
• Required and Optional Parameters
• Date
• Authentication Parameters

HTTP Method

This is the HTTP method of your request: GET, POST, PATCH, PUT, HEAD, DELETE. This method must be in uppercase.

Full URL path

This is the full URL of the action your want to perform on MeSomb: https:///. You will have below the endpoint of each action you want to perform.

Required and optional parameters

This element specifies the parameters of the request action. Each action in a web service has a set of required and optional parameters that define an API call. The API version is usually a required parameter. See the service documentation for the details of required and optional parameters.

Date

This is the date and time at which you make the request. Including the date in the request helps prevent third parties from intercepting your request and resubmitting it later. The date is specified using the timestamp format via the x-mesomb-date header.

Authentication parameters

Each request that you send must include the following set of parameters that MeSomb uses to ensure the validity and authenticity of the request.

• Algorithm. The hash algorithm that you're using as part of the signing process. For example, if you use SHA1 to create hashes, use the value HMAC-SHA1 (only SHA1 is supported for now).
• Credential scope. A string separated by slashes ("/"), is formed by concatenating your access key ID and the service you are requesting. For example, the following string represents the Credential parameter for a payment service. AKIAIOSFODNN7EXAMPLE/payment
• SignedHeaders A list delimited by semicolons (";") of HTTP/HTTPS headers to include in the signature.
• Signature A hexadecimal-encoded string that represents the output of the signature operation described in Task 3: Calculate the signature for MeSomb Signature. You must calculate the signature using the algorithm that you specified in the Algorithm parameter.

Signing requests with MeSomb Signature

To create a signed request, complete the following:

• Task 1: Create a canonical request for MeSomb Signature Arrange the contents of your request (method, URL, headers, etc.) into a standard (canonical) format. The canonical request is one of the inputs used to create a string to sign.
• Task 2: Create a string to sign for MeSomb Signature Create a string to sign with the canonical request and extra information such as the algorithm, request date, credential scope, and the digest (hash) of the canonical request.
• Task 3: Calculate the signature for MeSomb Signature TODO
• Task 4: Add the signature to the HTTP request After you calculate the signature, add it to an HTTP header or the query string of the request.

The following table describes the functions that are shown in the diagram. You need to implement code for these functions.

Task 1: Create a canonical request for MeSomb Signature

This section provides an overview of creating a canonical request.

The following is the canonical request format that MeSomb uses to calculate a signature. For signatures to match, you must create a canonical request in this format:

{HTTPMethod}\n
{CanonicalURI}\n
{CanonicalQueryString}\n
{CanonicalHeaders}\n
{SignedHeaders}\n
{HashedPayload}

Where:

• HTTPMethod: is one of the HTTP methods, for example, GET, PUT, HEAD, and DELETE.

• CanonicalURI: is the URI-encoded version of the absolute path component of the URI—everything starting with the "/" that follows the domain name and up to the end of the string or the question mark character ('?') if you have query string parameters. The URI in the following example, /example/payment, is the absolute path and you don't encode the "/" in the absolute path: http://mesomb.hachther.com/example/payment

• CanonicalQueryString: specifies the URI-encoded query string parameters. You URI-encode name and values individually. You must also sort the parameters in the canonical query string alphabetically by key name. The sorting occurs after encoding. The query string in the following URI example is: param=value&service=payment&value=20

http://mesomb.hachther.com/service?param=value&service=payment&value=20

The canonical query string is as follows (line breaks are added to this example for readability):

UriEncode("marker")+"="+UriEncode("someMarker")+"&"+
UriEncode("max-keys")+"="+UriEncode("20") + "&" +
UriEncode("prefix")+"="+UriEncode("somePrefix")

• CanonicalHeaders: is a list of request headers with their values. Individual header name and value pairs are separated by the newline character ("\n"). Header names must be in lowercase. You must sort the header names alphabetically to construct the string, as shown in the following example

Lowercase(<HeaderName1>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderName2>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderNameN>)+":"+Trim(<value>)+"\n"

The Lowercase() and Trim() functions used in this example are described in the preceding section.

The CanonicalHeaders list must include the following:

• HTTP host header.
• If the Content-Type header is present in the request, you must add it to the CanonicalHeaders list.
• Any x-mesomb-* headers that you plan to include in your request must also be added. Some x-mesomb-* header is required:
• x-mesomb-date: is the date of the request on the timestamps format
• x-mesomb-nonce: is the unique string randomly generated for each request

The following is an example CanonicalHeaders string. The header names are in lowercase and sorted.

host:mesomb.hachther.com
x-mesomb-date:1666091223
x-mesomb-nonce:8fd90ffs903if0394ls

• SignedHeaders: is an alphabetically sorted, semicolon-separated list of lowercase request header names. The request headers in the list are the same headers that you included in the CanonicalHeaders string. For example, for the previous example, the value of SignedHeaders would be as follows:

host;x-mesomb-date;x-mesomb-nonce

• HashedPayload is the hexadecimal value of the SHA1 hash of the request payload string. Payload is the string representation on the most compact string form of the json object: eliminating whitespace.

Hex(SHA1Hash(<payload>)

If there is no payload in the request, you compute a hash of the empty string JSON object as follows:

Hex(SHA1Hash("{}"))

Task 2: Create a string to sign for MeSomb Signature

This section provides an overview of creating a string to sign.

The string to sign is a concatenation of the following strings:

"HMAC-SHA1" + "\n" +
timeStamp + "\n" +
<Scope> + "\n" +
Hex(SHA1Hash(<CanonicalRequest>))

The constant string HMAC-SHA1 specifies the hash algorithm that you are using, HMAC-SHA1. The timeStamp is the current timestamp.

Scope binds the resulting signature to a specific date and service (payment, wallet, ...). Thus, your resulting signature will work only in the specific service. The signature is valid for seven days after the specified date.

date.Format(<YYYYMMDD>) + "/" <service> + "/mesomb_request"

The following scope restricts the resulting signature to the service payment.

20220101/payment/mesomb_request

Task 3: Calculate the signature for MeSomb Signature

The final signature is the HMAC-SHA1 hash of the string to sign, using the secret key.

HMAC-SHA1(SecretKey, StringToSign)

Task 4: Add the signature to the HTTP request

You include signing information by adding it to an HTTP header named Authorization. The contents of the header are created after you calculate the signature as described in the preceding steps, so the Authorization header is not included in the list of signed headers. Although the header is named Authorization, the signing information is used for authentication.

The following pseudocode shows the construction of the Authorization header.

Authorization: algorithm Credential=access key ID/credential scope, SignedHeaders=SignedHeaders, Signature=signature

Using an SDK

If you use one of our official SDKs, you won't have to worry about any of the above — fetch your access token from the MeSomb dashboard under Developer settings, and the client library will take care of the rest. All the client libraries use MeSomb Signature behind the scenes.