GithubHelp home page GithubHelp logo

http-hmac-spec's Introduction

HTTP HMAC Spec

This spec documents an HMAC message format for securing RESTful web APIs.

HMAC authentication is a shared-secret cryptography method where signatures are generated on the client side and validated by the server in order to authenticate the request. It is used by popular web services such as AWS and in protocols such as OAuth 1.0a to sign and authenticate API requests.

Spec

The pseudocode below illustrates construction of the HTTP "Authorization" header and signature:

Authorization = "Provider" + " " + ID + ":" + Signature;

Signature = Base64( Algorithm( SecretKey, Message ) );

Message =
    HTTP-Verb + "\n" +
    MD5( Request-Body ) + "\n" +
    Content-Type + "\n" +
    Date + "\n" +
    Custom-Headers + "\n"
    Resource
;

"\n" denotes a Unix-style line feed (ASCII code 0x0A).

Authorization Header

The value of the Authorization header contains the following parts:

  • Provider: The provider, for example "Acquia", "MyCompany", etc.
  • ID: The API key's unique identifier, which is an arbitrary string
  • Signature: The base64 encoded HMAC digest as described below

Signature

The signature is a base64 encoded binary HMAC digest generated from the following parts:

  • Algorithm: The cryptographic algorithm, e.g. "sha1", "sha256", etc.
  • SecretKey: The API key's shared secret
  • Message: The string being signed as described below

Message

The message is a concatenated string generated from the following parts:

  • HTTP-Verb: The uppercase HTTP request method e.g. "GET", "POST"
  • Request-Body: The raw body of the HTTP request
    • Note that in the message, the body is hashed using the MD5 algorithm
  • Content-Type: The lowercase value of the "Content-type" header
  • Date: The value of the "Date" header
    • The implementation may also read the timestamp from a custom header, e.g. x-acquia-timestamp
  • Custom-Headers: A canonicalized concatenation of optional custom headers
    • Each header is in x-custom-header: value format
    • Header names are lowercase
    • Multiple values are separated by a comma and space, e.g. value1, value2
    • Each header is separated by a newline in the concatenated string
  • Resource: The HTTP request path + query string, e.g. /resource?key=value

Further Reading

Refer to the wiki for frequently asked questions and a list of implementations in various languages.

Attribution

The algorithm is modeled after Amazon Web Service's implementation and in part is derived from the HMAC authentication system developed for Acquia Search.

http-hmac-spec's People

Contributors

cpliakas avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.