old-keypairs.js/README.md

# Keypairs for node.js

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)](https://git.coolaj86.com/coolaj86/eckles.js/)
and [Rasha.js (RSA)](https://git.coolaj86.com/coolaj86/rasha.js/).

# Features

  * [x] Generate keypairs
    * [x] RSA
    * [x] ECDSA (P-256, P-384)
  * [x] PEM-to-JWK
  * [x] JWK-to-PEM
  * [x] SHA256 JWK Thumbprints
  * [ ] JWK fetching. See [Keyfetch.js](https://npmjs.com/packages/keyfetch/)
    * [ ] OIDC
    * [ ] Auth0

<!--

  * [ ] sign JWS
  * [ ] generate CSR (DER as PEM or base64url)

-->

# Usage

A brief (albeit somewhat nonsensical) introduction to the APIs:

```
Keypairs.generate().then(function (jwk) {
  return Keypairs.export({ jwk: jwk }).then(function (pem) {
    return Keypairs.import({ pem: pem }).then(function (jwk) {
      return Keypairs.thumbprint({ jwk: jwk }).then(function (thumb) {
        console.log(thumb);
      });
    });
  });
});
```

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.

## API

Each of these return a Promise.

* `Keypairs.generate(options)`
  * options example `{ kty: 'RSA', modulusLength: 2048 }`
  * options example `{ kty: 'ECDSA', namedCurve: 'P-256' }`
* `Keypairs.import(options)`
  * options example `{ pem: '...' }`
* `Keypairs.export(options)`
  * options example `{ jwk: jwk }`
  * options example `{ jwk: jwk, public: true }`
* `Keypairs.thumbprint({ jwk: jwk })`

<!--

* `Keypairs.jws.sign(options)`
  * options example `{ keypair, header, protected, payload }`
* `Keypairs.csr.generate(options)`
  * options example `{ keypair, [ 'example.com' ] }`

-->

# Full Documentation

Keypairs.js provides a 1-to-1 mapping to the Rasha.js and Eckles.js APIs.

The full RSA documentation is at [Rasha.js](https://git.coolaj86.com/coolaj86/rasha.js/)

The full ECDSA documentation is at [Eckles.js](https://git.coolaj86.com/coolaj86/eckles.js/)

Any option you pass to Keypairs will be passed directly to the corresponding API
of either Rasha or Eckles.