Azure Keyvault and HMAC-SHA256 Pseudonymizer

In this article, using Azure Keyvault together with HMAC-SHA256.

Introduction to HMAC SHA-256

The HMAC-SHA256 is a SHA-256 cryptographic hashing function that combines SHA-256 with a secret key (that can be shared) to provide both data integrity (to ensure that data has not been altered) and data authenticity (that data originates from a sender that knows about the shared secret key of the HMAC-SHA256 hash). HMAC-SHA256 generates a Message Authentication Code (MAC)
that we can get both these benefits from, data authenticity and data integrity. Since it is 256 bits or 32 bytes, the hash can be represented as hexadecimal string of length 64. If it is represented as a base-64 string, it will be approximately 44 bytes long, given that a base-64 string will be padded in multiple of 4 characters.

Storing the shared secret key in Azure Keyvault

Azure Keyvault will be used to store the shared secret key. The secret key could be stored anywhere, but using a KeyVault in Azure makes it easier to keep it safe and apply rolling policies for the secret key. First off, to create an Azure Keyvault secret, make sure you have an Azure Keyvault created. Search for a resource called Key vaults with a key icon. Choose Create, enter a Key vault name and Region and resource group, Pay per use and Standard pricing tier. (Premium includes HSM backed keys, which will use dedicated physical devices - HSM = Hardware Security Module - for enhanced FIPS 140-2 Level 3 certified security). Once the keyvault is created, choose Object and Secrets. Click Generate/Import. Just enter a name for the secret and the secret value. It is suggested that they secret value you enter should be genereated from a cryptographically secure random generator and a length of at least 16 bytes and 32 bytes.

Generating a strong shared secret key for HMAC SHA-256

The following code can be used to generate a strong 256 (32-byte) key, and pasted into the Secret value

HmacSha256KeyGenerator.cs

using System.Security.Cryptography;

namespace MinimalApiSecurityExperimentsDotNet.Extensions
{

    public static class HmacSha256KeyGenerator
    {

        public static string GenerateStrongKey()
        {
            // Generate a 256-bit (32-byte) key
            byte[] key = new byte[32];
            using (var rng = RandomNumberGenerator.Create())
            {
                rng.GetBytes(key);
            }

            // Convert to Base64 for storage or display
            string base64Key = Convert.ToBase64String(key);
            return base64Key;
            //Console.WriteLine("Generated HMAC-SHA-256 Key (Base64):");
            //Console.WriteLine(base64Key);
        }

    }

}

MinimalApiSecurityDemo.csproj

The following Nuget packages can be added to work with Azure Keyvault secrets.

  <PackageReference Include="Azure.Identity" Version="1.14.2" />
  <PackageReference Include="Azure.Security.KeyVault.Keys" Version="4.8.0" />
  <PackageReference Include="Azure.Security.KeyVault.Secrets" Version="4.8.0" />

Note that you do not need the Keys nuget package here if you only want to retrieve secrets. Azure KeyVault got three different object types - Keys, secrets and certificates. Only secrets will be looked at in this article.

KeyVaultSecretRetriever.cs

Let's look at key vault retrieval.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

namespace MinimalApiSecurityExperimentsDotNet
{
    
    public class KeyVaultSecretRetriever
    {
        private readonly IConfiguration _configuration;
        public KeyVaultSecretRetriever(IConfiguration configuration)
        {
            _configuration = configuration;
        }

        public async Task<KeyVaultSecret>? GetSecretAsync(string secretName)
        {
            try
            {
                string keyVaultUri = _configuration["AzureKeyVault:VaultUri"] ?? throw new ArgumentNullException(nameof(keyVaultUri));
                var client = new SecretClient(new Uri(keyVaultUri), new DefaultAzureCredential());
                KeyVaultSecret secret = await client.GetSecretAsync(secretName);
                return secret;
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error retrieving the secret {secretName}: {ex.Message}");
                return null;
            }
        }     

    }

}

The SecretClient in the code above is the client used to retrieve the secret from Azure KeyVault. The client is from the Azure.Security.KeyVault.Secrets Nuget package. The DefaultAzureCredential used here means you will have to login in advance before retrieving the secret. There are different credential types you can use instead, but this default credential type is the easiest to use for testing out. If you run the code above from the console, you can for example install the Azure Powershell module and run az login. The following appsettings file can be used for the code above.

appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",

  "AzureKeyVault": {
    "VaultUri": "https://yourkeyvaultsomewhereinazure.vault.azure.net/",
    "HmacSha256SecretName":  "YourExampleHmacStrongKey"
  }

}

Pseudonymizer class

The following pseudonymizer class uses HMAC-SHA256 to generate a pseudonym for a given message. This can be used for generating a value for sensitive data with a key. The key can be shared between sender and receiver to avoid exposing sensitive values in clear text.

Pseudonymizer.cs

using System.Text;

namespace MinimalApiSecurityExperimentsDotNet
{

    public class Pseudonymizer
    {
        private readonly byte[]? _key;

        public Pseudonymizer(string key)
        {
            if (!string.IsNullOrWhiteSpace(key))
            {
                _key = Encoding.UTF8.GetBytes(key);
            }
        }

        /// <summary>
        /// Outputs a pseudonymized version of the input string using HMAC SHA256.       
        /// </summary>
        /// <param name="message"></param>
        /// <param name="outputToHexString">Output to hex string if true. If false, base-64 string is returned</param>
        /// <returns></returns>
        public string? Pseudonymize(string? message, bool outputToHexString = true)
        {
            if (string.IsNullOrWhiteSpace(message) || _key == null)
            {
                return message;
            }
            using var hmac = new System.Security.Cryptography.HMACSHA256(_key);
            var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
            return outputToHexString ? Convert.ToHexString(hash) : Convert.ToBase64String(hash);
        }

        public bool Verify(string input, string pseudonym)
        {
            if (string.IsNullOrEmpty(input) || string.IsNullOrEmpty(pseudonym))
            {
                return false;
            }
            var computedPseudonym = Pseudonymize(input);
            return computedPseudonym == pseudonym;
        }

    }

}

The code above shows that we can both psedonymize and verify the pseudonym. Next up, a provider for creating an instance of this Pseudonymizer for use in ASP.net Core, for example.

PseudonymizerProvider.cs

namespace MinimalApiSecurityExperimentsDotNet.Extensions
{

    public class PseudonymizerProvider
    {

        private Pseudonymizer? _pseudonymizer;

        public void Set(Pseudonymizer pseudonymizer)
        {
            _pseudonymizer = pseudonymizer;
        }

        public Pseudonymizer Get()
        {
            return _pseudonymizer ?? throw new InvalidOperationException("Pseudonymizer not initalized");
        }

    }

}

The following Hosted service sets up the pseudonymizer service. It will start up when the Asp.net core application is starting, however after the DI container has been built.

PseudonymizerHostedService .cs

using Azure.Security.KeyVault.Secrets;

namespace MinimalApiSecurityExperimentsDotNet.Extensions
{

    public class PseudonymizerHostedService : IHostedService
    {

        private readonly IServiceProvider _provider;

        public PseudonymizerHostedService(IServiceProvider provider)
        {
            _provider = provider;
        }

        public async Task StartAsync(CancellationToken cancellationToken)
        {
            using var scope = _provider.CreateScope();
            var config = scope.ServiceProvider.GetRequiredService<IConfiguration>();
            var keyVaultRetriever = new KeyVaultSecretRetriever(config);
            var hmacSha256SecretName = config["AzureKeyVault:HmacSha256SecretName"];
            if (hmacSha256SecretName == null)
            {
                throw new InvalidOperationException($"Config '{hmacSha256SecretName}' not is missing.");
            }
            KeyVaultSecret? secret = await keyVaultRetriever.GetSecretAsync(hmacSha256SecretName);

            if (secret == null)
            {
                throw new InvalidOperationException($"Secret '{hmacSha256SecretName}' not found in Key Vault.");
            }

            var pseudonymizer = new Pseudonymizer(secret.Value);

            // Register the pseudonymizer in the pseudonymizerProvider
            var pseudonymizerProvider = scope.ServiceProvider.GetRequiredService<PseudonymizerProvider>();
            pseudonymizerProvider.Set(pseudonymizer);
        }

        public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;

    }

}

In the Program.cs of a sample Asp.net Web API with minimal API, the provider and the hosted service is registered before building the webapplication with .Build().

Program.cs

using MinimalApiSecurityExperimentsDotNet.Extensions;

namespace MinimalApiSecurityExperimentsDotNet
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            // Add services to the container.

            builder.Services.AddControllers();

            // Add Swagger services
            builder.Services.AddSwaggerGen();
            builder.Services.AddEndpointsApiExplorer();

            // Adding keyvault access via registering PseudonymizerHostedService 
            builder.Services.AddSingleton<PseudonymizerProvider>();
            builder.Services.AddHostedService<PseudonymizerHostedService>();

            var app = builder.Build();

            // Configure the HTTP request pipeline.

            app.UseHttpsRedirection();

            app.UseAuthorization();

            app.MapControllers();

            // Enable Swagger middleware 
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI();
            }
          
            app.MapGet("/generatestrongkey", () =>
            {
                return HmacSha256KeyGenerator.GenerateStrongKey();

            });

            app.MapGet("/pseudonymize", (string? key, string? value) =>
            {
                var pseudonym = new Pseudonymizer(key).Pseudonymize(value, outputToHexString: true);
                return Results.Json(pseudonym);
            });

            app.MapGet("/pseudonymize/verify", (string? key, string? value, string? pseudonym) =>
            {
                var pseudonymizer = new Pseudonymizer(key);
                var isValid = pseudonymizer.Verify(value, pseudonym);
                return Results.Json(isValid);
            });

            //Example using the injected singleton PseudonymizerProvider

            app.MapGet("/pseudo", (string? input, PseudonymizerProvider pseudonymizerProvider) =>
            {
                var pseudonymizer = pseudonymizerProvider.Get();
                var result = pseudonymizer.Pseudonymize(input); //pseudonymize the input using the inject Pseudonymizer instance. This will use HMAC SHA256 under the hood.
                return Results.Ok(new { message = input, pseudonym = result });
            });

            app.MapGet("/getkeyvaultsecret", async (string secretName) =>
            {
                var keyvaultRetriever = new KeyVaultSecretRetriever(builder.Configuration);
                var secret = await keyvaultRetriever.GetSecretAsync(secretName);
                return Results.Json(secret);
            });          

            app.Run(); 
        }
    }


}

The benefits of registering the pseudonymizer's hosted service and provider in the container is shown in the code above. We can easily pseudonymize and use Azure Key vault stored secret for the HMAC-SHA256 hash / pseudonoym.

 //Example using the injected singleton PseudonymizerProvider

app.MapGet("/pseudo", (string? input, PseudonymizerProvider pseudonymizerProvider) =>
{
    var pseudonymizer = pseudonymizerProvider.Get();
    var result = pseudonymizer.Pseudonymize(input); //pseudonymize the input using the inject Pseudonymizer instance. This will use HMAC SHA256 under the hood.
    return Results.Ok(new { message = input, pseudonym = result });
});

Summary

The pseudonymizer is initialized and registered as a singleton, it got a dependency against Azure Keyvault service at startup, but further on pseudonymizing can now use the singleton instance of the pseudonymizer that is registered by the hosted service at application startup. The pseudonymizer can for example pseudonymize sensitive values and hide their content. A receiver can be shown this pseudonymized value in the response. There pseudonymized value could also be described as for example one of these three descriptions:

• Key identifier / alias
• Obfuscated key named
• Derived key label

If the receiver got the shared secret key, since it is a one-way cryptographic algorithm, obtaining the original value is still only possible via a brute-force dictionary attack. However, it can be used for example as a pseudo-id that is shared and also identify for example a shared identifier, for example a patient identifier for multiple registered documents in a database for example. The pseudo id can be even stored in the database as a way of obfuscating sensitive values such a SSN / PID (Patient Id, SSN = Social Security Number).

Note about Keyvault access

Just because you know the url to an Azure keyvault and possible the secret's name, does of course not mean you got access to the secret. Inside the Azure Keyvault, clik on Access Control (IAM) to get started. To just test things out, follow the guide by clicking the button Add role assignment. Follow the wizard to gain access to your key vault. Search for role Key Vault Administrator. Click Next. Choose Select members to choose for example your own user. Click Next Click Review and assign. Finally you have added access to your Key vault. This must be done even for the Key vault you have created yourself. Of course, if you use Azure AD, you can choose different members here and authorize fine-grained access.

Share this article on LinkedIn.