rsa-compat.js/README.md

97 lines
2.8 KiB
Markdown
Raw Normal View History

2016-07-30 15:20:44 +00:00
# rsa-compat.js
2016-07-30 19:59:48 +00:00
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 PromiseA = require('bluebird');
var RSA = PromiseA.promisify(require('rsa-compat').RSA);
var bitlen = 1024;
2016-07-30 20:04:57 +00:00
var exp = 65537;
2016-07-30 19:59:48 +00:00
var options = { public: true, pem: true, internal: true };
RSA.generateKeypair(bitlen, exp, options).then(function (keypair) {
console.log(keypair);
});
```
`console.log(keypair)`:
```javascript
2016-07-31 03:47:52 +00:00
{ publicKeyPem: '-----BEGIN RSA PUBLIC KEY-----\n/*base64 pem-encoded string*/'
, privateKeyPem: '-----BEGIN RSA PRIVATE KEY-----\n/*base64 pem-encoded string*/'
// http://crypto.stackexchange.com/questions/6593/what-data-is-saved-in-rsa-private-key
2016-07-30 19:59:48 +00:00
, privateKeyJwk: {
kty: "RSA"
, n: '/*base64 modulus n = pq*/'
2016-07-30 20:04:57 +00:00
, e: '/*base64 exponent (usually 65537)*/'
2016-07-30 19:59:48 +00:00
, 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 p1))*/
, dq: /*base64 Second exponent, used for CRT (dQ = d (mod q1))/
, qi: /*base64 Coefficient, used for CRT (qinv = q^1 (mod p))*/
}
, publicKeyJwk: {
kty: "RSA"
, n: /*base64 modulus n = pq*/
2016-07-30 20:04:57 +00:00
, e: /base64 exponent (usually 65537)*/
2016-07-30 19:59:48 +00:00
}
2016-07-31 03:47:52 +00:00
2016-07-30 19:59:48 +00:00
, _ursa: /*undefined or intermediate ursa object*/
2016-07-31 03:47:52 +00:00
, _ursaPublic: /*undefined or intermediate ursa object*/
2016-07-30 19:59:48 +00:00
, _forge: /*undefined or intermediate forge object*/
2016-07-31 03:47:52 +00:00
, _forgePublic: /*undefined or intermediate forge object*/
2016-07-30 19:59:48 +00:00
}
// NOTE: this object is JSON safe as _ursa and _forge will be ignored
```
API
---
* `RSA.generateKeypair(bitlen, exp, options, cb)`
2016-07-31 03:47:52 +00:00
* `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`
2016-07-30 19:59:48 +00:00
### 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) { /*...*/ });
2016-07-30 20:04:57 +00:00
RSA.generateKeypair(1024, 65537, { pem: false, public: false, internal: false }, function (keypair) { /*...*/ });
2016-07-30 19:59:48 +00:00
```
`bitlen`: *1024* (default), 2048, or 4096
2016-07-30 20:04:57 +00:00
`exp`: *65537* (default)
2016-07-30 19:59:48 +00:00
`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)
}
```