twitst4tz

signer.js (13013B)

---

 // Copyright 2012 Joyent, Inc.  All rights reserved.
 
 var assert = require('assert-plus');
 var crypto = require('crypto');
 var http = require('http');
 var util = require('util');
 var sshpk = require('sshpk');
 var jsprim = require('jsprim');
 var utils = require('./utils');
 
 var sprintf = require('util').format;
 
 var HASH_ALGOS = utils.HASH_ALGOS;
 var PK_ALGOS = utils.PK_ALGOS;
 var InvalidAlgorithmError = utils.InvalidAlgorithmError;
 var HttpSignatureError = utils.HttpSignatureError;
 var validateAlgorithm = utils.validateAlgorithm;
 
 ///--- Globals
 
 var AUTHZ_FMT =
   'Signature keyId="%s",algorithm="%s",headers="%s",signature="%s"';
 
 ///--- Specific Errors
 
 function MissingHeaderError(message) {
   HttpSignatureError.call(this, message, MissingHeaderError);
 }
 util.inherits(MissingHeaderError, HttpSignatureError);
 
 function StrictParsingError(message) {
   HttpSignatureError.call(this, message, StrictParsingError);
 }
 util.inherits(StrictParsingError, HttpSignatureError);
 
 /* See createSigner() */
 function RequestSigner(options) {
   assert.object(options, 'options');
 
   var alg = [];
   if (options.algorithm !== undefined) {
     assert.string(options.algorithm, 'options.algorithm');
     alg = validateAlgorithm(options.algorithm);
   }
   this.rs_alg = alg;
 
   /*
    * RequestSigners come in two varieties: ones with an rs_signFunc, and ones
    * with an rs_signer.
    *
    * rs_signFunc-based RequestSigners have to build up their entire signing
    * string within the rs_lines array and give it to rs_signFunc as a single
    * concat'd blob. rs_signer-based RequestSigners can add a line at a time to
    * their signing state by using rs_signer.update(), thus only needing to
    * buffer the hash function state and one line at a time.
    */
   if (options.sign !== undefined) {
     assert.func(options.sign, 'options.sign');
     this.rs_signFunc = options.sign;
 
   } else if (alg[0] === 'hmac' && options.key !== undefined) {
     assert.string(options.keyId, 'options.keyId');
     this.rs_keyId = options.keyId;
 
     if (typeof (options.key) !== 'string' && !Buffer.isBuffer(options.key))
       throw (new TypeError('options.key for HMAC must be a string or Buffer'));
 
     /*
      * Make an rs_signer for HMACs, not a rs_signFunc -- HMACs digest their
      * data in chunks rather than requiring it all to be given in one go
      * at the end, so they are more similar to signers than signFuncs.
      */
     this.rs_signer = crypto.createHmac(alg[1].toUpperCase(), options.key);
     this.rs_signer.sign = function () {
       var digest = this.digest('base64');
       return ({
         hashAlgorithm: alg[1],
         toString: function () { return (digest); }
       });
     };
 
   } else if (options.key !== undefined) {
     var key = options.key;
     if (typeof (key) === 'string' || Buffer.isBuffer(key))
       key = sshpk.parsePrivateKey(key);
 
     assert.ok(sshpk.PrivateKey.isPrivateKey(key, [1, 2]),
       'options.key must be a sshpk.PrivateKey');
     this.rs_key = key;
 
     assert.string(options.keyId, 'options.keyId');
     this.rs_keyId = options.keyId;
 
     if (!PK_ALGOS[key.type]) {
       throw (new InvalidAlgorithmError(key.type.toUpperCase() + ' type ' +
         'keys are not supported'));
     }
 
     if (alg[0] !== undefined && key.type !== alg[0]) {
       throw (new InvalidAlgorithmError('options.key must be a ' +
         alg[0].toUpperCase() + ' key, was given a ' +
         key.type.toUpperCase() + ' key instead'));
     }
 
     this.rs_signer = key.createSign(alg[1]);
 
   } else {
     throw (new TypeError('options.sign (func) or options.key is required'));
   }
 
   this.rs_headers = [];
   this.rs_lines = [];
 }
 
 /**
  * Adds a header to be signed, with its value, into this signer.
  *
  * @param {String} header
  * @param {String} value
  * @return {String} value written
  */
 RequestSigner.prototype.writeHeader = function (header, value) {
   assert.string(header, 'header');
   header = header.toLowerCase();
   assert.string(value, 'value');
 
   this.rs_headers.push(header);
 
   if (this.rs_signFunc) {
     this.rs_lines.push(header + ': ' + value);
 
   } else {
     var line = header + ': ' + value;
     if (this.rs_headers.length > 0)
       line = '\n' + line;
     this.rs_signer.update(line);
   }
 
   return (value);
 };
 
 /**
  * Adds a default Date header, returning its value.
  *
  * @return {String}
  */
 RequestSigner.prototype.writeDateHeader = function () {
   return (this.writeHeader('date', jsprim.rfc1123(new Date())));
 };
 
 /**
  * Adds the request target line to be signed.
  *
  * @param {String} method, HTTP method (e.g. 'get', 'post', 'put')
  * @param {String} path
  */
 RequestSigner.prototype.writeTarget = function (method, path) {
   assert.string(method, 'method');
   assert.string(path, 'path');
   method = method.toLowerCase();
   this.writeHeader('(request-target)', method + ' ' + path);
 };
 
 /**
  * Calculate the value for the Authorization header on this request
  * asynchronously.
  *
  * @param {Func} callback (err, authz)
  */
 RequestSigner.prototype.sign = function (cb) {
   assert.func(cb, 'callback');
 
   if (this.rs_headers.length < 1)
     throw (new Error('At least one header must be signed'));
 
   var alg, authz;
   if (this.rs_signFunc) {
     var data = this.rs_lines.join('\n');
     var self = this;
     this.rs_signFunc(data, function (err, sig) {
       if (err) {
         cb(err);
         return;
       }
       try {
         assert.object(sig, 'signature');
         assert.string(sig.keyId, 'signature.keyId');
         assert.string(sig.algorithm, 'signature.algorithm');
         assert.string(sig.signature, 'signature.signature');
         alg = validateAlgorithm(sig.algorithm);
 
         authz = sprintf(AUTHZ_FMT,
           sig.keyId,
           sig.algorithm,
           self.rs_headers.join(' '),
           sig.signature);
       } catch (e) {
         cb(e);
         return;
       }
       cb(null, authz);
     });
 
   } else {
     try {
       var sigObj = this.rs_signer.sign();
     } catch (e) {
       cb(e);
       return;
     }
     alg = (this.rs_alg[0] || this.rs_key.type) + '-' + sigObj.hashAlgorithm;
     var signature = sigObj.toString();
     authz = sprintf(AUTHZ_FMT,
       this.rs_keyId,
       alg,
       this.rs_headers.join(' '),
       signature);
     cb(null, authz);
   }
 };
 
 ///--- Exported API
 
 module.exports = {
   /**
    * Identifies whether a given object is a request signer or not.
    *
    * @param {Object} object, the object to identify
    * @returns {Boolean}
    */
   isSigner: function (obj) {
     if (typeof (obj) === 'object' && obj instanceof RequestSigner)
       return (true);
     return (false);
   },
 
   /**
    * Creates a request signer, used to asynchronously build a signature
    * for a request (does not have to be an http.ClientRequest).
    *
    * @param {Object} options, either:
    *                   - {String} keyId
    *                   - {String|Buffer} key
    *                   - {String} algorithm (optional, required for HMAC)
    *                 or:
    *                   - {Func} sign (data, cb)
    * @return {RequestSigner}
    */
   createSigner: function createSigner(options) {
     return (new RequestSigner(options));
   },
 
   /**
    * Adds an 'Authorization' header to an http.ClientRequest object.
    *
    * Note that this API will add a Date header if it's not already set. Any
    * other headers in the options.headers array MUST be present, or this
    * will throw.
    *
    * You shouldn't need to check the return type; it's just there if you want
    * to be pedantic.
    *
    * The optional flag indicates whether parsing should use strict enforcement
    * of the version draft-cavage-http-signatures-04 of the spec or beyond.
    * The default is to be loose and support
    * older versions for compatibility.
    *
    * @param {Object} request an instance of http.ClientRequest.
    * @param {Object} options signing parameters object:
    *                   - {String} keyId required.
    *                   - {String} key required (either a PEM or HMAC key).
    *                   - {Array} headers optional; defaults to ['date'].
    *                   - {String} algorithm optional (unless key is HMAC);
    *                              default is the same as the sshpk default
    *                              signing algorithm for the type of key given
    *                   - {String} httpVersion optional; defaults to '1.1'.
    *                   - {Boolean} strict optional; defaults to 'false'.
    * @return {Boolean} true if Authorization (and optionally Date) were added.
    * @throws {TypeError} on bad parameter types (input).
    * @throws {InvalidAlgorithmError} if algorithm was bad or incompatible with
    *                                 the given key.
    * @throws {sshpk.KeyParseError} if key was bad.
    * @throws {MissingHeaderError} if a header to be signed was specified but
    *                              was not present.
    */
   signRequest: function signRequest(request, options) {
     assert.object(request, 'request');
     assert.object(options, 'options');
     assert.optionalString(options.algorithm, 'options.algorithm');
     assert.string(options.keyId, 'options.keyId');
     assert.optionalArrayOfString(options.headers, 'options.headers');
     assert.optionalString(options.httpVersion, 'options.httpVersion');
 
     if (!request.getHeader('Date'))
       request.setHeader('Date', jsprim.rfc1123(new Date()));
     if (!options.headers)
       options.headers = ['date'];
     if (!options.httpVersion)
       options.httpVersion = '1.1';
 
     var alg = [];
     if (options.algorithm) {
       options.algorithm = options.algorithm.toLowerCase();
       alg = validateAlgorithm(options.algorithm);
     }
 
     var i;
     var stringToSign = '';
     for (i = 0; i < options.headers.length; i++) {
       if (typeof (options.headers[i]) !== 'string')
         throw new TypeError('options.headers must be an array of Strings');
 
       var h = options.headers[i].toLowerCase();
 
       if (h === 'request-line') {
         if (!options.strict) {
           /**
            * We allow headers from the older spec drafts if strict parsing isn't
            * specified in options.
            */
           stringToSign +=
             request.method + ' ' + request.path + ' HTTP/' +
             options.httpVersion;
         } else {
           /* Strict parsing doesn't allow older draft headers. */
           throw (new StrictParsingError('request-line is not a valid header ' +
             'with strict parsing enabled.'));
         }
       } else if (h === '(request-target)') {
         stringToSign +=
           '(request-target): ' + request.method.toLowerCase() + ' ' +
           request.path;
       } else {
         var value = request.getHeader(h);
         if (value === undefined || value === '') {
           throw new MissingHeaderError(h + ' was not in the request');
         }
         stringToSign += h + ': ' + value;
       }
 
       if ((i + 1) < options.headers.length)
         stringToSign += '\n';
     }
 
     /* This is just for unit tests. */
     if (request.hasOwnProperty('_stringToSign')) {
       request._stringToSign = stringToSign;
     }
 
     var signature;
     if (alg[0] === 'hmac') {
       if (typeof (options.key) !== 'string' && !Buffer.isBuffer(options.key))
         throw (new TypeError('options.key must be a string or Buffer'));
 
       var hmac = crypto.createHmac(alg[1].toUpperCase(), options.key);
       hmac.update(stringToSign);
       signature = hmac.digest('base64');
 
     } else {
       var key = options.key;
       if (typeof (key) === 'string' || Buffer.isBuffer(key))
         key = sshpk.parsePrivateKey(options.key);
 
       assert.ok(sshpk.PrivateKey.isPrivateKey(key, [1, 2]),
         'options.key must be a sshpk.PrivateKey');
 
       if (!PK_ALGOS[key.type]) {
         throw (new InvalidAlgorithmError(key.type.toUpperCase() + ' type ' +
           'keys are not supported'));
       }
 
       if (alg[0] !== undefined && key.type !== alg[0]) {
         throw (new InvalidAlgorithmError('options.key must be a ' +
           alg[0].toUpperCase() + ' key, was given a ' +
           key.type.toUpperCase() + ' key instead'));
       }
 
       var signer = key.createSign(alg[1]);
       signer.update(stringToSign);
       var sigObj = signer.sign();
       if (!HASH_ALGOS[sigObj.hashAlgorithm]) {
         throw (new InvalidAlgorithmError(sigObj.hashAlgorithm.toUpperCase() +
           ' is not a supported hash algorithm'));
       }
       options.algorithm = key.type + '-' + sigObj.hashAlgorithm;
       signature = sigObj.toString();
       assert.notStrictEqual(signature, '', 'empty signature produced');
     }
 
     var authzHeaderName = options.authorizationHeaderName || 'Authorization';
 
     request.setHeader(authzHeaderName, sprintf(AUTHZ_FMT,
                                                options.keyId,
                                                options.algorithm,
                                                options.headers.join(' '),
                                                signature));
 
     return true;
   }
 
 };