commit 7591e3fbdd0288bfd4652e43afb8312ffe21241e Author: AJ ONeal Date: Thu May 10 15:19:09 2018 -0600 begin spec diff --git a/README.md b/README.md new file mode 100644 index 0000000..c0c53ba --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +Keypairs™ for node.js +=========================== + +JavaScript RSA and ECDSA utils that work on Windows, Mac, and Linux with or without C compiler. + +There are many different RSA and ECDSA libraries for node and it seems like they're +all incompatible in different ways. This isn't [yet another library](https://xkcd.com/927/), +but rather [one to rule them all and bind them](https://en.wikipedia.org/wiki/One_Ring). + +Features +======== + + * [x] RSA + * [] ECDSA (in-progress) + * [x] generate keypair + * [x] export to JWK + * [x] import from JWK + * [x] export to PEM + * [x] import from PEM + * [x] sign JWS + * [x] generate CSR (DER as PEM or base64url) + +API +=== + +* `Keypairs.generate(options)` + * options example `{ type: 'RSA' || 'ECDSA', bitlength: 2048 || 256 }` +* `Keypairs.import(options)` + * options example `{ pem: '...', crv: 'P-256' || 'ECC', bitlength: 2048 || 256 }` +* `Keypairs.export(options)` + * options example `{ private: true || false, pem: true || false }` +* `Keypairs.jws.sign(options)` + * options example `{ keypair, header, protected, payload }` +* `Keypairs.csr.generate(options)` + * options example `{ keypair, [ 'example.com' ] }` + +`keypair` can be any object with +any of these keys `publicKeyPem, privateKeyPem, publicKeyJwk, privateKeyJwk`. + +Examples +======== + +These are quick examples of how to use the library. +If you have a specific question, please open an issue. + +Keypairs.generate(options) +------------------- + +Simple RSA + +```js +return Keypairs.generate({ + type: 'RSA' +, bitlength: 2048 +}).then(function (keypair) { + + // we won't bother describing this object + // because it's only useful once exported + +}); +``` + +Advanced RSA + +```js +return Keypairs.generate({ + type: 'RSA' +, bitlength: 2048 // or 4096 +, exponent: 65537 // don't change this +, public: true // pre-cache public key +, pem: true // pre-export the PEM +, internal: true // pre-cache internal representations +}).then(function (keypair) { + + // we won't bother describing this object + // because it's only useful once exported + +}); +``` + +Keypairs.export(options) +------------------- + +Keypairs.import(options) +------------------- + +Keypairs.jws.sign(options) +------------------- + +Keypairs.csr.generate(options) +------------------- +