README.md
1# JWS [](https://pkg.go.dev/github.com/lestrrat-go/jwx/jws)
2
3Package jws implements JWS as described in [RFC7515](https://tools.ietf.org/html/rfc7515) and [RFC7797](https://tools.ietf.org/html/rfc7797)
4
5* Parse and generate compact or JSON serializations
6* Sign and verify arbitrary payload
7* Use any of the keys supported in [github.com/lestrrat-go/jwx/jwk](../jwk)
8* Add arbitrary fields in the JWS object
9* Ability to add/replace existing signature methods
10* Respect "b64" settings for RFC7797
11
12How-to style documentation can be found in the [docs directory](../docs).
13
14Examples are located in the examples directory ([jws_example_test.go](../examples/jws_example_test.go))
15
16Supported signature algorithms:
17
18| Algorithm | Supported? | Constant in [jwa](../jwa) |
19|:----------------------------------------|:-----------|:-------------------------|
20| HMAC using SHA-256 | YES | jwa.HS256 |
21| HMAC using SHA-384 | YES | jwa.HS384 |
22| HMAC using SHA-512 | YES | jwa.HS512 |
23| RSASSA-PKCS-v1.5 using SHA-256 | YES | jwa.RS256 |
24| RSASSA-PKCS-v1.5 using SHA-384 | YES | jwa.RS384 |
25| RSASSA-PKCS-v1.5 using SHA-512 | YES | jwa.RS512 |
26| ECDSA using P-256 and SHA-256 | YES | jwa.ES256 |
27| ECDSA using P-384 and SHA-384 | YES | jwa.ES384 |
28| ECDSA using P-521 and SHA-512 | YES | jwa.ES512 |
29| ECDSA using secp256k1 and SHA-256 (2) | YES | jwa.ES256K |
30| RSASSA-PSS using SHA256 and MGF1-SHA256 | YES | jwa.PS256 |
31| RSASSA-PSS using SHA384 and MGF1-SHA384 | YES | jwa.PS384 |
32| RSASSA-PSS using SHA512 and MGF1-SHA512 | YES | jwa.PS512 |
33| EdDSA (1) | YES | jwa.EdDSA |
34
35* Note 1: Experimental
36* Note 2: Experimental, and must be toggled using `-tags jwx_es256k` build tag
37
38# SYNOPSIS
39
40## Sign and verify arbitrary data
41
42```go
43import(
44 "crypto/rand"
45 "crypto/rsa"
46 "log"
47
48 "github.com/lestrrat-go/jwx/jwa"
49 "github.com/lestrrat-go/jwx/jws"
50)
51
52func main() {
53 privkey, err := rsa.GenerateKey(rand.Reader, 2048)
54 if err != nil {
55 log.Printf("failed to generate private key: %s", err)
56 return
57 }
58
59 buf, err := jws.Sign([]byte("Lorem ipsum"), jwa.RS256, privkey)
60 if err != nil {
61 log.Printf("failed to created JWS message: %s", err)
62 return
63 }
64
65 // When you receive a JWS message, you can verify the signature
66 // and grab the payload sent in the message in one go:
67 verified, err := jws.Verify(buf, jwa.RS256, &privkey.PublicKey)
68 if err != nil {
69 log.Printf("failed to verify message: %s", err)
70 return
71 }
72
73 log.Printf("signed message verified! -> %s", verified)
74}
75```
76
77## Programatically manipulate `jws.Message`
78
79```go
80func ExampleMessage() {
81 // initialization for the following variables have been omitted.
82 // please see jws_example_test.go for details
83 var decodedPayload, decodedSig1, decodedSig2 []byte
84 var public1, protected1, public2, protected2 jws.Header
85
86 // Construct a message. DO NOT use values that are base64 encoded
87 m := jws.NewMessage().
88 SetPayload(decodedPayload).
89 AppendSignature(
90 jws.NewSignature().
91 SetSignature(decodedSig1).
92 SetProtectedHeaders(public1).
93 SetPublicHeaders(protected1),
94 ).
95 AppendSignature(
96 jws.NewSignature().
97 SetSignature(decodedSig2).
98 SetProtectedHeaders(public2).
99 SetPublicHeaders(protected2),
100 )
101
102 buf, err := json.MarshalIndent(m, "", " ")
103 if err != nil {
104 fmt.Printf("%s\n", err)
105 return
106 }
107
108 _ = buf
109}
110```
111
112
){kind=link}