kem: add basic usage with example (#2354)

Author: tarcieri

kem/src/lib.rs

@@ -8,6 +8,49 @@
 #![forbid(unsafe_code)]
 #![warn(missing_docs, unused_qualifications, missing_debug_implementations)]
 
+//! # Usage
+//!
+//! There are two roles in a KEM:
+//!
+//! - Encapsulator: the holder of the public key (a.k.a. encapsulation key), which provides an
+//!   operation that simultaneously generates both the plaintext and ciphertext of a random
+//!   "shared key" whose ciphertext (a.k.a. encapsulation) can be sent to the party with the
+//!   decapsulator key.
+//! - Decapsulator: holder secret/private key (a.k.a. decapsulation key), which can be used to
+//!   decrypt the encrypted (a.k.a. encapsulated) "shared key" which was randomly generated by
+//!   the encapsulator.
+//!
+//! The following example illustrates the workflow of using this crate's traits with a hypothetical
+//! KEM named `K` :
+//!
+#![cfg_attr(feature = "getrandom", doc = "```")]
+#![cfg_attr(not(feature = "getrandom"), doc = "```ignore")]
+//! // NOTE: requires the `getrandom` feature is enabled
+//!
+//! use kem::{Decapsulate, Encapsulate, Kem};
+//!
+//! # pub fn kem_workflow_example<K: Kem<DecapsulationKey: Decapsulate>>() {
+//! // Generate a decapsulation/encapsulation keypair. The first one is the secret one.
+//! let (dk, ek) = K::generate_keypair();
+//!
+//! // Encapsulator:
+//! //
+//! // Randomly generates and encapsulates/encrypts a shared key which can be decrypted by the
+//! // holder of the decapsulation key, obtaining the ciphertext and plaintext of the shared key.
+//! let (ct, k_send) = ek.encapsulate();
+//!
+//! // Decapsulator:
+//! //
+//! // Decapsulates the encrypted/encapsulated shared key, obtaining its plaintext.
+//! let k_recv = dk.decapsulate(&ct);
+//!
+//! // We've now established a shared key.
+//! assert_eq!(k_send, k_recv);
+//! # }
+//! ```
+//!
+//! [RFC 9180]: https://www.rfc-editor.org/info/rfc9180
+
 pub use common::{
     self, Generate, InvalidKey, Key, KeyExport, KeyInit, KeySizeUser, TryKeyInit, typenum::consts,
 };