Gathering detailed insights and metrics for @root/keypairs
Gathering detailed insights and metrics for @root/keypairs
Lightweight, Zero-Dependency RSA and EC/ECDSA crypto for Node.js and Browsers
0.10.3
2
MPL-2.0
JavaScript
Installations
npm install @root/keypairsDeveloper Guide
BETA
Typescript
No
Module System
CommonJS, UMD
Node Version
16.6.2
NPM Version
7.20.3
Releases
Unable to fetch releases
Languages
2
JavaScript
Shell
JavaScript (81.96%)
Shell (18.04%)
Developer
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MPL-2.0 License
2 Stars
16 Commits
1 Forks
1 Watchers
2 Branches
Updated on Sep 01, 2024
Maintainers
1
Package Meta Information
Latest Version
0.10.3
Package Id
@root/keypairs@0.10.3
Size
20.62 kB
NPM Version
7.20.3
Node Version
16.6.2
Published on
Aug 27, 2021
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
3
@root/keypairs
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).
Features
- Generate keypairs
- RSA
- ECDSA (P-256, P-384)
- PEM-to-JWK (and SSH-to-JWK)
- JWK-to-PEM (and JWK-to-SSH)
- Create JWTs (and sign JWS)
- SHA256 JWK Thumbprints
- JWK fetching. See Keyfetch.js
- OIDC
- Auth0
- CLI
- See keypairs-cli
- Node
- Browsers (Webpack >=5)
Progress
This is fully functional, but the re-usable code from ACME.js hasn't been fully teased out for the v2.0 release.
(SSH conversions have not yet made it to 2.0)
Usage
A brief introduction to the APIs:
1// generate a new keypair as jwk 2// (defaults to EC P-256 when no options are specified) 3Keypairs.generate().then(function (pair) { 4 console.log(pair.private); 5 console.log(pair.public); 6});
1// JWK to PEM 2// (supports various 'format' and 'encoding' options) 3return Keypairs.export({ jwk: pair.private, format: 'pkcs8' }).then(function ( 4 pem 5) { 6 console.log(pem); 7});
1// PEM to JWK 2return Keypairs.import({ pem: pem }).then(function (jwk) { 3 console.log(jwk); 4});
1// Thumbprint a JWK (SHA256) 2return Keypairs.thumbprint({ jwk: jwk }).then(function (thumb) { 3 console.log(thumb); 4});
1// Sign a JWT (aka compact JWS)
2return Keypairs.signJwt({
3 jwk: pair.private
4, iss: 'https://example.com'
5, exp: '1h'
6 // optional claims
7, claims: {
8 , sub: 'jon.doe@gmail.com'
9 }
10});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.
Webpack 5+ (for Browsers)
This package includes native browser versions of all special functions.
Since Webpack 5 now fully supports vanilla JavaScript and exclusive browser builds out-of-the-box, it's pretty easy to create a minimal config to use Keypairs in your browser projects:
webpack.config.js:
1'use strict'; 2 3var path = require('path'); 4 5module.exports = { 6 entry: './main.js', 7 mode: 'development', 8 devServer: { 9 contentBase: path.join(__dirname, 'dist'), 10 port: 3001 11 }, 12 output: { 13 publicPath: 'http://localhost:3001/' 14 }, 15 module: { 16 rules: [{}] 17 }, 18 plugins: [] 19};
main.js:
1'use strict'; 2 3var Keypairs = require('./keypairs.js'); 4 5Keypairs.generate().then(function (pair) { 6 console.log(pair.private); 7 console.log(pair.public); 8});
index.html:
1<!DOCTYPE html> 2<html> 3 <body> 4 <script src="./dist/main.js"></script> 5 </body> 6</html>
1npm install --save-dev webpack@5 2# Or, if webpack 5 is still in beta: npm install --save-dev webpack@next 3 4npm install --save-dev webpack-cli 5 6npx webpack --mode=production 7 8ls dist/main.js
API Overview
- generate (JWK)
- parse (PEM)
- parseOrGenerate (PEM to JWK)
- import (PEM-to-JWK)
- export (JWK-to-PEM, private or public)
- publish (Private JWK to Public JWK)
- thumbprint (JWK SHA256)
- signJwt
- signJws
Keypairs.generate(options)
Generates a public/private pair of JWKs as { private, public }
Option examples:
- RSA
{ kty: 'RSA', modulusLength: 2048 } - ECDSA
{ kty: 'ECDSA', namedCurve: 'P-256' }
When no options are supplied EC P-256 (also known as prime256v1 and secp256r1) is used by default.
Keypairs.parse(options)
Parses either a JWK (encoded as JSON) or an x509 (encdode as PEM) and gives back the JWK representation.
Option Examples:
- JWK { key: '{ "kty":"EC", ... }' }
- PEM { key: '-----BEGIN PRIVATE KEY-----\n...' }
- Public Key Only { key: '-----BEGIN PRIVATE KEY-----\n...', public: true }
- Must Have Private Key { key: '-----BEGIN PUBLIC KEY-----\n...', private: true }
Example:
1Keypairs.parse({ key: '...' }).catch(function (e) { 2 // could not be parsed or was a public key 3 console.warn(e); 4 return Keypairs.generate(); 5});
Keypairs.parseOrGenerate({ key, throw, [generate opts]... })
Parses the key. Logs a warning on failure, marches on.
(a shortcut for the above, with private: true)
Option Examples:
- parse key if exist, otherwise generate
{ key: process.env["PRIVATE_KEY"] } - generated key curve
{ key: null, namedCurve: 'P-256' } - generated key modulus
{ key: null, modulusLength: 2048 }
Example:
1Keypairs.parseOrGenerate({ key: process.env['PRIVATE_KEY'] }).then(function ( 2 pair 3) { 4 console.log(pair.public); 5});
Great for when you have a set of shared keys for development and randomly generated keys in
Keypairs.import({ pem: '...' }
Takes a PEM in pretty much any format (PKCS1, SEC1, PKCS8, SPKI) and returns a JWK.
Keypairs.export(options)
Exports a JWK as a PEM.
Exports PEM in PKCS8 (private) or SPKI (public) by default.
Options
1{ jwk: jwk 2, public: true 3, encoding: 'pem' // or 'der' 4, format: 'pkcs8' // or 'ssh', 'pkcs1', 'sec1', 'spki' 5}
Keypairs.publish({ jwk: jwk, exp: '3d', use: 'sig' })
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".
Keypairs.thumbprint({ jwk: jwk })
Promises a JWK-spec thumbprint: URL Base64-encoded sha256
Keypairs.signJwt({ jwk, header, claims })
Returns a JWT (otherwise known as a protected JWS in "compressed" format).
1{ jwk: jwk 2 // required claims 3, iss: 'https://example.com' 4, exp: '15m' 5 // all optional claims 6, claims: { 7 } 8}
Exp may be human readable duration (i.e. 1h, 15m, 30s) or a datetime in seconds.
Header defaults:
1{ kid: thumbprint 2, alg: 'xS256' 3, typ: 'JWT' 4}
Payload notes:
iat: nowis added by default (setfalseto disable)expmust be set (setfalseto disable)issshould 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.
Keypairs.signJws({ jwk, header, protected, payload })
This is provided for APIs like ACME (Let's Encrypt) that use uncompressed JWS (instead of JWT, which is compressed).
Options:
headernot what you think. Leave undefined unless you need this for the spec you're following.protectedis the typical JWT-style headerkidandalgwill be added by default (these are almost always required), setfalseexplicitly to disable
payloadcan be JSON, a string, or even a buffer (which gets URL Base64 encoded)- you must set this to something, even if it's an empty string, object, or Buffer
Additional Documentation
Keypairs.js provides a 1-to-1 mapping to the Rasha.js and Eckles.js APIs for the following:
- generate(options)
- import({ pem: '---BEGIN...' })
- export({ jwk: { kty: 'EC', ... })
- thumbprint({ jwk: jwk })
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:
Contributions
Did this project save you some time? Maybe make your day? Even save the day?
Please say "thanks" via Paypal or Patreon:
- Paypal: $5 | $10 | Any amount: paypal@therootcompany.com
- Patreon: https://patreon.com/rootprojects
Where does your contribution go?
Root is a collection of experts who trust each other and enjoy working together on deep-tech, Indie Web projects.
Our goal is to operate as a sustainable community.
Your contributions - both in code and especially monetarily - help to not just this project, but also our broader work of projects that fuel the Indie Web.
Also, we chat on Keybase in #rootprojects
Commercial Support
Do you need...
- more features?
- bugfixes, on your timeline?
- custom code, built by experts?
- commercial support and licensing?
Contact aj@therootcompany.com for support options.
Legal
Copyright AJ ONeal, Root 2018-2019
MPL-2.0 | Terms of Use | Privacy Policy
No vulnerabilities found.
No security vulnerabilities found.