docs: add an example of public key crypto

1 files changed, 36 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index 907d53e..7db50cd 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -180,6 +180,42 @@ 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.
 
+The following example shows an exchange between two parties. Each party
+encrypts a plaintext message with the other party's public key. When that party
+receives the ciphertext message they are able to decrypt the message using their
+own private key.
+
+```ruby
+#!/bin/env ruby
+require 'openssl'
+
+class Player
+  attr_reader :name, :public_key
+
+  def initialize(name, private_key = OpenSSL::PKey::RSA.new(2048))
+    @name = name
+    @private_key = private_key
+    @public_key = private_key.public_key
+  end
+
+  def send_to(player, plaintext)
+    ciphertext = player.public_key.public_encrypt(plaintext)
+    player.receive_from(self, ciphertext)
+  end
+
+  def receive_from(player, ciphertext)
+    plaintext = @private_key.private_decrypt(ciphertext)
+    puts "#{player.name}: #{plaintext}\n"
+  end
+end
+
+clifford = Player.new("clifford")
+reginald = Player.new("reginald")
+
+clifford.send_to(reginald, "What time is it?")
+reginald.send_to(clifford, "Time to go live!")
+```
+
 #### Authenticity
 
 To ensure that a message originated from the entity that claims to have sent the