1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
# node-jws [](http://travis-ci.org/brianloveswords/node-jws)
An implementation of [JSON Web Signatures](http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html).
This was developed against `draft-ietf-jose-json-web-signature-08` and
implements the entire spec **except** X.509 Certificate Chain
signing/verifying (patches welcome).
There are both synchronous (`jws.sign`, `jws.verify`) and streaming
(`jws.createSign`, `jws.createVerify`) APIs.
# Install
```bash
$ npm install jws
```
# Usage
## jws.ALGORITHMS
Array of supported algorithms. The following algorithms are currently supported.
alg Parameter Value | Digital Signature or MAC Algorithm
----------------|----------------------------
HS256 | HMAC using SHA-256 hash algorithm
HS384 | HMAC using SHA-384 hash algorithm
HS512 | HMAC using SHA-512 hash algorithm
RS256 | RSASSA using SHA-256 hash algorithm
RS384 | RSASSA using SHA-384 hash algorithm
RS512 | RSASSA using SHA-512 hash algorithm
PS256 | RSASSA-PSS using SHA-256 hash algorithm
PS384 | RSASSA-PSS using SHA-384 hash algorithm
PS512 | RSASSA-PSS using SHA-512 hash algorithm
ES256 | ECDSA using P-256 curve and SHA-256 hash algorithm
ES384 | ECDSA using P-384 curve and SHA-384 hash algorithm
ES512 | ECDSA using P-521 curve and SHA-512 hash algorithm
none | No digital signature or MAC value included
## jws.sign(options)
(Synchronous) Return a JSON Web Signature for a header and a payload.
Options:
* `header`
* `payload`
* `secret` or `privateKey`
* `encoding` (Optional, defaults to 'utf8')
`header` must be an object with an `alg` property. `header.alg` must be
one a value found in `jws.ALGORITHMS`. See above for a table of
supported algorithms.
If `payload` is not a buffer or a string, it will be coerced into a string
using `JSON.stringify`.
Example
```js
const signature = jws.sign({
header: { alg: 'HS256' },
payload: 'h. jon benjamin',
secret: 'has a van',
});
```
## jws.verify(signature, algorithm, secretOrKey)
(Synchronous) Returns `true` or `false` for whether a signature matches a
secret or key.
`signature` is a JWS Signature. `header.alg` must be a value found in `jws.ALGORITHMS`.
See above for a table of supported algorithms. `secretOrKey` is a string or
buffer containing either the secret for HMAC algorithms, or the PEM
encoded public key for RSA and ECDSA.
Note that the `"alg"` value from the signature header is ignored.
## jws.decode(signature)
(Synchronous) Returns the decoded header, decoded payload, and signature
parts of the JWS Signature.
Returns an object with three properties, e.g.
```js
{ header: { alg: 'HS256' },
payload: 'h. jon benjamin',
signature: 'YOWPewyGHKu4Y_0M_vtlEnNlqmFOclqp4Hy6hVHfFT4'
}
```
## jws.createSign(options)
Returns a new SignStream object.
Options:
* `header` (required)
* `payload`
* `key` || `privateKey` || `secret`
* `encoding` (Optional, defaults to 'utf8')
Other than `header`, all options expect a string or a buffer when the
value is known ahead of time, or a stream for convenience.
`key`/`privateKey`/`secret` may also be an object when using an encrypted
private key, see the [crypto documentation][encrypted-key-docs].
Example:
```js
// This...
jws.createSign({
header: { alg: 'RS256' },
privateKey: privateKeyStream,
payload: payloadStream,
}).on('done', function(signature) {
// ...
});
// is equivalent to this:
const signer = jws.createSign({
header: { alg: 'RS256' },
});
privateKeyStream.pipe(signer.privateKey);
payloadStream.pipe(signer.payload);
signer.on('done', function(signature) {
// ...
});
```
## jws.createVerify(options)
Returns a new VerifyStream object.
Options:
* `signature`
* `algorithm`
* `key` || `publicKey` || `secret`
* `encoding` (Optional, defaults to 'utf8')
All options expect a string or a buffer when the value is known ahead of
time, or a stream for convenience.
Example:
```js
// This...
jws.createVerify({
publicKey: pubKeyStream,
signature: sigStream,
}).on('done', function(verified, obj) {
// ...
});
// is equivilant to this:
const verifier = jws.createVerify();
pubKeyStream.pipe(verifier.publicKey);
sigStream.pipe(verifier.signature);
verifier.on('done', function(verified, obj) {
// ...
});
```
## Class: SignStream
A `Readable Stream` that emits a single data event (the calculated
signature) when done.
### Event: 'done'
`function (signature) { }`
### signer.payload
A `Writable Stream` that expects the JWS payload. Do *not* use if you
passed a `payload` option to the constructor.
Example:
```js
payloadStream.pipe(signer.payload);
```
### signer.secret<br>signer.key<br>signer.privateKey
A `Writable Stream`. Expects the JWS secret for HMAC, or the privateKey
for ECDSA and RSA. Do *not* use if you passed a `secret` or `key` option
to the constructor.
Example:
```js
privateKeyStream.pipe(signer.privateKey);
```
## Class: VerifyStream
This is a `Readable Stream` that emits a single data event, the result
of whether or not that signature was valid.
### Event: 'done'
`function (valid, obj) { }`
`valid` is a boolean for whether or not the signature is valid.
### verifier.signature
A `Writable Stream` that expects a JWS Signature. Do *not* use if you
passed a `signature` option to the constructor.
### verifier.secret<br>verifier.key<br>verifier.publicKey
A `Writable Stream` that expects a public key or secret. Do *not* use if you
passed a `key` or `secret` option to the constructor.
# TODO
* It feels like there should be some convenience options/APIs for
defining the algorithm rather than having to define a header object
with `{ alg: 'ES512' }` or whatever every time.
* X.509 support, ugh
# License
MIT
```
Copyright (c) 2013-2015 Brian J. Brennan
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```
[encrypted-key-docs]: https://nodejs.org/api/crypto.html#crypto_sign_sign_private_key_output_format
|
