Interface ISharedKeyService

Provides a service to authenticate requests using HMAC-SHA256 shared key signatures.

Namespace: DataWeb.Authorization

Assembly: DataWeb.Core.dll

Syntax

public interface ISharedKeyService

Remarks

This service implements a request signing protocol based on HMAC-SHA256 to authenticate API requests between systems. Each request is signed with a secret key and includes a timestamp to prevent replay attacks.

The signature is computed over the app name, Unix timestamp, URL, and HTTP method, ensuring that any modification to these fields will invalidate the signature.

Methods

GetHttpHeaders(Uri, string, string, string)

Generates the HTTP headers required to authenticate an outgoing request.

Declaration

Dictionary<string, string> GetHttpHeaders(Uri url, string appName, string secretKey, string httpMethod)

Parameters

Type	Name	Description
Uri	url	The full URL of the outgoing request.
string	appName	The application name to include in the request headers.
string	secretKey	The shared secret key used to compute the signature.
string	httpMethod	The HTTP method of the outgoing request (e.g., GET, POST).

Returns

Type	Description
Dictionary<string, string>	A Dictionary<TKey, TValue> containing the authentication headers: X-AppName, X-Stamp, and X-Signature.

GetSignature(string, string)

Computes an HMAC-SHA256 signature for the provided data using the specified secret key.

Declaration

string GetSignature(string data, string secretKey)

Parameters

Type	Name	Description
string	data	The data string to sign.
string	secretKey	The shared secret key used for signing.

Returns

Type	Description
string	A Base64-encoded string representing the HMAC-SHA256 signature.

Exceptions

Type	Condition
ArgumentNullException	Thrown when data or secretKey is null or empty.

GetStamp()

Retrieves the current Unix timestamp in seconds.

Declaration

ulong GetStamp()

Returns

Type	Description
ulong	The current UTC time expressed as the number of seconds elapsed since Unix epoch (1970-01-01 00:00:00 UTC).

IsValidRequest(string, string, string, ulong, string, string, string, ulong)

Validates whether an incoming request is authenticated and has not expired.

Declaration

bool IsValidRequest(string appName, string secretKey, string requestAppName, ulong requestStamp, string requestSignature, string requestUrl, string requestMethod, ulong seconds = 900)

Parameters

Type	Name	Description
string	appName	The expected application name for this service.
string	secretKey	The shared secret key used to verify the signature.
string	requestAppName	The application name provided in the request.
ulong	requestStamp	The Unix timestamp (in seconds) provided in the request.
string	requestSignature	The HMAC-SHA256 signature provided in the request.
string	requestUrl	The full URL of the incoming request.
string	requestMethod	The HTTP method of the incoming request (e.g., GET, POST).
ulong	seconds	The maximum allowed age of the request in seconds. Defaults to 900 (15 minutes).

Returns

Type	Description
bool	true if the request is authenticated and within the allowed time window; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	Thrown when any required parameter is null or empty.

ValidateStamp(ulong, ulong)

Validates whether the request timestamp is within the allowed time window.

Declaration

bool ValidateStamp(ulong requestStamp, ulong seconds)

Parameters

Type	Name	Description
ulong	requestStamp	The Unix timestamp (in seconds) provided in the request.
ulong	seconds	The maximum allowed age of the request in seconds.

Returns

Type	Description
bool	true if the timestamp difference from the current time is within the allowed window; otherwise, false.

Remarks

Protects against replay attacks by rejecting requests with timestamps too far in the past or future.