auth

README

gauth

Authentication library written in Go.

Authentication

This authentication method is based on Amazon AWS REST authentication.

API uses Authorization-header with following format: "SCHEME public_id:signature".

Example:

"Authorization: VPS MTIzMjE0MTIzMg==:aHU5Ru1DykQh88JjO9bs1Kk0ybv3D1bTEEUo+1SYPg4="

Header's value is formed from scheme, public id, and hmac hash.

• Scheme: VPS
• Public ID: Base64 encoded sender's id
• Signature: Base64 encoded hmac hash
• HMAC-SHA256 (RFC 4868)

Workflow

1. Check if date is within allowed limit
2. Check signature
3. Check content-md5 hash if set

Root-URL

Root-url is /api/vX.

X is API version number.

Signature

Signature is used for authenticating sender and validating the integrity of the request. Both sender and receiver will calculate signature using same details and if signatures don't match, request is denied and HTTP 401 - Unauthorized is returned.

Signature is Base64 encoded HMAC-SHA256 hash in hex-format.

Format:

Signature = Base64( HMAC-SHA256( PrivateAPIKey, UTF-8-Encoding-Of( StringToSign ) ) )

StringToSign has following format:

StringToSign = HTTP-Verb + "\n" +
	Content-MD5 + "\n" +
	Content-Type + "\n" +
	Date + "\n" +
	CanonicalizedResource;

• HTTP-verb: Used HTTP method in capital letters. Newline is added to the end.
• E.q. GET
• Mandatory headers
• content-md5: Base64 encoded MD5-hash of the request's body. With GET-method, this is empty string (""). Newline is added to the end.
• content-type: Content type for the request, e.q. application/json. With GET-method, this is empty string (""). Newline is added to the end.
• date: Datetime in format Sun, 06 Nov 1994 08:49:37 GMT (RFC 1123). Newline is added to the end.
• CanonicalizedResource: Target route and with GET-method, also parameters are included.

Example where content-md5 and content-type are empty (""):

GET


Tue, 29 Jul 2014 07:09:12 GMT
/api/hello/tete?testi

CanonicalizedResource

How to build:

1. Create an empty string
2. Add root-url to this string
3. Add resource path without parameters to this string

• e.q. "/hello/world"

1. Sort query parameters
2. URL decode parameters and their values
3. Add ? to this string
4. Add query parameters to this string in format parametername=parametervalue&parametername=parametervalue

• If parameter has multiple values, separate those with comma (,)
  • E.q.parametername=parametervalue,parametervalue2&parametername=parametervalue,parametervalue2

Target:

https://www.example.com/api/hello/world?testi=1234&name=tester

CanonicalizedResource:

/api/hello/world?testi=1234&name=tester

Documentation

Index

• type Config
  • func (a *Config) AddAuth(r *http.Request) error
  • func (a *Config) Authenticate(h http.Handler) http.HandlerFunc
  • func (a *Config) CalcMD5(r *http.Request) (string, error)
  • func (a *Config) CanonicalString(m string, u *url.URL, h http.Header) string
  • func (a *Config) CheckDates(reqDate string) (bool, error)
  • func (a *Config) CheckHash(r *http.Request, publicHash, privateKey string) (bool, error)
  • func (a *Config) GetSignature(r *http.Request, apiKey string) (string, error)
  • func (a *Config) ParseAuthHeader(h string) (string, string, error)
  • func (a *Config) PrivateHash(id string) (string, string, error)

Types

type Config

type Config struct {
	RootURL      string
	PrivateKey   string
	PublicID     string
	SignHeaders  []string
	AllowedPaths map[string]string
	DB           *sql.DB
}

Main object

func (*Config) AddAuth

func (a *Config) AddAuth(r *http.Request) error

AddAuth calculates authorization information and adds it to Authorization-header

func (*Config) Authenticate

func (a *Config) Authenticate(h http.Handler) http.HandlerFunc

Authenticate is a HTTP middleware that will check if request has proper authorization header

func (*Config) CalcMD5

func (a *Config) CalcMD5(r *http.Request) (string, error)

Calculates content-md5 of the request body

func (*Config) CanonicalString

func (a *Config) CanonicalString(m string, u *url.URL, h http.Header) string

Constuct canonical string of the request

StringToSign = HTTP-Verb + "\n" +

Content-MD5 + "\n" +
Content-Type + "\n" +
Date + "\n" +
CanonicalizedResource;

Example

POST MDMyNjFlYWJkYTc4ZGEwNTc4NWZiZjYyZWI2YjUzYjU= application/json Wed, 21 Jan 2015 07:01:02 GMT /api/v1/groups/modes

func (*Config) CheckDates

func (a *Config) CheckDates(reqDate string) (bool, error)

CheckDates will check if request's date is within 10 minutes of current datetime

func (*Config) CheckHash

func (a *Config) CheckHash(r *http.Request, publicHash, privateKey string) (bool, error)

CheckHash will compare public hash against private hash and returns true if they are a match

func (*Config) GetSignature

func (a *Config) GetSignature(r *http.Request, apiKey string) (string, error)

Construct request's signature

Signature = Base64( HMAC-SHA256( PrivateAPIKey, UTF-8-Encoding-Of( StringToSign ) ) );

func (*Config) ParseAuthHeader

func (a *Config) ParseAuthHeader(h string) (string, string, error)

ParseAuthHeader will return public id and signature in base64 decoded format

func (*Config) PrivateHash

func (a *Config) PrivateHash(id string) (string, string, error)

PrivateHash will return private hash from database for given id