2. Validating a request

The following tutorial explains how to validate an HTTP request.

You will only need the Donker.Hmac assembly for this.

Table of contents

1. Creating the validator
2. Validating the request
3. Interpreting the result
4. On failed authentication

1. Creating the validator

Before you can create a validator, you will need a configuration and signer. See the Signing a request page for more information, as we will use the same configuration and signer used there.

Once you have a configuration and signer, all you need to do is create a new instance of the HmacValidator class.

IHmacValidator validator = new HmacValidator(configuration, signer);

The validator will use the signer for creating a signature from the received request. The configuration also has an effect on how the validator behaves, as explained on the Signing a request page.

2. Validating the request

With the validator created, you can now validate the HTTP request.

HttpRequestBase request;

...

HmacValidationResult result = validator.ValidateHttpRequest(request);

As with the signer, the validator accepts either an HttpRequestMessage or HttpRequestBase object.

3. Interpreting the result

The HmacValidationResult that the validator returns describes whether the validation succeeded and, if not, what caused the validation to fail. It's ErrorMessage property contains a description if validation failed. The ResultCode property describes the result.

The ResultCode can be compared with one of the predefined result codes from the HmacValidationResultCode class.

switch (result.ResultCode)
{
    case HmacValidationResultCode.Ok:
        return "Everything is fine!";
    case HmacValidationResultCode.SignatureMismatch:
        return "Hmm... This signature is different.";
    
    ...

The following result codes are possible.

Code	Text	Description
0	OK	No error occured.
1	DateMissing	The date header could not be found.
2	DateInvalid	The date expired or is set in the future.
3	UsernameMissing	The username is required but not found.
4	KeyMissing	No key was found.
5	BodyHashMismatch	The Content-MD5 body hash does not match the one in the header.
6	AuthorizationMissing	The authorization header could not be found or was empty.
7	AuthorizationInvalid	The authorization header was in an incorrect format.
8	SignatureMismatch	The signatures do not match.
9	BodyHashMissing	The Content-MD5 body hash was expected but not present in the headers.

Of course, some results are only available depending on the configuration. For example, you shouln't get a BodyHashMismatch error if Content-MD5 validation has been disabled in the configuration.

4. On failed authentication

When authentication fails, HTTP status code 401 should be returned in the response. RFC 7235 states that a 401 response should also contain a WWW-Authenticate header that describes the form of authentication required. The validator has a method for adding the WWW-Authenticate header. See the example below:

HttpResponseBase response;

...

validator.AddWwwAuthenticateHeader(response, "HMAC");

I'd also recommend placing the validation error code in a custom response header, so that you can use that on the client side to know what went wrong without having to rely on the error message. For example:

response.Headers["X-Auth-ErrorCode"] = result.ResultCode;