docs: write up notes on PKI

1 files changed, 66 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index c0b6d02..3635b52 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -158,3 +158,69 @@ is a metaphor for a high security context that the operators of the airplane
 understand. The credit card company and each intermediate authority that was
 used to ensure entry do not determine the access controls for gaining entry into
 the plane.
+
+### Authentication
+
+Authentication is the act of verifying that an entity is who they say they are.
+
+How do we do this on the internet? To accomplish this we depend on public key
+cryptography which is a form of asymmetic crypto. In this style of crypto each
+party has a public and private key. Entities distribute their public keys while
+keeping their private keys private. The interesting property of the
+public/private key relationship is that messages that are encrypted by either
+the public or private key can only be decrypted by the other corresponding key.
+
+#### Confidentiality
+
+So if I give you my public key then you can encrypt a message with my public key
+and send that message to me. Only I can decrypt that message using my private
+key. This ensures confidentiality so that the ciphertext produced can be snooped
+by anyone but only the recipient can convert the ciphertext back into plaintext.
+
+### Authenticity
+
+To ensure that a message originated from the entity that claims to have sent the
+message an additional signature can be appended to the message. The signature
+can contain any arbitrary text but is usually a hash (e.g. SHA256) of the
+original plaintext message and encrypted using the private key of the sender.
+I'll explain below why a hash is used below. If the recipient has the public key of the sender
+then they can decrypt the signature using the public key of the sender. If
+signature can be decrypted without an error then we can trust that the message
+did in fact originate from the sender. This authenticates the message.
+
+### Integrity
+
+When a recipient receives a message from a sender the recipient also needs to
+verify that the message wasn't altered. If the signature of the message includes
+an encrypted hash then the recipient can compute a hash of the plaintext message
+and compare it with the hash in the encrypted signature. This ensures that the
+message hasn't been tampered with.
+
+In order for us to be able to trust JSON Web Tokens we need public/private key
+pairs that we can use to validate the authenticity and integrity of the token.
+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.
+
+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.
+X.509 certificates can include a digital signature from other authorities
+provides a chain of trust. Each X.509 certificate stores in the CA trust store
+on your computer is a self signed certificate that is considered trusted.
+Intermediate certificates can be traced back to a root certificate and provides
+a web of trust. i.e. I trust this JWT because it was signed by a public key that
+I found in this intermediate certificate that was signed by a public key found
+in this root certificate that is in my operating systems root certificate
+authority trust store. Typically, organizations will operate an internal
+certificate authority that can sign intermediate certificates that can be
+installed in the trust store for internal services. This makes it easier to
+issue internal certificates without need direct access to private keys that can
+be abused by bad actors. I apologize for the weak summary of this but a cursory
+knowledge of how this works is important for understanding authentication.
+
+When a service federates user authentication to an Identity Provider (.e.g. SAML
+IdP, OIDC Provider) the transaction between the service (i.e. SAML Service
+Provider, OIDC Relaying Party) depends on an exchange of public key information
+ahead of time (AoT). Without this pre-prequisite, none of the downstream
+assumptions about user authentication is valid.