JWS HMAC: What is it?

According to the RFC 7515 standard, JWS (JSON Web Signature) is a small, URL-safe technique for securely expressing claims between two parties. It allows you to digitally sign data and verify that it hasn’t been altered while being transmitted. A particular kind of message authentication code (MAC) that uses a cryptographic hash function and a secret cryptographic key is called HMAC (Hash-based Message Authentication Code). Using HMAC in the context of JWS indicates that a hash function and a secret key are used to calculate the JWS Signature.

Why Use JWS HMAC?

1. Integrity and Authenticity: JWS with HMAC provides both data integrity and authentication. The signature ensures that the data has not been altered, and since the HMAC key is secret, it can verify that the sender (or signer) of the JWT is who they claim to be.
2. Security: HMAC is considered a strong method of ensuring data integrity because it involves a secret key, which makes it difficult to forge compared to non-keyed hashes.
3. Compactness: JWS provides a compact way to securely transmit information via URLs, HTTP headers, and within other contexts where space is limited.

How to Use JWS HMAC in an ASP.NET Web Application?

To use JWS HMAC in an ASP.NET application, you’ll typically be working with JWT (JSON Web Tokens), where JWS forms the string that is signed and encoded. Here’s how you can implement this,

Step 1. Install Necessary NuGet Package

You’ll need a library that can handle JWT. One popular choice is System.IdentityModel.Tokens.Jwt. You can install it via NuGet.

Install-Package System.IdentityModel.Tokens.Jwt

Step 2. Create and Sign a JWT with HMAC

Here’s how you can create a JWT and sign it using HMAC in your ASP.NET application.

using System;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using System.Security.Claims;

public class TokenService
{
    public string GenerateToken()
    {
        var secretKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your-256-bit-secret"));
        var signinCredentials = new SigningCredentials(secretKey, SecurityAlgorithms.HmacSha256);

        var tokenOptions = new JwtSecurityToken(
            issuer: "https://yourdomain.com",
            audience: "https://yourdomain.com",
            claims: new List<Claim>(),
            expires: DateTime.Now.AddMinutes(30),
            signingCredentials: signinCredentials
        );

        var tokenString = new JwtSecurityTokenHandler().WriteToken(tokenOptions);

        return tokenString;
    }
}

Explanation

1. Secret Key: This is a key used by HMAC for hashing. It should be kept secret and secure.
2. Signing Credentials: Uses the secret key and specifies the HMAC SHA256 algorithm for signing.
3. JwtSecurityToken: Represents the JWT data structure and allows setting properties like issuer, audience, claims, expiry time, etc.
4. JwtSecurityTokenHandler: Handles the creation of the token string.

Step 3. Validate the JWT in ASP.NET

When you receive a JWT, you need to validate it to ensure it’s still valid and verify its signature.

public ClaimsPrincipal ValidateToken(string token)
{
    var tokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = "https://www.hostforlife.eu",
        ValidAudience = "https://www.hostforlife.eu",
        IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your-256-bit-secret"))
    };

    var tokenHandler = new JwtSecurityTokenHandler();
    SecurityToken validatedToken;
    var principal = tokenHandler.ValidateToken(token, tokenValidationParameters, out validatedToken);
    return principal;
}