1 files changed, 65 insertions, 1 deletions
diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index 9fb0701..29fbe64 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -247,7 +247,9 @@ In the following code example the two actors perform a public key exchange with
 each other before they start to communicate with each other. This allows them to
 verify that the message that they receive did in fact originate from the person
 that they think it originated from. It also allows them to ensure that the
-message hasn't been altered in transit by appending a signature.
+message hasn't been altered in transit by appending a signature. The choice of
+SHA1 is meant for demonstration purposes only and is not considered a strong
+enough hashing algorithm due to the opportunity for collisions to occur.
 
 ```ruby
 #!/bin/env ruby
@@ -310,6 +312,68 @@ It is also possible to encrypt the JWT body but this isn't necessary and this is
 why storing sensitive information like personally identifiable information in a
 JWT claim is not recommended.
 
+In the Ruby code example above the message that was sent from one person to
+another took the form of:
+
+```plaintext
+  [name, plaintext, signature]
+```
+
+This shape is similar to how a JSON Web Token is structured. A JWT takes the
+form of:
+
+```plaintext
+  header.body.signature
+```
+
+Where each segment is a base64 encoded JSON. The header provides information
+such as the type of signature algorithm that was used and the key id of the
+public key that can be used to verify the signature. This key id typically
+corresponds to one of the keys that are published through the JSON Web Key Set
+(JWKS) URI. For example, the GitLab JWKS can be discovered through the OIDC
+Discovery Endpoint.
+
+```bash
+$ curl https://gitlab.com/.well-known/openid-configuration | jq '.' | grep jwks_uri
+  "jwks_uri": "https://gitlab.com/oauth/discovery/keys",
+```
+
+The following keys imply that GitLab uses RSA for public key cryptography and
+SHA256 as the hash algorithm for verifying digital signatures.
+
+```bash
+$ curl https://gitlab.com/oauth/discovery/keys | jq '.'
+{
+  "keys": [
+    {
+      "kty": "RSA",
+      "kid": "kewiQq9jiC84CvSsJYOB-N6A8WFLSV20Mb-y7IlWDSQ",
+      "e": "AQAB",
+      "n": "5RyvCSgBoOGNE03CMcJ9Bzo1JDvsU8XgddvRuJtdJAIq5zJ8fiUEGCnMfAZI4of36YXBuBalIycqkgxrRkSOENRUCWN45bf8xsQCcQ8zZxozu0St4w5S-aC7N7UTTarPZTp4BZH8ttUm-VnK4aEdMx9L3Izo0hxaJ135undTuA6gQpK-0nVsm6tRVq4akDe3OhC-7b2h6z7GWJX1SD4sAD3iaq4LZa8y1mvBBz6AIM9co8R-vU1_CduxKQc3KxCnqKALbEKXm0mTGsXha9aNv3pLNRNs_J-cCjBpb1EXAe_7qOURTiIHdv8_sdjcFTJ0OTeLWywuSf7mD0Wpx2LKcD6ImENbyq5IBuR1e2ghnh5Y9H33cuQ0FRni8ikq5W3xP3HSMfwlayhIAJN_WnmbhENRU-m2_hDPiD9JYF2CrQneLkE3kcazSdtarPbg9ZDiydHbKWCV-X7HxxIKEr9N7P1V5HKatF4ZUrG60e3eBnRyccPwmT66i9NYyrcy1_ZNN8D1DY8xh9kflUDy4dSYu4R7AEWxNJWQQov525v0MjD5FNAS03rpk4SuW3Mt7IP73m-_BpmIhW3LZsnmfd8xHRjf0M9veyJD0--ETGmh8t3_CXh3I3R9IbcSEntUl_2lCvc_6B-m8W-t2nZr4wvOq9-iaTQXAn1Au6EaOYWvDRE",
+      "use": "sig",
+      "alg": "RS256"
+    },
+    {
+      "kty": "RSA",
+      "kid": "4i3sFE7sxqNPOT7FdvcGA1ZVGGI_r-tsDXnEuYT4ZqE",
+      "e": "AQAB",
+      "n": "4cxDjTcJRJFID6UCgepPV45T1XDz_cLXSPgMur00WXB4jJrR9bfnZDx6dWqwps2dCw-lD3Fccj2oItwdRQ99In61l48MgiJaITf5JK2c63halNYiNo22_cyBG__nCkDZTZwEfGdfPRXSOWMg1E0pgGc1PoqwOdHZrQVqTcP3vWJt8bDQSOuoZBHSwVzDSjHPY6LmJMEO42H27t3ZkcYtS5crU8j2Yf-UH5U6rrSEyMdrCpc9IXe9WCmWjz5yOQa0r3U7M5OPEKD1-8wuP6_dPw0DyNO_Ei7UerVtsx5XSTd-Z5ujeB3PFVeAdtGxJ23oRNCq2MCOZBa58EGeRDLR7Q",
+      "use": "sig",
+      "alg": "RS256"
+    },
+    {
+      "kty": "RSA",
+      "kid": "UEtnUohTq58JiJzxHhBLSU0yTpsmW-9EY1Wykha6VIg",
+      "e": "AQAB",
+      "n": "9UAG0U59NZ3MBMQkjCVuA8c0ZHEL8SEljnXYYxAuuvy4P79XxTYNodmBAioe1CBsdOmFjjdtXzPIxYv_zEHwkI5WoL1U0r83Q8RSbcl_YSCjfq32TW1hj1KQe0bjzx1TohtnOZSIq-0_8QLbdJrwN7LnBHkalAdMYFk9qUEFlTP-jwUIxztmjpok_-d6W1621iDQwUzYqKiTYc7ZQdC3Bf5jv-8yTm7pMQrR0W6XvPNnRwJmGZdkDH1ZC6okTzLsaMBgMV5awtXJeSZqrR3Qy3ATX6hiitmld9K3FyKFyyIOpaygjltKVzNy5giwnDfTHaGs24Y51Jy1SZ51vqfEFQ",
+      "use": "sig",
+      "alg": "RS256"
+    }
+  ]
+}
+```
+
+
 The problem of sharing and distributing public keys is solved using Public Key
 Infrastructure (PKI). PKI provides a mechanism for distributing X.509
 certificates that include metadata and the public keys for different entities.