JavaScript implementation of JSON Web Signatures and JSON Web Tokens as needed by BrowserID.
-
libs contains third-party libraries that need to be included. See libs/dependencies.txt and libs/package.txt
-
This is written as CommonJS modules for node and such. Browserify is used to bundle it all up.
NOTE: this is written as future documentation of v0.2 APIs, which will not be backwards compatible with v0.1.
Overview
JSON Web Tokens (JWTs) look like:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
(line breaks are for readability)
JWTs are made up of three components, each base64url-encoded, joined by a period character. A JWT can be either a JWS (JSON Web Signature) or a JWE (JSON Web Encryption). In this library, we only consider JWS. Because JWT is effectively the abstract superclass of both JWS and JWE, we don't expose JWT APIs directly (as of v0.2.0). We simply expose a JWS API.
We use JWK (JSON Web Keys) to specify keys: http://tools.ietf.org/html/draft-ietf-jose-json-web-key-00
We use JWA (JSON Web Algorithms) to specify algorithms: http://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-00 (we add algorithm "DSA" to indicate DSA, with DS160 the standard DSA 1024/160.)
Usage
- for Node 4+ ensure that you are using g++ 4.8 (use
CXX=g++-4.8
to force that version) - npm install browserid-crypto
- in javascript:
require('browserid-crypto')
Basic API
var jwcrypto = ;; // random number generation is taken care of automatically// with auto-seeding that is optimized for server or browser// setup // more entropy can be added as follows// this can be useful to incorporate server-provided entropy// on clients that don't have any good entropy of their own// entropy should be either a 32 bit int, an array of ints, or a stringjwcrypto; // generate a key// we use DSA, which is "DS" in JSON Web Algorithm parlance// we use keysize 160, which has a specific interpretation based// on the algorithm, in this case DSA 1024/160, standard DSA.jwcrypto;
Assertions
Sometimes the JSON object to sign should be a standard assertion with pre-defined fields.
var assertion = assertion; // payload of the assertionvar payload = principal: email: 'some@dude.domain'; // add special fields which will be encoded properly// payload cannot contain reserved fieldsassertion;
Note that timestamps (for issuedAt
and expiresAt
) are integers containing the standard JS milliseconds-since-epoch, or objects with methods named .valueOf()
which will return such an integer. The assertion format currently serializes these integers verbatim; a future version may serialize them as seconds (instead of milliseconds) to conform with the JWT specifications.
Certs
Sometimes the JSON objects to sign are certificates
var cert = cert; var keyToCertify = keypairToCertifypublicKey;var principal = email: "someone@example.com"; var assertionParams = issuer: "foo.com" issuedAt: expiresAt: ; // cert params, kid is optional, others are requiredvar certParams = kid: "key-2012-08-11" publicKey: keyToCertify principal: principal; var additionalPayload = {}; // payload cannot contain reserved fieldscert; // bundle a cert chain and an assertionvar bundle = cert; { // function to get a public key for an issuer} var now = ; // verify just the chain of certscert; // verify a chain of certs and assertioncert;