2 HTTP Hawk Authentication Scheme
3 Copyright (c) 2012-2014, Eran Hammer <eran@hammer.io>
17 // Generate an Authorization header for a given request
20 uri: 'http://example.com/resource?a=b' or object generated by hawk.utils.parseUri()
21 method: HTTP verb (e.g. 'GET', 'POST')
28 key: 'aoijedoaijsdlaksjdl',
29 algorithm: 'sha256' // 'sha1', 'sha256'
34 ext: 'application-specific', // Application specific data sent via the ext attribute
35 timestamp: Date.now() / 1000, // A pre-calculated timestamp in seconds
36 nonce: '2334f34f', // A pre-generated nonce
37 localtimeOffsetMsec: 400, // Time offset to sync with server time (ignored if timestamp provided)
38 payload: '{"some":"payload"}', // UTF-8 encoded string for body hash generation (ignored if hash provided)
39 contentType: 'application/json', // Payload content-type (ignored if hash provided)
40 hash: 'U4MKKSmiVxk37JCCrAVIjV=', // Pre-calculated payload hash
41 app: '24s23423f34dx', // Oz application id
42 dlg: '234sz34tww3sd' // Oz delegated-by application id
46 header: function (uri, method, options) {
55 if (!uri || (typeof uri !== 'string' && typeof uri !== 'object') ||
56 !method || typeof method !== 'string' ||
57 !options || typeof options !== 'object') {
59 result.err = 'Invalid argument type';
65 var timestamp = options.timestamp || hawk.utils.now(options.localtimeOffsetMsec);
67 // Validate credentials
69 var credentials = options.credentials;
73 !credentials.algorithm) {
75 result.err = 'Invalid credentials object';
79 if (hawk.crypto.algorithms.indexOf(credentials.algorithm) === -1) {
80 result.err = 'Unknown algorithm';
86 if (typeof uri === 'string') {
87 uri = hawk.utils.parseUri(uri);
90 // Calculate signature
94 nonce: options.nonce || hawk.utils.randomString(6),
96 resource: uri.resource,
105 result.artifacts = artifacts;
107 // Calculate payload hash
109 if (!artifacts.hash &&
110 (options.payload || options.payload === '')) {
112 artifacts.hash = hawk.crypto.calculatePayloadHash(options.payload, credentials.algorithm, options.contentType);
115 var mac = hawk.crypto.calculateMac('header', credentials, artifacts);
119 var hasExt = artifacts.ext !== null && artifacts.ext !== undefined && artifacts.ext !== ''; // Other falsey values allowed
120 var header = 'Hawk id="' + credentials.id +
121 '", ts="' + artifacts.ts +
122 '", nonce="' + artifacts.nonce +
123 (artifacts.hash ? '", hash="' + artifacts.hash : '') +
124 (hasExt ? '", ext="' + hawk.utils.escapeHeaderAttribute(artifacts.ext) : '') +
125 '", mac="' + mac + '"';
128 header += ', app="' + artifacts.app +
129 (artifacts.dlg ? '", dlg="' + artifacts.dlg : '') + '"';
132 result.field = header;
137 // Generate a bewit value for a given URI
140 uri: 'http://example.com/resource?a=b'
147 key: 'aoijedoaijsdlaksjdl',
148 algorithm: 'sha256' // 'sha1', 'sha256'
150 ttlSec: 60 * 60, // TTL in seconds
154 ext: 'application-specific', // Application specific data sent via the ext attribute
155 localtimeOffsetMsec: 400 // Time offset to sync with server time
159 bewit: function (uri, options) {
164 (typeof uri !== 'string') ||
166 typeof options !== 'object' ||
172 options.ext = (options.ext === null || options.ext === undefined ? '' : options.ext); // Zero is valid value
176 var now = hawk.utils.now(options.localtimeOffsetMsec);
178 // Validate credentials
180 var credentials = options.credentials;
184 !credentials.algorithm) {
189 if (hawk.crypto.algorithms.indexOf(credentials.algorithm) === -1) {
195 uri = hawk.utils.parseUri(uri);
197 // Calculate signature
199 var exp = now + options.ttlSec;
200 var mac = hawk.crypto.calculateMac('bewit', credentials, {
204 resource: uri.resource, // Maintain trailing '?' and query params
210 // Construct bewit: id\exp\mac\ext
212 var bewit = credentials.id + '\\' + exp + '\\' + mac + '\\' + options.ext;
213 return hawk.utils.base64urlEncode(bewit);
216 // Validate server response
219 request: object created via 'new XMLHttpRequest()' after response received
220 artifacts: object received from header().artifacts
222 payload: optional payload received
223 required: specifies if a Server-Authorization header is required. Defaults to 'false'
227 authenticate: function (request, credentials, artifacts, options) {
229 options = options || {};
231 var getHeader = function (name) {
233 return request.getResponseHeader ? request.getResponseHeader(name) : request.getHeader(name);
236 var wwwAuthenticate = getHeader('www-authenticate');
237 if (wwwAuthenticate) {
239 // Parse HTTP WWW-Authenticate header
241 var wwwAttributes = hawk.utils.parseAuthorizationHeader(wwwAuthenticate, ['ts', 'tsm', 'error']);
242 if (!wwwAttributes) {
246 if (wwwAttributes.ts) {
247 var tsm = hawk.crypto.calculateTsMac(wwwAttributes.ts, credentials);
248 if (tsm !== wwwAttributes.tsm) {
252 hawk.utils.setNtpOffset(wwwAttributes.ts - Math.floor((new Date()).getTime() / 1000)); // Keep offset at 1 second precision
256 // Parse HTTP Server-Authorization header
258 var serverAuthorization = getHeader('server-authorization');
259 if (!serverAuthorization &&
265 var attributes = hawk.utils.parseAuthorizationHeader(serverAuthorization, ['mac', 'ext', 'hash']);
272 nonce: artifacts.nonce,
273 method: artifacts.method,
274 resource: artifacts.resource,
275 host: artifacts.host,
276 port: artifacts.port,
277 hash: attributes.hash,
283 var mac = hawk.crypto.calculateMac('response', credentials, modArtifacts);
284 if (mac !== attributes.mac) {
288 if (!options.payload &&
289 options.payload !== '') {
294 if (!attributes.hash) {
298 var calculatedHash = hawk.crypto.calculatePayloadHash(options.payload, credentials.algorithm, getHeader('content-type'));
299 return (calculatedHash === attributes.hash);
302 message: function (host, port, message, options) {
306 if (!host || typeof host !== 'string' ||
307 !port || typeof port !== 'number' ||
308 message === null || message === undefined || typeof message !== 'string' ||
309 !options || typeof options !== 'object') {
316 var timestamp = options.timestamp || hawk.utils.now(options.localtimeOffsetMsec);
318 // Validate credentials
320 var credentials = options.credentials;
324 !credentials.algorithm) {
326 // Invalid credential object
330 if (hawk.crypto.algorithms.indexOf(credentials.algorithm) === -1) {
334 // Calculate signature
338 nonce: options.nonce || hawk.utils.randomString(6),
341 hash: hawk.crypto.calculatePayloadHash(message, credentials.algorithm)
344 // Construct authorization
349 nonce: artifacts.nonce,
350 hash: artifacts.hash,
351 mac: hawk.crypto.calculateMac('message', credentials, artifacts)
357 authenticateTimestamp: function (message, credentials, updateClock) { // updateClock defaults to true
359 var tsm = hawk.crypto.calculateTsMac(message.ts, credentials);
360 if (tsm !== message.tsm) {
364 if (updateClock !== false) {
365 hawk.utils.setNtpOffset(message.ts - Math.floor((new Date()).getTime() / 1000)); // Keep offset at 1 second precision
377 algorithms: ['sha1', 'sha256'],
379 calculateMac: function (type, credentials, options) {
381 var normalized = hawk.crypto.generateNormalizedString(type, options);
383 var hmac = CryptoJS['Hmac' + credentials.algorithm.toUpperCase()](normalized, credentials.key);
384 return hmac.toString(CryptoJS.enc.Base64);
387 generateNormalizedString: function (type, options) {
389 var normalized = 'hawk.' + hawk.crypto.headerVersion + '.' + type + '\n' +
391 options.nonce + '\n' +
392 (options.method || '').toUpperCase() + '\n' +
393 (options.resource || '') + '\n' +
394 options.host.toLowerCase() + '\n' +
395 options.port + '\n' +
396 (options.hash || '') + '\n';
399 normalized += options.ext.replace('\\', '\\\\').replace('\n', '\\n');
405 normalized += options.app + '\n' +
406 (options.dlg || '') + '\n';
412 calculatePayloadHash: function (payload, algorithm, contentType) {
414 var hash = CryptoJS.algo[algorithm.toUpperCase()].create();
415 hash.update('hawk.' + hawk.crypto.headerVersion + '.payload\n');
416 hash.update(hawk.utils.parseContentType(contentType) + '\n');
417 hash.update(payload);
419 return hash.finalize().toString(CryptoJS.enc.Base64);
422 calculateTsMac: function (ts, credentials) {
424 var hash = CryptoJS['Hmac' + credentials.algorithm.toUpperCase()]('hawk.' + hawk.crypto.headerVersion + '.ts\n' + ts + '\n', credentials.key);
425 return hash.toString(CryptoJS.enc.Base64);
430 // localStorage compatible interface
432 hawk.internals.LocalStorage = function () {
437 this.getItem = function (key) {
439 return this._cache.hasOwnProperty(key) ? String(this._cache[key]) : null;
442 this.setItem = function (key, value) {
444 this._cache[key] = String(value);
445 this.length = Object.keys(this._cache).length;
448 this.removeItem = function (key) {
450 delete this._cache[key];
451 this.length = Object.keys(this._cache).length;
454 this.clear = function () {
460 this.key = function (i) {
462 return Object.keys(this._cache)[i || 0];
469 storage: new hawk.internals.LocalStorage(),
471 setStorage: function (storage) {
473 var ntpOffset = hawk.utils.storage.getItem('hawk_ntp_offset');
474 hawk.utils.storage = storage;
476 hawk.utils.setNtpOffset(ntpOffset);
480 setNtpOffset: function (offset) {
483 hawk.utils.storage.setItem('hawk_ntp_offset', offset);
486 console.error('[hawk] could not write to storage.');
491 getNtpOffset: function () {
493 var offset = hawk.utils.storage.getItem('hawk_ntp_offset');
498 return parseInt(offset, 10);
501 now: function (localtimeOffsetMsec) {
503 return Math.floor(((new Date()).getTime() + (localtimeOffsetMsec || 0)) / 1000) + hawk.utils.getNtpOffset();
506 escapeHeaderAttribute: function (attribute) {
508 return attribute.replace(/\\/g, '\\\\').replace(/\"/g, '\\"');
511 parseContentType: function (header) {
517 return header.split(';')[0].replace(/^\s+|\s+$/g, '').toLowerCase();
520 parseAuthorizationHeader: function (header, keys) {
526 var headerParts = header.match(/^(\w+)(?:\s+(.*))?$/); // Header: scheme[ something]
531 var scheme = headerParts[1];
532 if (scheme.toLowerCase() !== 'hawk') {
536 var attributesString = headerParts[2];
537 if (!attributesString) {
542 var verify = attributesString.replace(/(\w+)="([^"\\]*)"\s*(?:,\s*|$)/g, function ($0, $1, $2) {
544 // Check valid attribute names
546 if (keys.indexOf($1) === -1) {
550 // Allowed attribute value characters: !#$%&'()*+,-./:;<=>?@[]^_`{|}~ and space, a-z, A-Z, 0-9
552 if ($2.match(/^[ \w\!#\$%&'\(\)\*\+,\-\.\/\:;<\=>\?@\[\]\^`\{\|\}~]+$/) === null) {
556 // Check for duplicates
558 if (attributes.hasOwnProperty($1)) {
573 randomString: function (size) {
575 var randomSource = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
576 var len = randomSource.length;
579 for (var i = 0; i < size; ++i) {
580 result[i] = randomSource[Math.floor(Math.random() * len)];
583 return result.join('');
586 uriRegex: /^([^:]+)\:\/\/(?:[^@]*@)?([^\/:]+)(?:\:(\d+))?([^#]*)(?:#.*)?$/, // scheme://credentials@host:port/resource#fragment
587 parseUri: function (input) {
589 var parts = input.match(hawk.utils.uriRegex);
591 return { host: '', port: '', resource: '' };
594 var scheme = parts[1].toLowerCase();
597 port: parts[3] || (scheme === 'http' ? '80' : (scheme === 'https' ? '443' : '')),
604 base64urlEncode: function (value) {
606 var wordArray = CryptoJS.enc.Utf8.parse(value);
607 var encoded = CryptoJS.enc.Base64.stringify(wordArray);
608 return encoded.replace(/\+/g, '-').replace(/\//g, '_').replace(/\=/g, '');
613 // $lab:coverage:off$
616 // Based on: Crypto-JS v3.1.2
617 // Copyright (c) 2009-2013, Jeff Mott. All rights reserved.
618 // http://code.google.com/p/crypto-js/
619 // http://code.google.com/p/crypto-js/wiki/License
621 var CryptoJS = CryptoJS || function (h, r) { var k = {}, l = k.lib = {}, n = function () { }, f = l.Base = { extend: function (a) { n.prototype = this; var b = new n; a && b.mixIn(a); b.hasOwnProperty("init") || (b.init = function () { b.$super.init.apply(this, arguments) }); b.init.prototype = b; b.$super = this; return b }, create: function () { var a = this.extend(); a.init.apply(a, arguments); return a }, init: function () { }, mixIn: function (a) { for (var b in a) a.hasOwnProperty(b) && (this[b] = a[b]); a.hasOwnProperty("toString") && (this.toString = a.toString) }, clone: function () { return this.init.prototype.extend(this) } }, j = l.WordArray = f.extend({ init: function (a, b) { a = this.words = a || []; this.sigBytes = b != r ? b : 4 * a.length }, toString: function (a) { return (a || s).stringify(this) }, concat: function (a) { var b = this.words, d = a.words, c = this.sigBytes; a = a.sigBytes; this.clamp(); if (c % 4) for (var e = 0; e < a; e++) b[c + e >>> 2] |= (d[e >>> 2] >>> 24 - 8 * (e % 4) & 255) << 24 - 8 * ((c + e) % 4); else if (65535 < d.length) for (e = 0; e < a; e += 4) b[c + e >>> 2] = d[e >>> 2]; else b.push.apply(b, d); this.sigBytes += a; return this }, clamp: function () { var a = this.words, b = this.sigBytes; a[b >>> 2] &= 4294967295 << 32 - 8 * (b % 4); a.length = h.ceil(b / 4) }, clone: function () { var a = f.clone.call(this); a.words = this.words.slice(0); return a }, random: function (a) { for (var b = [], d = 0; d < a; d += 4) b.push(4294967296 * h.random() | 0); return new j.init(b, a) } }), m = k.enc = {}, s = m.Hex = { stringify: function (a) { var b = a.words; a = a.sigBytes; for (var d = [], c = 0; c < a; c++) { var e = b[c >>> 2] >>> 24 - 8 * (c % 4) & 255; d.push((e >>> 4).toString(16)); d.push((e & 15).toString(16)) } return d.join("") }, parse: function (a) { for (var b = a.length, d = [], c = 0; c < b; c += 2) d[c >>> 3] |= parseInt(a.substr(c, 2), 16) << 24 - 4 * (c % 8); return new j.init(d, b / 2) } }, p = m.Latin1 = { stringify: function (a) { var b = a.words; a = a.sigBytes; for (var d = [], c = 0; c < a; c++) d.push(String.fromCharCode(b[c >>> 2] >>> 24 - 8 * (c % 4) & 255)); return d.join("") }, parse: function (a) { for (var b = a.length, d = [], c = 0; c < b; c++) d[c >>> 2] |= (a.charCodeAt(c) & 255) << 24 - 8 * (c % 4); return new j.init(d, b) } }, t = m.Utf8 = { stringify: function (a) { try { return decodeURIComponent(escape(p.stringify(a))) } catch (b) { throw Error("Malformed UTF-8 data"); } }, parse: function (a) { return p.parse(unescape(encodeURIComponent(a))) } }, q = l.BufferedBlockAlgorithm = f.extend({ reset: function () { this._data = new j.init; this._nDataBytes = 0 }, _append: function (a) { "string" == typeof a && (a = t.parse(a)); this._data.concat(a); this._nDataBytes += a.sigBytes }, _process: function (a) { var b = this._data, d = b.words, c = b.sigBytes, e = this.blockSize, f = c / (4 * e), f = a ? h.ceil(f) : h.max((f | 0) - this._minBufferSize, 0); a = f * e; c = h.min(4 * a, c); if (a) { for (var g = 0; g < a; g += e) this._doProcessBlock(d, g); g = d.splice(0, a); b.sigBytes -= c } return new j.init(g, c) }, clone: function () { var a = f.clone.call(this); a._data = this._data.clone(); return a }, _minBufferSize: 0 }); l.Hasher = q.extend({ cfg: f.extend(), init: function (a) { this.cfg = this.cfg.extend(a); this.reset() }, reset: function () { q.reset.call(this); this._doReset() }, update: function (a) { this._append(a); this._process(); return this }, finalize: function (a) { a && this._append(a); return this._doFinalize() }, blockSize: 16, _createHelper: function (a) { return function (b, d) { return (new a.init(d)).finalize(b) } }, _createHmacHelper: function (a) { return function (b, d) { return (new u.HMAC.init(a, d)).finalize(b) } } }); var u = k.algo = {}; return k }(Math);
622 (function () { var k = CryptoJS, b = k.lib, m = b.WordArray, l = b.Hasher, d = [], b = k.algo.SHA1 = l.extend({ _doReset: function () { this._hash = new m.init([1732584193, 4023233417, 2562383102, 271733878, 3285377520]) }, _doProcessBlock: function (n, p) { for (var a = this._hash.words, e = a[0], f = a[1], h = a[2], j = a[3], b = a[4], c = 0; 80 > c; c++) { if (16 > c) d[c] = n[p + c] | 0; else { var g = d[c - 3] ^ d[c - 8] ^ d[c - 14] ^ d[c - 16]; d[c] = g << 1 | g >>> 31 } g = (e << 5 | e >>> 27) + b + d[c]; g = 20 > c ? g + ((f & h | ~f & j) + 1518500249) : 40 > c ? g + ((f ^ h ^ j) + 1859775393) : 60 > c ? g + ((f & h | f & j | h & j) - 1894007588) : g + ((f ^ h ^ j) - 899497514); b = j; j = h; h = f << 30 | f >>> 2; f = e; e = g } a[0] = a[0] + e | 0; a[1] = a[1] + f | 0; a[2] = a[2] + h | 0; a[3] = a[3] + j | 0; a[4] = a[4] + b | 0 }, _doFinalize: function () { var b = this._data, d = b.words, a = 8 * this._nDataBytes, e = 8 * b.sigBytes; d[e >>> 5] |= 128 << 24 - e % 32; d[(e + 64 >>> 9 << 4) + 14] = Math.floor(a / 4294967296); d[(e + 64 >>> 9 << 4) + 15] = a; b.sigBytes = 4 * d.length; this._process(); return this._hash }, clone: function () { var b = l.clone.call(this); b._hash = this._hash.clone(); return b } }); k.SHA1 = l._createHelper(b); k.HmacSHA1 = l._createHmacHelper(b) })();
623 (function (k) { for (var g = CryptoJS, h = g.lib, v = h.WordArray, j = h.Hasher, h = g.algo, s = [], t = [], u = function (q) { return 4294967296 * (q - (q | 0)) | 0 }, l = 2, b = 0; 64 > b;) { var d; a: { d = l; for (var w = k.sqrt(d), r = 2; r <= w; r++) if (!(d % r)) { d = !1; break a } d = !0 } d && (8 > b && (s[b] = u(k.pow(l, 0.5))), t[b] = u(k.pow(l, 1 / 3)), b++); l++ } var n = [], h = h.SHA256 = j.extend({ _doReset: function () { this._hash = new v.init(s.slice(0)) }, _doProcessBlock: function (q, h) { for (var a = this._hash.words, c = a[0], d = a[1], b = a[2], k = a[3], f = a[4], g = a[5], j = a[6], l = a[7], e = 0; 64 > e; e++) { if (16 > e) n[e] = q[h + e] | 0; else { var m = n[e - 15], p = n[e - 2]; n[e] = ((m << 25 | m >>> 7) ^ (m << 14 | m >>> 18) ^ m >>> 3) + n[e - 7] + ((p << 15 | p >>> 17) ^ (p << 13 | p >>> 19) ^ p >>> 10) + n[e - 16] } m = l + ((f << 26 | f >>> 6) ^ (f << 21 | f >>> 11) ^ (f << 7 | f >>> 25)) + (f & g ^ ~f & j) + t[e] + n[e]; p = ((c << 30 | c >>> 2) ^ (c << 19 | c >>> 13) ^ (c << 10 | c >>> 22)) + (c & d ^ c & b ^ d & b); l = j; j = g; g = f; f = k + m | 0; k = b; b = d; d = c; c = m + p | 0 } a[0] = a[0] + c | 0; a[1] = a[1] + d | 0; a[2] = a[2] + b | 0; a[3] = a[3] + k | 0; a[4] = a[4] + f | 0; a[5] = a[5] + g | 0; a[6] = a[6] + j | 0; a[7] = a[7] + l | 0 }, _doFinalize: function () { var d = this._data, b = d.words, a = 8 * this._nDataBytes, c = 8 * d.sigBytes; b[c >>> 5] |= 128 << 24 - c % 32; b[(c + 64 >>> 9 << 4) + 14] = k.floor(a / 4294967296); b[(c + 64 >>> 9 << 4) + 15] = a; d.sigBytes = 4 * b.length; this._process(); return this._hash }, clone: function () { var b = j.clone.call(this); b._hash = this._hash.clone(); return b } }); g.SHA256 = j._createHelper(h); g.HmacSHA256 = j._createHmacHelper(h) })(Math);
624 (function () { var c = CryptoJS, k = c.enc.Utf8; c.algo.HMAC = c.lib.Base.extend({ init: function (a, b) { a = this._hasher = new a.init; "string" == typeof b && (b = k.parse(b)); var c = a.blockSize, e = 4 * c; b.sigBytes > e && (b = a.finalize(b)); b.clamp(); for (var f = this._oKey = b.clone(), g = this._iKey = b.clone(), h = f.words, j = g.words, d = 0; d < c; d++) h[d] ^= 1549556828, j[d] ^= 909522486; f.sigBytes = g.sigBytes = e; this.reset() }, reset: function () { var a = this._hasher; a.reset(); a.update(this._iKey) }, update: function (a) { this._hasher.update(a); return this }, finalize: function (a) { var b = this._hasher; a = b.finalize(a); b.reset(); return b.finalize(this._oKey.clone().concat(a)) } }) })();
625 (function () { var h = CryptoJS, j = h.lib.WordArray; h.enc.Base64 = { stringify: function (b) { var e = b.words, f = b.sigBytes, c = this._map; b.clamp(); b = []; for (var a = 0; a < f; a += 3) for (var d = (e[a >>> 2] >>> 24 - 8 * (a % 4) & 255) << 16 | (e[a + 1 >>> 2] >>> 24 - 8 * ((a + 1) % 4) & 255) << 8 | e[a + 2 >>> 2] >>> 24 - 8 * ((a + 2) % 4) & 255, g = 0; 4 > g && a + 0.75 * g < f; g++) b.push(c.charAt(d >>> 6 * (3 - g) & 63)); if (e = c.charAt(64)) for (; b.length % 4;) b.push(e); return b.join("") }, parse: function (b) { var e = b.length, f = this._map, c = f.charAt(64); c && (c = b.indexOf(c), -1 != c && (e = c)); for (var c = [], a = 0, d = 0; d < e; d++) if (d % 4) { var g = f.indexOf(b.charAt(d - 1)) << 2 * (d % 4), h = f.indexOf(b.charAt(d)) >>> 6 - 2 * (d % 4); c[a >>> 2] |= (g | h) << 24 - 8 * (a % 4); a++ } return j.create(c, a) }, _map: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=" } })();
627 hawk.crypto.internals = CryptoJS;
630 // Export if used as a module
632 if (typeof module !== 'undefined' && module.exports) {
633 module.exports = hawk;