rsa-compat.js/README.md

# rsa-compat.js

JavaScript RSA utils that work on Windows, Mac, and Linux with or without C compiler

In order to provide a module that "just works" everywhere, we mix and match methods
from `node.js` core, `ursa`, `forge`, and others.

(in the future we'd like to provide the same API to the browser)

Examples
--------

Generate an RSA Keypair:

```javascript
var RSA = require('rsa-compat').RSA;

var bitlen = 1024;
var exp = 65537;
var options = { public: true, pem: true, internal: true };

RSA.generateKeypair(bitlen, exp, options, function (err, keypair) {
  console.log(keypair);
});
```

Here's what the object might look like:

`console.log(keypair)`:
```javascript

{ publicKeyPem: '-----BEGIN RSA PUBLIC KEY-----\n/*base64 pem-encoded string*/'
, privateKeyPem: '-----BEGIN RSA PRIVATE KEY-----\n/*base64 pem-encoded string*/'
, privateKeyJwk: {
    kty: "RSA"
  , n: '/*base64 modulus n = pq*/'
  , e: '/*base64 exponent (usually 65537)*/'
  , d: '/*base64 private exponent (d = e^−1 (mod ϕ(n))/'
  , p: '/*base64 first prime*/'
  , q: '/*base64 second prime*/'
  , dp: '/*base64 first exponent for Chinese remainder theorem (dP = d (mod p−1))*/'
  , dq: '/*base64 Second exponent, used for CRT (dQ = d (mod q−1))/'
  , qi: '/*base64 Coefficient, used for CRT (qinv = q^−1 (mod p))*/'
  }
, publicKeyJwk: {
    kty: "RSA"
  , n: '/*base64 modulus n = pq*/'
  , e: '/*base64 exponent (usually 65537)*/'
  }

, _ursa: '/*undefined or intermediate ursa object*/'
, _ursaPublic: '/*undefined or intermediate ursa object*/'
, _forge: '/*undefined or intermediate forge object*/'
, _forgePublic: '/*undefined or intermediate forge object*/'
}
```

NOTE: this object is JSON safe as _ursa and _forge will be ignored

See http://crypto.stackexchange.com/questions/6593/what-data-is-saved-in-rsa-private-key to learn a little more about the meaning of the specific fields in the JWK.

API
---

* `RSA.generateKeypair(bitlen, exp, options, cb)`
* `RSA.exportPrivatePem(keypair)`
* `RSA.exportPublicPem(keypair)`
* `RSA.exportPrivateJwk(keypair)`
* `RSA.exportPublicJwk(keypair)`

`keypair` can be any object with any of these keys `publicKeyPem, privateKeyPem, publicKeyJwk, privateKeyJwk`

### RSA.generateKeypair(bitlen, exp, options, cb)

Create a private keypair and export it as PEM, JWK, and/or internal formats

```javascript
RSA.generateKeypair(null, null, null, function (keypair) { /*...*/ });

RSA.generateKeypair(1024, 65537, { pem: false, public: false, internal: false }, function (keypair) { /*...*/ });
```

`bitlen`: *1024* (default), 2048, or 4096

`exp`: *65537* (default)

`options`:
```javascript
{ public: false       // export public keys
, pem: false          // export pems
, jwk: true           // export jwks
, internal: false     // preserve internal intermediate formats (_ursa, _forge)
, thumbprint: false   // JWK sha256 thumbprint
, fingerprint: false  // NOT IMPLEMENTED (RSA key fingerprint)
}
```