Skip to content

Commit 8d8b644

Browse files
stevencedrostevencedro
committed
refactor(#29): updated readme for RSA-OAEP. ECDSA example change.
1 parent 35ae19c commit 8d8b644

File tree

3 files changed

+208
-20
lines changed

3 files changed

+208
-20
lines changed

‎README.md

+121-14
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ An implementation of the W3C Web Cryptography API specification (https://www.w3.
2020
- [Parameter Definitions](#parameter-definitions-1)
2121
- [Examples](#examples-1)
2222
- [RSA-OAEP](#rsa-oaep)
23+
- [RSASSA-PKCS1-v1_5]()
2324
- [SHA](#sha)
2425
- [Contributing](#contributing)
2526
- [Appendix](#appendix)
@@ -124,16 +125,16 @@ func main() {
124125
panic(err)
125126
}
126127

127-
// key returned is a webcrypto.CryptoKeyPair
128-
cryptoKey := key.(webcrypto.CryptoKeyPair)
128+
// key returned is a webcrypto.CryptoKeyPair that contains two *ecdsa.CryptoKey
129+
cryptoKeyPair := key.(webcrypto.CryptoKeyPair)
129130

130131
// sign some data with the private key
131132
sig, err := webcrypto.Subtle().Sign(&webcrypto.Algorithm{
132133
Name: "ECDSA",
133134
Params: &ecdsa.Params{
134135
Hash: "SHA-256",
135136
},
136-
}, cryptoKey.PrivateKey(), []byte("test"))
137+
}, cryptoKeyPair.PrivateKey(), []byte("test"))
137138
if err != nil {
138139
panic(err)
139140
}
@@ -144,7 +145,7 @@ func main() {
144145
Params: &ecdsa.Params{
145146
Hash: "SHA-256",
146147
},
147-
}, cryptoKey.PublicKey(), sig, []byte("test"))
148+
}, cryptoKeyPair.PublicKey(), sig, []byte("test"))
148149
if err != nil {
149150
panic(err)
150151
}
@@ -154,7 +155,7 @@ func main() {
154155
}
155156

156157
// export the public/private key as webcrypto.JsonWebKey
157-
out, err := webcrypto.Subtle().ExportKey(webcrypto.Jwk, cryptoKey.PrivateKey())
158+
out, err := webcrypto.Subtle().ExportKey(webcrypto.Jwk, cryptoKeyPair.PrivateKey())
158159
if err != nil {
159160
panic(err)
160161
}
@@ -163,7 +164,7 @@ func main() {
163164
jwk := out.(*webcrypto.JsonWebKey)
164165

165166
// export the key as PKCS8
166-
out, err = webcrypto.Subtle().ExportKey(webcrypto.PKCS8, cryptoKey.PrivateKey())
167+
out, err = webcrypto.Subtle().ExportKey(webcrypto.PKCS8, cryptoKeyPair.PrivateKey())
167168
if err != nil {
168169
panic(err)
169170
}
@@ -345,39 +346,145 @@ func main() {
345346

346347
The **RSA-OAEP** algorithm is the implementation of operations described in [§22](https://www.w3.org/TR/WebCryptoAPI/#rsa-oaep) of the W3C specification.
347348

349+
`import "github.com/armortal/webcrypto-go/algorithms/rsa"`
350+
351+
#### Parameter Definitions
352+
353+
Below are the parameters that supported RSA-OAEP operations will take according to
354+
[§22.2](https://www.w3.org/TR/WebCryptoAPI/#rsa-oaep-registration).
355+
356+
#### OaepParams
357+
358+
As specified in [§22.3](https://www.w3.org/TR/WebCryptoAPI/#rsa-oaep-params)
359+
360+
| Field | Type | Description |
361+
| :---- | :--- | :---------- |
362+
| Label | `string` | The optional label/application data to associate with the message. |
363+
364+
#### Examples
365+
348366
```go
349367
package main
350368

351369
import (
370+
"fmt"
371+
"math/big"
372+
352373
"github.com/armortal/webcrypto-go"
353374
"github.com/armortal/webcrypto-go/algorithms/rsa"
354375
)
355376

356377
func main() {
357-
// generateKey
378+
// generate a new key
358379
key, err := webcrypto.Subtle().GenerateKey(
359-
&rsa.Algorithm{
380+
&webcrypto.Algorithm{
360381
Name: "RSA-OAEP",
361-
HashedKeyGenParams: &rsa.HashedKeyGenParams{
382+
Params: &rsa.HashedKeyGenParams{
362383
KeyGenParams: rsa.KeyGenParams{
363-
ModulusLength: 2048,
364-
PublicExponent: *big.NewInt(65537),
384+
ModulusLength: 2048,
385+
PublicExponent: *big.NewInt(65537),
365386
},
366387
Hash: "SHA-256",
367388
},
368-
369-
}, true, webcrypto.Decrypt, webcrypto.Encrypt)
389+
}, true, []webcrypto.KeyUsage{webcrypto.Decrypt, webcrypto.Encrypt})
370390

371391
if err != nil {
372392
panic(err)
373393
}
374394

375395
cryptoKeyPair := key.(webcrypto.CryptoKeyPair)
376396

377-
// do something with cryptoKeyPair
397+
// encrypt some data with an optional label
398+
encrypted, err := webcrypto.Subtle().Encrypt(&webcrypto.Algorithm{
399+
Name: "RSA-OAEP",
400+
Params: &rsa.OaepParams{
401+
Label: []byte("optional"),
402+
},
403+
}, cryptoKeyPair.PublicKey(), []byte("test"))
404+
405+
if err != nil {
406+
panic(err)
407+
}
408+
409+
// decrypt the data
410+
decrypted, err := webcrypto.Subtle().Decrypt(&webcrypto.Algorithm{
411+
Name: "RSA-OAEP",
412+
Params: &rsa.OaepParams{
413+
Label: []byte("optional"),
414+
},
415+
}, cryptoKeyPair.PrivateKey(), encrypted)
416+
417+
if err != nil {
418+
panic(err)
419+
}
420+
421+
// do something with decrypted data
422+
fmt.Println(string(decrypted))
423+
424+
// export the private/public key as jwk
425+
out, err := webcrypto.Subtle().ExportKey(webcrypto.Jwk, cryptoKeyPair.PrivateKey())
426+
if err != nil {
427+
panic(err)
428+
}
429+
430+
// do something with jwk
431+
jwk := out.(*webcrypto.JsonWebKey)
432+
433+
// import a key from jwk
434+
in, err := webcrypto.Subtle().ImportKey(webcrypto.Jwk, jwk, &webcrypto.Algorithm{
435+
Name: "RSA-OAEP",
436+
Params: &rsa.HashedImportParams{
437+
Hash: "SHA-256",
438+
},
439+
}, true, []webcrypto.KeyUsage{webcrypto.Decrypt})
440+
441+
if err != nil {
442+
panic(err)
443+
}
444+
445+
// do something with the imported key
446+
fmt.Println(in.Type())
378447
}
379448
```
380449

450+
### RSASSA-PKCS1-v1_5
451+
452+
This algorithm is currently not supported. However, parameter definitions for those used in [RSA-OAEP](#rsa-oaep) operations
453+
come from those defined in this algorithm.
454+
455+
#### Parameter Definitions
456+
457+
Below are the parameters that supported RSASSA-PKCS1-v1_5 operations will take according to
458+
[§20.2](https://www.w3.org/TR/WebCryptoAPI/#rsassa-pkcs1-registration).
459+
460+
##### KeyGenParams
461+
462+
As specified in [§20.3](https://www.w3.org/TR/WebCryptoAPI/#RsaKeyGenParams-dictionary)
463+
464+
| Field | Type | Description |
465+
| :---- | :--- | :---------- |
466+
| ModulusLength | `uint64` | The length, in bits, of the RSA modulus. |
467+
| PublicExponent | `*big.Int` | The RSA public exponent. |
468+
469+
##### HashedKeyGenParams
470+
471+
As specified in [§20.4](https://www.w3.org/TR/WebCryptoAPI/#RsaHashedKeyGenParams-dictionary)
472+
473+
| Field | Type | Description |
474+
| :---- | :--- | :---------- |
475+
| Hash | `string` | The [hash algorithm](#hash-algorithms) to use. |
476+
| ModulusLength | `uint64` | The length, in bits, of the RSA modulus. |
477+
| PublicExponent | `*big.Int` | The RSA public exponent. |
478+
479+
##### HashedImportParams
480+
481+
As specified in [§20.7](https://www.w3.org/TR/WebCryptoAPI/#RsaHashedImportParams-dictionary)
482+
483+
| Field | Type | Description |
484+
| :---- | :--- | :---------- |
485+
| Hash | `string` | The [hash algorithm](#hash-algorithms) to use. |
486+
487+
381488
## SHA
382489

383490
The **SHA** algorithm is the implementation of operations described in [§30](https://www.w3.org/TR/WebCryptoAPI/#sha) of the W3C specification.

‎examples/ecdsa/main.go

+6-6
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,16 @@ func main() {
2323
panic(err)
2424
}
2525

26-
// key returned is a webcrypto.CryptoKeyPair
27-
cryptoKey := key.(webcrypto.CryptoKeyPair)
26+
// key returned is a webcrypto.CryptoKeyPair that contains two *ecdsa.CryptoKey
27+
cryptoKeyPair := key.(webcrypto.CryptoKeyPair)
2828

2929
// sign some data with the private key
3030
sig, err := webcrypto.Subtle().Sign(&webcrypto.Algorithm{
3131
Name: "ECDSA",
3232
Params: &ecdsa.Params{
3333
Hash: "SHA-256",
3434
},
35-
}, cryptoKey.PrivateKey(), []byte("test"))
35+
}, cryptoKeyPair.PrivateKey(), []byte("test"))
3636
if err != nil {
3737
panic(err)
3838
}
@@ -43,7 +43,7 @@ func main() {
4343
Params: &ecdsa.Params{
4444
Hash: "SHA-256",
4545
},
46-
}, cryptoKey.PublicKey(), sig, []byte("test"))
46+
}, cryptoKeyPair.PublicKey(), sig, []byte("test"))
4747
if err != nil {
4848
panic(err)
4949
}
@@ -53,7 +53,7 @@ func main() {
5353
}
5454

5555
// export the public/private key as webcrypto.JsonWebKey
56-
out, err := webcrypto.Subtle().ExportKey(webcrypto.Jwk, cryptoKey.PrivateKey())
56+
out, err := webcrypto.Subtle().ExportKey(webcrypto.Jwk, cryptoKeyPair.PrivateKey())
5757
if err != nil {
5858
panic(err)
5959
}
@@ -62,7 +62,7 @@ func main() {
6262
jwk := out.(*webcrypto.JsonWebKey)
6363

6464
// export the key as PKCS8
65-
out, err = webcrypto.Subtle().ExportKey(webcrypto.PKCS8, cryptoKey.PrivateKey())
65+
out, err = webcrypto.Subtle().ExportKey(webcrypto.PKCS8, cryptoKeyPair.PrivateKey())
6666
if err != nil {
6767
panic(err)
6868
}

‎examples/rsaoaep/main.go

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
package main
2+
3+
import (
4+
"fmt"
5+
"math/big"
6+
7+
"github.com/armortal/webcrypto-go"
8+
"github.com/armortal/webcrypto-go/algorithms/rsa"
9+
)
10+
11+
func main() {
12+
// generate a new key
13+
key, err := webcrypto.Subtle().GenerateKey(
14+
&webcrypto.Algorithm{
15+
Name: "RSA-OAEP",
16+
Params: &rsa.HashedKeyGenParams{
17+
KeyGenParams: rsa.KeyGenParams{
18+
ModulusLength: 2048,
19+
PublicExponent: *big.NewInt(65537),
20+
},
21+
Hash: "SHA-256",
22+
},
23+
}, true, []webcrypto.KeyUsage{webcrypto.Decrypt, webcrypto.Encrypt})
24+
25+
if err != nil {
26+
panic(err)
27+
}
28+
29+
cryptoKeyPair := key.(webcrypto.CryptoKeyPair)
30+
31+
// encrypt some data with an optional label
32+
encrypted, err := webcrypto.Subtle().Encrypt(&webcrypto.Algorithm{
33+
Name: "RSA-OAEP",
34+
Params: &rsa.OaepParams{
35+
Label: []byte("optional"),
36+
},
37+
}, cryptoKeyPair.PublicKey(), []byte("test"))
38+
39+
if err != nil {
40+
panic(err)
41+
}
42+
43+
// decrypt the data
44+
decrypted, err := webcrypto.Subtle().Decrypt(&webcrypto.Algorithm{
45+
Name: "RSA-OAEP",
46+
Params: &rsa.OaepParams{
47+
Label: []byte("optional"),
48+
},
49+
}, cryptoKeyPair.PrivateKey(), encrypted)
50+
51+
if err != nil {
52+
panic(err)
53+
}
54+
55+
// do something with decrypted data
56+
fmt.Println(string(decrypted))
57+
58+
// export the private/public key as jwk
59+
out, err := webcrypto.Subtle().ExportKey(webcrypto.Jwk, cryptoKeyPair.PrivateKey())
60+
if err != nil {
61+
panic(err)
62+
}
63+
64+
// do something with jwk
65+
jwk := out.(*webcrypto.JsonWebKey)
66+
67+
// import a key from jwk
68+
in, err := webcrypto.Subtle().ImportKey(webcrypto.Jwk, jwk, &webcrypto.Algorithm{
69+
Name: "RSA-OAEP",
70+
Params: &rsa.HashedImportParams{
71+
Hash: "SHA-256",
72+
},
73+
}, true, []webcrypto.KeyUsage{webcrypto.Decrypt})
74+
75+
if err != nil {
76+
panic(err)
77+
}
78+
79+
// do something with the imported key
80+
fmt.Println(in.Type())
81+
}

0 commit comments

Comments
 (0)