ahmad-module 1.0.0

package/http-signature/README.md

@@ -0,0 +1,79 @@
+# node-http-signature
+
+node-http-signature is a node.js library that has client and server components
+for Joyent's [HTTP Signature Scheme](http_signing.md).
+
+## Usage
+
+Note the example below signs a request with the same key/cert used to start an
+HTTP server. This is almost certainly not what you actually want, but is just
+used to illustrate the API calls; you will need to provide your own key
+management in addition to this library.
+
+### Client
+
+```js
+var fs = require('fs');
+var https = require('https');
+var httpSignature = require('http-signature');
+
+var key = fs.readFileSync('./key.pem', 'ascii');
+
+var options = {
+  host: 'localhost',
+  port: 8443,
+  path: '/',
+  method: 'GET',
+  headers: {}
+};
+
+// Adds a 'Date' header in, signs it, and adds the
+// 'Authorization' header in.
+var req = https.request(options, function(res) {
+  console.log(res.statusCode);
+});
+
+
+httpSignature.sign(req, {
+  key: key,
+  keyId: './cert.pem'
+});
+
+req.end();
+```
+
+### Server
+
+```js
+var fs = require('fs');
+var https = require('https');
+var httpSignature = require('http-signature');
+
+var options = {
+  key: fs.readFileSync('./key.pem'),
+  cert: fs.readFileSync('./cert.pem')
+};
+
+https.createServer(options, function (req, res) {
+  var rc = 200;
+  var parsed = httpSignature.parseRequest(req);
+  var pub = fs.readFileSync(parsed.keyId, 'ascii');
+  if (!httpSignature.verifySignature(parsed, pub))
+    rc = 401;
+
+  res.writeHead(rc);
+  res.end();
+}).listen(8443);
+```
+
+## Installation
+
+    npm install http-signature
+
+## License
+
+MIT.
+
+## Bugs
+
+See <https://github.com/joyent/node-http-signature/issues>.

package/http-signature/http_signing.md

@@ -0,0 +1,363 @@
+# Abstract
+
+This document describes a way to add origin authentication, message integrity,
+and replay resistance to HTTP REST requests.  It is intended to be used over
+the HTTPS protocol.
+
+# Copyright Notice
+
+Copyright (c) 2011 Joyent, Inc. and the persons identified as document authors.
+All rights reserved.
+
+Code Components extracted from this document must include MIT License text.
+
+# Introduction
+
+This protocol is intended to provide a standard way for clients to sign HTTP
+requests.  RFC2617 (HTTP Authentication) defines Basic and Digest authentication
+mechanisms, and RFC5246 (TLS 1.2) defines client-auth, both of which are widely
+employed on the Internet today.  However, it is common place that the burdens of
+PKI prevent web service operators from deploying that methodology, and so many
+fall back to Basic authentication, which has poor security characteristics.
+
+Additionally, OAuth provides a fully-specified alternative for authorization
+of web service requests, but is not (always) ideal for machine to machine
+communication, as the key acquisition steps (generally) imply a fixed
+infrastructure that may not make sense to a service provider (e.g., symmetric
+keys).
+
+Several web service providers have invented their own schemes for signing
+HTTP requests, but to date, none have been placed in the public domain as a
+standard.  This document serves that purpose.  There are no techniques in this
+proposal that are novel beyond previous art, however, this aims to be a simple
+mechanism for signing these requests.
+
+# Signature Authentication Scheme
+
+The "signature" authentication scheme is based on the model that the client must
+authenticate itself with a digital signature produced by either a private
+asymmetric key (e.g., RSA) or a shared symmetric key (e.g., HMAC).  The scheme
+is parameterized enough such that it is not bound to any particular key type or
+signing algorithm.  However, it does explicitly assume that clients can send an
+HTTP `Date` header.
+
+## Authorization Header
+
+The client is expected to send an Authorization header (as defined in RFC 2617)
+with the following parameterization:
+
+    credentials := "Signature" params
+    params := 1#(keyId | algorithm | [headers] | [ext] | signature)
+    digitalSignature := plain-string
+
+    keyId := "keyId" "=" <"> plain-string <">
+    algorithm := "algorithm" "=" <"> plain-string <">
+    headers := "headers" "=" <"> 1#headers-value <">
+    ext := "ext" "=" <"> plain-string <">
+    signature := "signature" "=" <"> plain-string <">
+
+    headers-value := plain-string
+    plain-string   = 1*( %x20-21 / %x23-5B / %x5D-7E )
+
+### Signature Parameters
+
+#### keyId
+
+REQUIRED.  The `keyId` field is an opaque string that the server can use to look
+up the component they need to validate the signature.  It could be an SSH key
+fingerprint, an LDAP DN, etc.  Management of keys and assignment of `keyId` is
+out of scope for this document.
+
+#### algorithm
+
+REQUIRED. The `algorithm` parameter is used if the client and server agree on a
+non-standard digital signature algorithm.  The full list of supported signature
+mechanisms is listed below.
+
+#### headers
+
+OPTIONAL.  The `headers` parameter is used to specify the list of HTTP headers
+used to sign the request.  If specified, it should be a quoted list of HTTP
+header names, separated by a single space character.  By default, only one
+HTTP header is signed, which is the `Date` header.  Note that the list MUST be
+specified in the order the values are concatenated together during signing. To
+include the HTTP request line in the signature calculation, use the special
+`request-line` value.  While this is overloading the definition of `headers` in
+HTTP linguism, the request-line is defined in RFC 2616, and as the outlier from
+headers in useful signature calculation, it is deemed simpler to simply use
+`request-line` than to add a separate parameter for it.
+
+#### extensions
+
+OPTIONAL.  The `extensions` parameter is used to include additional information
+which is covered by the request.  The content and format of the string is out of
+scope for this document, and expected to be specified by implementors.
+
+#### signature
+
+REQUIRED.  The `signature` parameter is a `Base64` encoded digital signature
+generated by the client. The client uses the `algorithm` and `headers` request
+parameters to form a canonicalized `signing string`.  This `signing string` is
+then signed with the key associated with `keyId` and the algorithm
+corresponding to `algorithm`.  The `signature` parameter is then set to the
+`Base64` encoding of the signature.
+
+### Signing String Composition
+
+In order to generate the string that is signed with a key, the client MUST take
+the values of each HTTP header specified by `headers` in the order they appear.
+
+1. If the header name is not `request-line` then append the lowercased header
+   name followed with an ASCII colon `:` and an ASCII space ` `.
+2. If the header name is `request-line` then append the HTTP request line,
+   otherwise append the header value.
+3. If value is not the last value then append an ASCII newline `\n`. The string
+   MUST NOT include a trailing ASCII newline.
+
+# Example Requests
+
+All requests refer to the following request (body omitted):
+
+    POST /foo HTTP/1.1
+    Host: example.org
+    Date: Tue, 07 Jun 2014 20:51:35 GMT
+    Content-Type: application/json
+    Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+    Content-Length: 18
+
+The "rsa-key-1" keyId refers to a private key known to the client and a public
+key known to the server. The "hmac-key-1" keyId refers to key known to the
+client and server.
+
+## Default parameterization
+
+The authorization header and signature would be generated as:
+
+    Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",signature="Base64(RSA-SHA256(signing string))"
+
+The client would compose the signing string as:
+
+    date: Tue, 07 Jun 2014 20:51:35 GMT
+
+## Header List
+
+The authorization header and signature would be generated as:
+
+    Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",headers="(request-target) date content-type digest",signature="Base64(RSA-SHA256(signing string))"
+
+The client would compose the signing string as (`+ "\n"` inserted for
+readability):
+
+    (request-target) post /foo + "\n"
+    date: Tue, 07 Jun 2011 20:51:35 GMT + "\n"
+    content-type: application/json + "\n"
+    digest: SHA-256=Base64(SHA256(Body))
+
+## Algorithm
+
+The authorization header and signature would be generated as:
+
+    Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1",signature="Base64(HMAC-SHA1(signing string))"
+
+The client would compose the signing string as:
+
+    date: Tue, 07 Jun 2011 20:51:35 GMT
+
+# Signing Algorithms
+
+Currently supported algorithm names are:
+
+* rsa-sha1
+* rsa-sha256
+* rsa-sha512
+* dsa-sha1
+* hmac-sha1
+* hmac-sha256
+* hmac-sha512
+
+# Security Considerations
+
+## Default Parameters
+
+Note the default parameterization of the `Signature` scheme is only safe if all
+requests are carried over a secure transport (i.e., TLS).  Sending the default
+scheme over a non-secure transport will leave the request vulnerable to
+spoofing, tampering, replay/repudiation, and integrity violations (if using the
+STRIDE threat-modeling methodology).
+
+## Insecure Transports
+
+If sending the request over plain HTTP, service providers SHOULD require clients
+to sign ALL HTTP headers, and the `request-line`.  Additionally, service
+providers SHOULD require `Content-MD5` calculations to be performed to ensure
+against any tampering from clients.
+
+## Nonces
+
+Nonces are out of scope for this document simply because many service providers
+fail to implement them correctly, or do not adopt security specifications
+because of the infrastructure complexity.  Given the `header` parameterization,
+a service provider is fully enabled to add nonce semantics into this scheme by
+using something like an `x-request-nonce` header, and ensuring it is signed
+with the `Date` header.
+
+## Clock Skew
+
+As the default scheme is to sign the `Date` header, service providers SHOULD
+protect against logged replay attacks by enforcing a clock skew.  The server
+SHOULD be synchronized with NTP, and the recommendation in this specification
+is to allow 300s of clock skew (in either direction).
+
+## Required Headers to Sign
+
+It is out of scope for this document to dictate what headers a service provider
+will want to enforce, but service providers SHOULD at minimum include the
+`Date` header.
+
+# References
+
+## Normative References
+
+* [RFC2616] Hypertext Transfer Protocol -- HTTP/1.1
+* [RFC2617] HTTP Authentication: Basic and Digest Access Authentication
+* [RFC5246] The Transport Layer Security (TLS) Protocol Version 1.2
+
+## Informative References
+
+    Name: Mark Cavage (editor)
+    Company: Joyent, Inc.
+    Email: mark.cavage@joyent.com
+    URI: http://www.joyent.com
+
+# Appendix A - Test Values
+
+The following test data uses the RSA (1024b) keys, which we will refer
+to as `keyId=Test` in the following samples:
+
+    -----BEGIN PUBLIC KEY-----
+    MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3
+    6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6
+    Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw
+    oYi+1hqp1fIekaxsyQIDAQAB
+    -----END PUBLIC KEY-----
+
+    -----BEGIN RSA PRIVATE KEY-----
+    MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF
+    NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F
+    UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB
+    AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA
+    QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK
+    kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg
+    f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u
+    412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc
+    mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7
+    kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA
+    gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW
+    G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI
+    7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA==
+    -----END RSA PRIVATE KEY-----
+
+And all examples use this request:
+
+<!-- httpreq -->
+
+    POST /foo?param=value&pet=dog HTTP/1.1
+    Host: example.com
+    Date: Thu, 05 Jan 2014 21:31:40 GMT
+    Content-Type: application/json
+    Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+    Content-Length: 18
+
+    {"hello": "world"}
+
+<!-- /httpreq -->
+
+### Default
+
+The string to sign would be:
+
+<!-- sign {"name": "Default", "options": {"keyId":"Test", "algorithm": "rsa-sha256"}} -->
+<!-- signstring -->
+
+    date: Thu, 05 Jan 2014 21:31:40 GMT
+
+<!-- /signstring -->
+
+The Authorization header would be:
+
+<!-- authz -->
+
+    Authorization: Signature keyId="Test",algorithm="rsa-sha256",headers="date",signature="jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9HpFQlG7N4YcJPteKTu4MWCLyk+gIr0wDgqtLWf9NLpMAMimdfsH7FSWGfbMFSrsVTHNTk0rK3usrfFnti1dxsM4jl0kYJCKTGI/UWkqiaxwNiKqGcdlEDrTcUhhsFsOIo8VhddmZTZ8w="
+
+<!-- /authz -->
+
+### All Headers
+
+Parameterized to include all headers, the string to sign would be (`+ "\n"`
+inserted for readability):
+
+<!-- sign {"name": "All Headers", "options": {"keyId":"Test", "algorithm": "rsa-sha256", "headers": ["(request-target)", "host", "date", "content-type", "digest", "content-length"]}} -->
+<!-- signstring -->
+
+    (request-target): post /foo?param=value&pet=dog
+    host: example.com
+    date: Thu, 05 Jan 2014 21:31:40 GMT
+    content-type: application/json
+    digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+    content-length: 18
+
+<!-- /signstring -->
+
+The Authorization header would be:
+
+<!-- authz -->
+
+    Authorization: Signature keyId="Test",algorithm="rsa-sha256",headers="(request-target) host date content-type digest content-length",signature="Ef7MlxLXoBovhil3AlyjtBwAL9g4TN3tibLj7uuNB3CROat/9KaeQ4hW2NiJ+pZ6HQEOx9vYZAyi+7cmIkmJszJCut5kQLAwuX+Ms/mUFvpKlSo9StS2bMXDBNjOh4Auj774GFj4gwjS+3NhFeoqyr/MuN6HsEnkvn6zdgfE2i0="
+
+<!-- /authz -->
+
+## Generating and verifying signatures using `openssl`
+
+The `openssl` commandline tool can be used to generate or verify the signatures listed above.
+
+Compose the signing string as usual, and pipe it into the the `openssl dgst` command, then into `openssl enc -base64`, as follows:
+
+    $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
+      openssl dgst -binary -sign /path/to/private.pem -sha256 | \
+      openssl enc -base64
+    jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9Hp...
+    $
+
+The `-sha256` option is necessary to produce an `rsa-sha256` signature. You can select other hash algorithms such as `sha1` by changing this argument.
+
+To verify a signature, first save the signature data, Base64-decoded, into a file, then use `openssl dgst` again with the `-verify` option:
+
+    $ echo 'jKyvPcxB4JbmYY4mByy...' | openssl enc -A -d -base64 > signature
+    $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
+      openssl dgst -sha256 -verify /path/to/public.pem -signature ./signature
+    Verified OK
+    $
+
+## Generating and verifying signatures using `sshpk-sign`
+
+You can also generate and check signatures using the `sshpk-sign` tool which is
+included with the `sshpk` package in `npm`.
+
+Compose the signing string as above, and pipe it into `sshpk-sign` as follows:
+
+    $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
+      sshpk-sign -i /path/to/private.pem
+    jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9Hp...
+    $
+
+This will produce an `rsa-sha256` signature by default, as you can see using
+the `-v` option:
+
+    sshpk-sign: using rsa-sha256 with a 1024 bit key
+
+You can also use `sshpk-verify` in a similar manner:
+
+    $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
+      sshpk-verify -i ./public.pem -s 'jKyvPcxB4JbmYY...'
+    OK
+    $

package/http-signature/lib/index.js

@@ -0,0 +1,29 @@
+// Copyright 2015 Joyent, Inc.
+
+var parser = require('./parser');
+var signer = require('./signer');
+var verify = require('./verify');
+var utils = require('./utils');
+
+
+
+///--- API
+
+module.exports = {
+
+  parse: parser.parseRequest,
+  parseRequest: parser.parseRequest,
+
+  sign: signer.signRequest,
+  signRequest: signer.signRequest,
+  createSigner: signer.createSigner,
+  isSigner: signer.isSigner,
+
+  sshKeyToPEM: utils.sshKeyToPEM,
+  sshKeyFingerprint: utils.fingerprint,
+  pemToRsaSSHKey: utils.pemToRsaSSHKey,
+
+  verify: verify.verifySignature,
+  verifySignature: verify.verifySignature,
+  verifyHMAC: verify.verifyHMAC
+};