Browse Source

begin spec

tags/v0.0.1
AJ ONeal 1 year 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 @@
1
+Keypairs™ for node.js
2
+===========================
3
+
4
+JavaScript RSA and ECDSA utils that work on Windows, Mac, and Linux with or without C compiler.
5
+
6
+There are many different RSA and ECDSA libraries for node and it seems like they're
7
+all incompatible in different ways. This isn't [yet another library](https://xkcd.com/927/),
8
+but rather [one to rule them all and bind them](https://en.wikipedia.org/wiki/One_Ring).
9
+
10
+Features
11
+========
12
+
13
+  * [x] RSA
14
+  * [] ECDSA (in-progress)
15
+  * [x] generate keypair
16
+  * [x] export to JWK
17
+  * [x] import from JWK
18
+  * [x] export to PEM
19
+  * [x] import from PEM
20
+  * [x] sign JWS
21
+  * [x] generate CSR (DER as PEM or base64url)
22
+
23
+API
24
+===
25
+
26
+* `Keypairs.generate(options)`
27
+  * options example `{ type: 'RSA' || 'ECDSA', bitlength: 2048 || 256 }`
28
+* `Keypairs.import(options)`
29
+  * options example `{ pem: '...', crv: 'P-256' || 'ECC', bitlength: 2048 || 256 }`
30
+* `Keypairs.export(options)`
31
+  * options example `{ private: true || false, pem: true || false }`
32
+* `Keypairs.jws.sign(options)`
33
+  * options example `{ keypair, header, protected, payload }`
34
+* `Keypairs.csr.generate(options)`
35
+  * options example `{ keypair, [ 'example.com' ] }`
36
+
37
+`keypair` can be any object with
38
+any of these keys `publicKeyPem, privateKeyPem, publicKeyJwk, privateKeyJwk`.
39
+
40
+Examples
41
+========
42
+
43
+These are quick examples of how to use the library.
44
+If you have a specific question, please open an issue.
45
+
46
+Keypairs.generate(options)
47
+-------------------
48
+
49
+Simple RSA
50
+
51
+```js
52
+return Keypairs.generate({
53
+  type: 'RSA'
54
+, bitlength: 2048
55
+}).then(function (keypair) {
56
+
57
+  // we won't bother describing this object
58
+  // because it's only useful once exported
59
+
60
+});
61
+```
62
+
63
+Advanced RSA
64
+
65
+```js
66
+return Keypairs.generate({
67
+  type: 'RSA'
68
+, bitlength: 2048 // or 4096
69
+, exponent: 65537 // don't change this
70
+, public: true    // pre-cache public key
71
+, pem: true       // pre-export the PEM
72
+, internal: true  // pre-cache internal representations
73
+}).then(function (keypair) {
74
+
75
+  // we won't bother describing this object
76
+  // because it's only useful once exported
77
+
78
+});
79
+```
80
+
81
+Keypairs.export(options)
82
+-------------------
83
+
84
+Keypairs.import(options)
85
+-------------------
86
+
87
+Keypairs.jws.sign(options)
88
+-------------------
89
+
90
+Keypairs.csr.generate(options)
91
+-------------------
92
+

Loading…
Cancel
Save