|
1 year ago | |
---|---|---|
bin | 1 year ago | |
.gitignore | 1 year ago | |
README.md | 1 year ago | |
example.js | 1 year ago | |
keypairs.js | 1 year ago | |
package-lock.json | 1 year ago | |
package.json | 1 year ago | |
test.js | 1 year ago |
Lightweight JavaScript RSA and ECDSA utils that work on Windows, Mac, and Linux using modern node.js APIs (no need for C compiler).
A thin wrapper around Eckles.js (ECDSA) and Rasha.js (RSA).
A brief introduction to the APIs:
// generate a new keypair as jwk
// (defaults to EC P-256 when no options are specified)
Keypairs.generate().then(function (pair) {
console.log(pair.private);
console.log(pair.public);
});
// JWK to PEM
// (supports various 'format' and 'encoding' options)
return Keypairs.export({ jwk: pair.private, format: 'pkcs8' }).then(function (pem) {
console.log(pem);
});
// PEM to JWK
return Keypairs.import({ pem: pem }).then(function (jwk) {
console.log(jwk);
});
// Thumbprint a JWK (SHA256)
return Keypairs.thumbprint({ jwk: jwk }).then(function (thumb) {
console.log(thumb);
});
// Sign a JWT (aka compact JWS)
return Keypairs.signJwt({
jwk: pair.private
, iss: 'https://example.com'
, exp: '1h'
// optional claims
, claims: {
, sub: 'jon.doe@gmail.com'
}
});
By default ECDSA keys will be used since they've had native support in node much longer than RSA has, and they're smaller, and faster to generate.
Generates a public/private pair of JWKs as { private, public }
Option examples:
{ kty: 'RSA', modulusLength: 2048 }
{ kty: 'ECDSA', namedCurve: 'P-256' }
When no options are supplied EC P-256 (also known as prime256v1
and secp256r1
) is used by default.
Parses either a JWK (encoded as JSON) or an x509 (encdode as PEM) and gives back the JWK representation.
Option Examples:
Example:
Keypairs.parse({ key: '...' }).catch(function (e) {
// could not be parsed or was a public key
console.warn(e);
return Keypairs.generate();
});
Parses the key. Logs a warning on failure, marches on.
(a shortcut for the above, with private: true
)
Option Examples:
{ key: process.env["PRIVATE_KEY"] }
{ key: null, namedCurve: 'P-256' }
{ key: null, modulusLength: 2048 }
Example:
Keypairs.parseOrGenerate({ key: process.env["PRIVATE_KEY"] }).then(function (pair) {
console.log(pair.public);
})
Great for when you have a set of shared keys for development and randomly generated keys in
Takes a PEM in pretty much any format (PKCS1, SEC1, PKCS8, SPKI) and returns a JWK.
Exports a JWK as a PEM.
Exports PEM in PKCS8 (private) or SPKI (public) by default.
Options
{ jwk: jwk
, public: true
, encoding: 'pem' // or 'der'
, format: 'pkcs8' // or 'ssh', 'pkcs1', 'sec1', 'spki'
}
Promises a public key that adheres to the OIDC and Auth0 spec (plus expiry), suitable to be published to a JWKs URL:
{ "kty": "EC"
, "crv": "P-256"
, "x": "..."
, "y": "..."
, "kid": "..."
, "use": "sig"
, "exp": 1552074208
}
In particular this adds "use" and "exp".
Promises a JWK-spec thumbprint: URL Base64-encoded sha256
Returns a JWT (otherwise known as a protected JWS in "compressed" format).
{ jwk: jwk
// required claims
, iss: 'https://example.com'
, exp: '15m'
// all optional claims
, claims: {
}
}
Exp may be human readable duration (i.e. 1h, 15m, 30s) or a datetime in seconds.
Header defaults:
{ kid: thumbprint
, alg: 'xS256'
, typ: 'JWT'
}
Payload notes:
iat: now
is added by default (set false
to disable)exp
must be set (set false
to disable)iss
should be the base URL for JWK lookup (i.e. via OIDC, Auth0)Notes:
header
is actually the JWS protected
value, as all JWTs use protected headers (yay!)
and claims
are really the JWS payload
.
This is provided for APIs like ACME (Let's Encrypt) that use uncompressed JWS (instead of JWT, which is compressed).
Options:
header
not what you think. Leave undefined unless you need this for the spec you're following.protected
is the typical JWT-style header
kid
and alg
will be added by default (these are almost always required), set false
explicitly to disablepayload
can be JSON, a string, or even a buffer (which gets URL Base64 encoded)
Keypairs.js provides a 1-to-1 mapping to the Rasha.js and Eckles.js APIs for the following:
If you want to know the algorithm-specific options that are available for those you'll want to take a look at the corresponding documentation: