github.com/lestrrat-go/jwx/v2@v2.0.21/jws/README.md (about)

     1  # JWS [![Go Reference](https://pkg.go.dev/badge/github.com/lestrrat-go/jwx/v2/jws.svg)](https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws)
     2  
     3  Package 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/v2/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  
    12  How-to style documentation can be found in the [docs directory](../docs).
    13  
    14  Examples are located in the examples directory ([jws_example_test.go](../examples/jws_example_test.go))
    15  
    16  Supported 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
    43  import(
    44    "crypto/rand"
    45    "crypto/rsa"
    46    "log"
    47  
    48    "github.com/lestrrat-go/jwx/v2/jwa"
    49    "github.com/lestrrat-go/jwx/v2/jws"
    50  )
    51  
    52  func 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"), jws.WithKey(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, jws.WithKey(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
    80  func 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