Een tijdje geleden werkte ik aan een ASP.NET Web API, waarbij ik gebruik maakte van HMAC voor authenticatie. Het leek mij handig om hiervan een library te maken voor eventueel toekomstig gebruik.

Het project en documentatie zijn hier op GitHub te vinden.

Wat is HMAC?

HMAC staat voor Hash-based Message Authentication Code en kan gebruikt worden als een manier voor het authentiseren van HTTP requests.

Waar het simpelweg op neer komt is dat je van een unieke sleutel gebruik maakt waar alleen de client en server van afweten. Deze sleutel gebruik je om de client een signature te laten maken van een aantal belangrijke onderdelen van het HTTP request. Deze signature wordt vervolgens als header meegestuurd met het request. De server zal met dezelfde sleutel eenzelfde signature maken van het request en het resultaat vergelijken met de signature die in de header was meegestuurd. Komen ze overeen, dan is de authenticatie geslaagd. Zo niet, dan betekent het dat de client en server niet op dezelfde manier een signature van het request maken, of dat er onderweg iets aan het request is gewijzigd.

Om het af te maken controleer je aan de server kant meestal ook nog op het tijdstip van het request, wat ook wordt meegenomen in de signature. Als er een langere tijd zit tussen het aanmaken van het request en het ontvangen door de server kun je het request als ongeldig verklaren. Op deze manier kun je replay-attacks voorkomen.

Wat je uiteindelijk hebt is een zeer veilige manier van authenticatie. Ook voor onbeveiligde verbindingen.

Wat kun je met deze library?

• Een HTTP request signen;
• Een RestSharp request signen;
• Een request valideren;
• Makkelijk Content-MD5 hashes maken;
• Replay-attacks voorkomen;
• Het is volledig uitbreidbaar;
• Waarschijnlijk nog meer mooie dingen die ik ben vergeten om hier neer te zetten.

Welke assemblies zijn er?

• Donker.Hmac bevat alles om een request te kunnen signen en valideren;
• Donker.Hmac.Configuration bevat code voor het kunnen beheren van configuraties voor HMAC signing en validatie;
• Donker.Hmac.RestSharp is een implementatie/uitbreiding om RestSharp requests te kunnen signen.

Daarnaast zijn de volgende test projecten aanwezig:

• Donker.Hmac.Test bevat unit tests voor de Donker.Hmac assembly;
• Donker.Hmac.Configuration.Test bevat unit tests voor de Donker.Hmac.Configuration assembly;
• Donker.Hmac.RestSharp.Test bevat unit tests voor de Donker.Hmac.RestSharp assembly.

Wat heb je nodig voor deze library?

• Kennis van HTTP;
• Kennis van HMAC;
• Kennis van ASP.NET;
• Kennis van een hoop andere dingen.