Skip to content

Scala utility for signing and verifying HMAC signatures passed in HTTP headers

License

Notifications You must be signed in to change notification settings

guardian/hmac-headers

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

56 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hmac-headers Scala version support Release

Introduction

hmac-headers is a Scala utility for signing and verifying HMAC signatures passed in a header in a HTTP request. Given a secret key shared between the client and the server, hmac-headers can do the following:

  • on the client side, create two strings which can be put in appropriate headers (generally the Date and Authorization headers) as part of the request:

  • on the server side, verify that the received headers are valid. Given a date string and a HMAC hash, it will check that:

    • the hash was computed using the same secret
    • the date is within the allowed time range (to avoid replay attacks)

Usage

In your build.sbt:

libraryDependencies += "com.gu" %% "hmac-headers" % "<version>" // find the latest version by checking this repo's tags

Releasing

Testing locally

You can publish locally by running:

# Test your signing setup works (you may need to follow the guide below first)
sbt +publishLocalSigned

# Publish locally so that other projects can use your local ivy repository
sbt +publishLocal

Publishing a new release

This repo uses gha-scala-library-release-workflow to automate publishing releases (both full & preview releases) - see Making a Release.

Verifying requests

import com.gu.hmac.HMACHeaders

val authorization = // extract HMAC from header
val date = // extract date from header
val uri = new URI(request.uri) // extract the URI from the request

hmacService.validateHMACHeaders(date, authorization, uri)) // returns a Boolean

Signing requests

import com.gu.hmac.HMACHeaders

val hmacHeaders = hmac.createHMACHeaderValues(new URI("example.com"))
// Add headers to your request as appropriate, e.g. in Play
ws.url("example.com")
  .withHeaders(HeaderNames.DATE -> hmacHeaders.date, HeaderNames.AUTHORIZATION -> hmacHeaders.token)

About

Scala utility for signing and verifying HMAC signatures passed in HTTP headers

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages