content/posts/2023-10-07-c11-fips203ipd.md: fix typos, add rationale, add explanation to example section

1 files changed, 29 insertions, 15 deletions

diff --git a/content/posts/2023-10-07-c11-fips203ipd.md b/content/posts/2023-10-07-c11-fips203ipd.md
index 1ba1dc8..aa45ca1 100644
--- a/content/posts/2023-10-07-c11-fips203ipd.md
+++ b/content/posts/2023-10-07-c11-fips203ipd.md
@@ -1,23 +1,23 @@
 ---
 slug: C11 Implementation of FIPS 203 IPD
-title: "C11 FIPS 203"
+title: "C11 FIPS 203 IPD"
 date: "2023-10-07T12:19:48-04:00"
 ---
-I created a [C11][] implementation of the KEM512, KEM768, and KEM1024
-parameter sets from the [FIPS 203 initial public draft
+For fun and also to provide feedback during the draft phase, I created a
+[C11][] implementation of the [FIPS 203 initial public draft
 (IPD)][fips203ipd].
 
-[FIPS 203][fips203ipd] is (or will be) [NIST's][nist] standardized
-version of [Kyber][], a post-quantum [key encapsulation mechanism
-(KEM)][kem].
+[FIPS 203][fips203ipd] is a slightly modified version of [Kyber][], and
+will (eventually) become [NIST's][nist] standarized post-quantum [key
+encapsulation mechanism (KEM)][kem].
 
 ### Features
 
 * Full implementation of all three parameter sets from the [FIPS 203
-  initial public draft][fips203ipd]
-* [C11][], no external dependencies
-* Test suite w/ common sanitizers enabled (`make test`)
-* API documentation (`fips203ipd.h`)
+  initial public draft][fips203ipd].
+* [C11][], no external dependencies (other than the standard library).
+* Test suite w/ common sanitizers enabled (`make test`).
+* Doxygen-friendly API documentation (`fips203ipd.h`).
 * short example application (`examples/0-hello-kem/`).
 
 [Git Repository][github]
@@ -31,10 +31,20 @@ correctly][djb-kyber], by [Dan Bernstein (djb)][djb].
 
 ## Example
 
-This example application is also included in the [git
-repository][github] as `examples/0-hello-kem/`.
+Below is the source code and output of a minimal [C11][] example
+application which demonstrates the following:
 
-### Source
+1. Alice generates a random KEM512 encapsulation/decapsulation key pair.
+2. Alice sends the encapsulation key to Bob.
+3. Bob uses the encapsulation key sent by Alice to encapsulate a random shared secret as ciphertext.
+4. Bob sends the ciphertext to Alice.
+5. Alice uses the decapsulation key to decapsulate the shared secret from the ciphertext sent by Bob.
+6. Application verifies that the shared secrets from steps #3 and #5 match.
+
+This example is also included in the [git repository][github] as
+`examples/0-hello-kem/`.
+
+### Example Source Code
 
 ```c
 //
@@ -68,6 +78,7 @@ int main(void) {
     // alice: generate encapsulation/decapsulation key pair
     fips203ipd_kem512_keygen(ek, dk, keygen_seed);
   }
+
   fputs("alice: generated encapsulation key `ek` and decapsulation key `dk`:\n", stdout);
   printf("alice: ek (%d bytes) = ", FIPS203IPD_KEM512_EK_SIZE);
   hex_write(stdout, ek, sizeof(ek));
@@ -138,11 +149,12 @@ int main(void) {
 }
 ```
 
-### Output
+### Example Output
 
 Output of `./hello` with longer lines truncated for brevity:
 
 ```sh
+> ./hello
 alice: keygen random (64 bytes) = d656012a9eb09aa50e77a205188f0156e98276a584dcc11c2dfef0c06003ca38b233fab93e9f8dd5adec32278c8d091190112285b7389510bd610ec7b23376b2
 alice: generated encapsulation key `ek` and decapsulation key `dk`:
 alice: ek (800 bytes) = af3b0497f6 ... (omitted) ... 31f0f62cbd
@@ -160,8 +172,10 @@ alice: a_key (32 bytes) = 32c9eb490db7e8500d9b209d78a9367fd73a967d8d58edff865527
 
 SUCCESS! alice secret `a_key` and bob secret `b_key` match.
 ```
+ 
 
-### 
+**Update (2023-10-10):** Fixed typos, added rationale to intro, and
+added a brief explanation to the example section.
 
 [c11]: https://en.wikipedia.org/wiki/C11_(C_standard_revision)
   "ISO/IEC 9899:2011"