From 7591e3fbdd0288bfd4652e43afb8312ffe21241e Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@daplie.com>
Date: Thu, 10 May 2018 15:19:09 -0600
Subject: [PATCH] begin spec

---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 README.md

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&trade; 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)
+-------------------
+