Some documentation improvements (#1)

oxisto · web-flow · commit 65369ff10e04 · 2023-03-25T15:23:19.000+01:00
* Some documentation improvements

* Switching back to official image, since it now suports also arm-builds
* Adding a bit of a structure and tabs
* Added first small code pieces

* more doc

* First set of parser options

* More parsing options
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
 .build/
 .idea/
 .vscode/
+.cache/
+
diff --git a/Makefile b/Makefile
@@ -1,8 +1,5 @@
 DOCKER ?= docker
-# The official docker image is linux/amd64 only. So we use the recommended 
-# third-party image as suggested in the docs:
-# https://squidfunk.github.io/mkdocs-material/getting-started/?h=docker#with-docker
-DOCKER_IMAGE ?= ghcr.io/afritzler/mkdocs-material
+DOCKER_IMAGE ?= squidfunk/mkdocs-material
 DOCKER_BUILD_EXTRA_ARGS ?=
 
 preview:
diff --git a/README.md b/README.md
@@ -12,12 +12,5 @@ We use a pre-built
 [docker image](https://squidfunk.github.io/mkdocs-material/getting-started/#with-docker) which comes
 with all dependencies pre-installed.
 
-Note, we're using the recommended third-party image because the official one only supports
-`linux/amd64`.
-
-```
-docker pull ghcr.io/afritzler/mkdocs-material
-```
-
 Ensure you have Docker installed, run `make preview`, and open http://127.0.0.1:8000 to see a
 preview of the site locally.
diff --git a/docs/index.md b/docs/index.md
@@ -2,10 +2,43 @@
 description: Getting started with golang-jwt/jwt
 ---
 
-# Getting started
+# Getting Started
 
-⚠️ This webpage is a work in progress.
+Welcome to `jwt-go`, a [go](http://www.golang.org) (or 'golang' for search engine friendliness) implementation of [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519). 
 
-## Installation
 
-## Signing Algorithms
+### Supported Go versions
+
+Our support of Go versions is aligned with Go's [version release
+policy](https://golang.org/doc/devel/release#policy). So we will support a major
+version of Go until there are two newer major releases. We no longer support
+building jwt-go with unsupported Go versions, as these contain security
+vulnerabilities which will not be fixed.
+
+## What the heck is a JWT?
+
+JWT.io has [a great introduction](https://jwt.io/introduction) to JSON Web Tokens.
+
+In short, it's a signed JSON object that does something useful (for example, authentication).  It's commonly used for `Bearer` tokens in OAuth 2.0  A token is made of three parts, separated by `.`'s.  The first two parts are JSON objects, that have been [base64url](https://datatracker.ietf.org/doc/html/rfc4648) encoded.  The last part is the signature, encoded the same way.
+
+The first part is called the header.  It contains the necessary information for verifying the last part, the signature.  For example, which encryption method was used for signing and what key was used.
+
+The part in the middle is the interesting bit.  It's called the Claims and contains the actual stuff you care about.  Refer to [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) for information about reserved keys and the proper way to add your own.
+
+## What's in the box?
+
+This library supports the parsing and verification as well as the generation and signing of JWTs.  Current supported signing algorithms are HMAC SHA, RSA, RSA-PSS, ECDSA and EdDSA, though hooks are present for adding your own.
+
+## Installation Guidelines
+
+To install the jwt package, you first need to have [Go](https://go.dev/doc/install) installed, then you can use the command below to add `jwt-go` as a dependency in your Go program.
+
+```sh
+go get -u github.com/golang-jwt/jwt/v5
+```
+
+Then import it in your code:
+
+```go
+import "github.com/golang-jwt/jwt/v5"
+```
diff --git a/docs/usage/create.md b/docs/usage/create.md
@@ -0,0 +1,69 @@
+# Creating a New JWT
+
+One of the primary goals of this library is to create a new JWT (or in short
+*token*).
+
+## With Default Options
+
+ The easiest way to create a token is to use the
+[`jwt.New`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#New) function. It
+then needs one of the available [signing methods](./signing_methods.md), to
+finally sign and convert the token into a string format (using the
+[`SignedString`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token.SignedString)
+method). In the first example, we are using a **symmetric** signing method, i.e.,
+HS256. For a symmetric method, both the signing and the verifying key are the
+same and thus, both must be equally protected (and should definitely NOT be
+stored in your code).
+
+```go
+var (
+  key []byte
+  t   *jwt.Token
+  s   string
+)
+
+key = /* Load key from somewhere, for example an environment variable */
+t = jwt.New(jwt.SigningMethodHS256) // (1)!
+s = t.SignedString(key) // (2)!
+```
+
+1. This initializes a new
+   [`jwt.Token`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token) struct
+   based on the supplied signing method. In this case a **symmetric** method is
+   chosen.
+2. This step computes a cryptographic signature based on the supplied key. 
+
+Signing using an *asymmetric* signing method (for example ECDSA) works quite
+similar. For an **asymmetric** method, the private key (which must be kept
+secret) is used to *sign* and the corresponding public key (which can be freely
+transmitted) is used to *verify* the token.
+
+```go
+var (
+  key *ecdsa.PrivateKey
+  t   *jwt.Token
+  s   string
+)
+
+key = /* Load key from somewhere, for example a file */
+t = jwt.New(jwt.SigningMethodES256) // (1)!
+s = t.SignedString(key) // (2)!
+```
+
+1. This initializes a new [`jwt.Token`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token) struct based on the supplied signing method. In this case a **asymmetric** method is chosen.
+2. This step computes a cryptographic signature based on the supplied private
+   key.
+
+Note, that the chosen signing method and the type of key must match. Please refer to [Signing Methods](./signing_methods.md) for a complete overview.
+
+
+## With Additional Claims
+
+## With Options
+
+While we already prepared a
+[`jwt.TokenOption`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#TokenOption)
+type, which can be supplied as a varargs to
+[`jwt.New`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#New) and
+[`jwt.NewWithClaims`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#NewWithClaims),
+these are strictly for future compatibility and are currently not used.
diff --git a/docs/usage/parse.md b/docs/usage/parse.md
@@ -0,0 +1,27 @@
+# Parsing and Validating a JWT
+
+## Keyfunc
+
+
+
+## With Options
+
+| <div style="width:5.6rem">Option Name</div> | <div style="width:4.5rem">Arguments</div>                     | Description                                                                                                                                                                                                                                                                                                                                                                           |
+| :------------------------------------------ | :------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WithValidMethods`                          | methods as `[]string`                                         | Supplies a list of [signing methods](./signing_methods.md) that the parser will check against the algorithm on the token. Only the supplied methods will be considered valid. It is heavily encouraged to use this option in order to prevent "none" algorithm attacks.[^1]                                                                                                           |  |
+| `WithJSONNumber`                            | -                                                             | Configures the underlying JSON parser to use the [`UseNumber`](https://pkg.go.dev/encoding/json#Decoder.UseNumber) function, which decodes numeric JSON values into the [`json.Number`](https://pkg.go.dev/encoding/json#Number) type instead of `float64`. This type can then be used to convert the value into either a floating type or integer type.                              |
+| `WithIssuer`                                | issuer as `string`                                            | Configures the validator to require the specified issuer in the `"iss"`[^iss] claim. Validation will fail if a different issuer is specified in the token or the `"iss"` claim is missing.                                                                                                                                                                                            |
+| `WithSubject`                               | subject as `string`                                           | Configures the validator to require the specified subject in the `"sub"`[^sub] claim. Validation will fail if a different subject is specified in the token or the `"sub"` claim is missing.                                                                                                                                                                                          |
+| `WithAudience`                              | audience  as `string`                                         | Configures the validator to require the specified audience in the `"aud"`[^aud] claim. Validation will fail if the audience is not listed in the token or the `"aud"` claim is missing. The contents of the audience string is application specific, but often contains the URI of the service that consumes the token.                                                               |
+| `WithLeeway`                                | leeway as [`time.Duration`](https://pkg.go.dev/time#Duration) | According to the RFC, a certain time window (leeway) is allowed when verifying time based claims, such as expiration time. This is due to the fact that a there is not perfect clock synchronization on the a distributed system such as the internet. While we do not enforce any restriction on the amount of leeway, it should generally not exceed more than a few minutes.[^exp] |
+| `WithIssuedAt`                              | -                                                             | Enables a sanity check of the `"iat"`[^iat] claim. More specifically, when turning this option on, the validator will check if the issued-at time is not in the future.                                                                                                                                                                                                               |
+| Danger Zone                                 |
+
+
+[^1]: [https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries](https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries)
+[^iss]: [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1)
+[^sub]: [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2)
+[^aud]: [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)
+[^exp]: [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)
+[^iat]: [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6)
+
diff --git a/docs/usage/signing_methods.md b/docs/usage/signing_methods.md
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -5,17 +5,30 @@ repo_name: golang-jwt/jwt
 repo_url: https://github.com/golang-jwt/jwt
 edit_uri: ""
 
+plugins:
+  - social
+
 theme:
   name: material
   palette:
-    primary: white
-    accent: indigo
+    primary: light blue
+    accent: purple
   logo: assets/jwt.png
   favicon: assets/jwt.png
   features:
     - navigation.instant
+    - navigation.tabs
     - toc.integrate
-    - navigation.sections
+    - content.code.copy
+    - content.code.annotate
 
-nav:
-  - index.md
+markdown_extensions:
+  - pymdownx.highlight:
+      use_pygments: true
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - footnotes

-Original file line number
+Diff line change
@@ @@ -1,3 +1,5 @@ @@
 .build/
 .idea/
 .vscode/
 +.cache/
++