urlsign

README

urlsign

Package urlsign contains a signed URL mechanism, where a URL can safely be passed through a third party and validated before being served.

The Problem This Solves

If you have one service that generates a URL which is then passed to a browser, and the browser then uses that URL to access the resource from another service, you need a way to identify that this is a valid request. One method for doing that is to provide a URL that contains a token representing an HMAC over the content of the URL. This library implements that.

How it Works

urlsign generates a signing token for each URL based on all the other query parameters and the path. This can then be included as the token parameter appended to any signed URL. Using this token, the authenticity of the request can be validated.

Tokens have a validity window much like that of TOTP 2-factor auth systems. The library will validate a token from the current window, the previous window, and a future window. Since browsers use query parameters in caching determination, this token window will also affect the expiration of the cached resource in the browser.

This does not validate the hostname or scheme from the passed URL. Expiration/bucket size is an external, agreed parameter between the services.

Documentation

Overview

Package urlsign contains a signed URL mechanism, where a URL can safely be passed through a third party and validated before being served. This is useful for passing a URL to a browser, for example, from one service and having a second service be certain the URL was as authorized. This is handled by generating a signing token for each URL based on all the other query parameters and the path. This does not validate the hostname or scheme from the passed URL. Expiration/bucket size is an external, agreed parameter between the services.

Index

• Variables
• func GenerateToken(secret string, bucketSize time.Duration, baseTime time.Time, reqUrl string) string
• func IsValidSignature(secret string, bucketSize time.Duration, baseTime time.Time, reqUrl string) bool

Variables

var HmacAlgorithm = sha1.New

Yes, SHA1-HMAC is still considered secure, despite attacks on SHA-1 itself: https://crypto.stackexchange.com/questions/26510/why-is-hmac-sha1-still-considered-secure

Functions

func GenerateToken

func GenerateToken(secret string, bucketSize time.Duration, baseTime time.Time, reqUrl string) string

generateToken takes the secret generated by timedSecret and uses it to sign the url that is passed in, returning a hex-encoded string containing the signature.

func IsValidSignature

func IsValidSignature(secret string, bucketSize time.Duration, baseTime time.Time, reqUrl string) bool

isValidSignature takes a signed URL, grabs the token, generates an HMAC for the URL as expected, and compares the results. To work properly, this method assumes that the arguments in the URL are +sorted+ in string order. Additionally, it will test the current timeBucket and the previous and next buckets providing a 3*timeBucket window of validity for each signature.