Browse Source

begin spec

tags/v0.0.1
AJ ONeal 2 years ago
commit
7591e3fbdd
1 changed files with 92 additions and 0 deletions
  1. +92
    -0
      README.md

+ 92
- 0
README.md View File

@@ -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)
-------------------


Loading…
Cancel
Save