github.com/lestrrat-go/jwx/v2@v2.0.21/docs/00-anatomy.md (about)

     1  # 1. Anatomy of JOSE and JWX
     2  
     3  In this article we will briefly go over what JOSE is, and how each JWX libraries map to the respective RFCs.
     4  
     5  ---
     6  
     7  # JOSE Overview
     8  
     9  Javascript Object Signing and Encryption is mainly comprised of specifications that span over 5 RFCs: namely RFC7515, RFC7516, RFC7517, RFC7518, and RFC7519.
    10  
    11  * [RFC 7515 - JSON Web Signature (JWS)](https://tools.ietf.org/html/rfc7515)
    12  * [RFC 7516 - JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516)
    13  * [RFC 7517 - JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517)
    14  * [RFC 7518 - JSON Web Algorithms (JWA)](https://tools.ietf.org/html/rfc7518)
    15  * [RFC 7519 - JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519)
    16  
    17  As there are many RFCs involved, at first it could be daunting. But here is a breakdown for beginners.
    18  
    19  While there are other standards and RFCs available related to JOSE such as extensions like ES256K, the above 5 concepts are at the core.
    20  
    21  JWX is a Go specific implementation of the JOSE ecosystem, and attempts to do this as cleanly as possible.
    22  
    23  # JWT - RFC7519
    24  
    25  First, you are probably here because you were trying to work with JWTs, which is described in RFC7519. 
    26  
    27  JWTs are implemented in github.com/lestrrat-go/jwx/v2/jwt package. There is also a package to deal with OpenID extensions in github.com/lestrrat-go/jwx/v2/jwt/openid. 
    28  
    29  In its essence, there is nothing special about JWTs: they are just a standardized format to exchange some piece of information.
    30  
    31  Most of the times this information must be integrity checked using signatures, securely encrypted, or both.
    32  
    33  While they are referenced from RFC7519, the standardized message formats for signed and/or encrypted JWTs are not in the same RFC.
    34  
    35  As a side note, many libraries bundle these signature/encryption features into one JWT package, and API becomes tightly coupled with the JWT, which I find confusing and hard to fix/extend- which is part of the reason why JWX was born.
    36  
    37  ## Documentation for `github.com/lestrrat-go/jwx/v2/jwt`
    38  
    39  * [FAQ-style HOW-TOs](./01-jwt.md)
    40  * [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwt)
    41  
    42  # JWS - RFC7515
    43  
    44  RFC7515 describes JWS, which is used to sign payloads. The format is not necessarily for JWTs: it can sign any arbitrary piece of data.
    45  
    46  The signed content can be encoded in two different formats. The most common one is called the compact form, and takes the form of three base64 encoded strings, concatenated by a single period ("."). The other format takes the form of a JSON object.
    47  
    48  ```
    49  # An example of a "compact" JWS message
    50  eyJhbGciOiJFUzI1NiJ9.SGVsbG8sIFdvcmxkCg.3q5N5JyFphiJolUZuBuUZhuWDfmLDR__rZe3lnuaxWe3bfrfvJS9HmUUhie56NqkyN7vjOl8hm6tzJKTc2oNsg
    51  ```
    52  
    53  Please note that a JWS message may take three forms: compact, full JSON, and flattened JSON serialization.
    54  
    55  ```mermaid
    56  graph TD
    57      RawData[Raw Data] --> |"three base64 encoded segments,<br/> concatenated with ."| Compact[Compact Serialization]
    58      RawData --> | JSON | JSON[JSON Serialization]
    59      JSON --> |"does NOT have'signature'"| FullJSON[Full JSON Serialization]
    60      JSON --> |"has 'signature'"| Flat[Flattened JSON Serialization]
    61  ```
    62  
    63  JWS is implemented in github.com/lestrrat-go/jwx/v2/jws package. This package provides ways to sign arbitrary payload into JWS message, and ways to verify them.
    64  
    65  ## Documentation for `github.com/lestrrat-go/jwx/v2/jws`
    66  
    67  * [FAQ-style HOW-TOs](./02-jws.md)
    68  * [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jws)
    69  
    70  # JWE - RFC7516
    71  
    72  RFC7516 describes JWE which is used to encrypt data. Similar to JWS, JWE describes the standardized format to encrypt any arbitrary data, not just JWTs.
    73  
    74  And again, similar to JWS, JWE can encode data into two different formats, one of which consists of 5 base64 encoded strings concatenated by a single period ("."). The other format takes the form of a JSON object.
    75  
    76  ```
    77  # An example of JWE message
    78  eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTE5MkdDTSIsImVwayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IndMckhLNnBTLXZzdmhQZUNfNTN0ZWpxYzZIZUFsMllRWDRmY1hPNGV1bmciLCJ5IjoiV2V3bFdKazJ4QWJYSXE3WFJ6aVlZa2lxMjJfOF9TQ0VsbTA1Vm1iUGhFWSJ9fQ..7UTcbVpz-Ed1Q0wq.sneVfeTeAvzZNSMGpQ.JNo1BbDaKB-Q1mWaBNmdow
    79  ```
    80  
    81  JWE is implemented in github.com/lestrrat-go/jwe package. This package provides tools to encrypt payload into JWE messages, and tools to decrypt them.
    82  
    83  ## Documentation for `github.com/lestrrat-go/jwx/v2/jwe`
    84  
    85  * [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwe)
    86  
    87  # JWK - RFC7517
    88  
    89  So JWTs can be signed and/or encrypted using JWS and JWE. However in order to do either operation one needs some sort of a key. This is where RFC757 which describes JWK comes into play.
    90  
    91  JWKs describe formats to describe keys, such as RSA keys, Elliptic Curve keys, symmetric keys, etc. Each family of keys have a slightly different, unique format, but they are all encoded as JSON objects. 
    92  
    93  ```
    94  # An example of a JWK
    95  {
    96    "crv": "P-256",
    97    "d": "vVLuV63SADBsZrixRXs3hcteS7SaBrMPnxERz6G1xZ8",
    98    "kty": "EC",
    99    "x": "uNs7UU1KU9nug9QrfxLmxLtYZLQDnYcX7_J3zkTkhCk",
   100    "y": "IGsWjOsDHFbeiQg-Reih-a1BsijmV2RUPPGswl8TRTI"
   101  }
   102  ```
   103  
   104  JWK is implemented in github.com/lestrrat-go/jwx/v2/jwk package. This package provides ways to generate, read, and manipulate JWKs, convert them to and from raw key formats (e.g. "crypto/rsa".PrivateKey to JWK and vice versa). It can also work with PEM-encoded keys.
   105  
   106  ## Documentation for `github.com/lestrrat-go/jwx/v2/jwk`
   107  
   108  * [FAQ-style HOW-TOs](./04-jwk.md)
   109  * [Documentation on pkg.go.dev](https://pkg.go.dev/github.com/lestrrat-go/jwx/v2/jwk)
   110  
   111  # JWA - RFC7518
   112  
   113  And finally, RFC exists to define commonly used algorithm names in JWT, JWS, JWE, and JWK. 
   114  
   115  This is implemented in github.com/lestrrat-go/jwx/v2/jwa.