More module documentation
+#![doc(html_no_source)]
//! # Ossuary
//!
//! Ossuary is a library for establishing an encrypted and authenticated
//! Authentication and verification of remote hosts is optional, and requires
//! an out-of-band exchange of host public keys, or a Trust-On-First-Use policy.
//!
+//! ## Protocol Overview:
+//!
+//! The Ossuary protocol consists of two distinct stages: a handshaking stage
+//! and an established channel stage.
+//!
+//! ## Handshake
+//!
+//! All connections begin by handshaking. A few packets are exchanged back and
+//! forth to establish an encrypted channel with a negotiated session key, and
+//! to optionally authenticate the identity of the hosts. Handshake packets are
+//! generated by the Ossuary library itself; the application asks Ossuary for
+//! the next packet to send, and then is responsible for putting it on the wire.
+//!
+//! ## Established Channel
+//!
+//! Once the handshake completes successfully, Ossuary drops into the
+//! established channel stage. In this stage, Ossuary is completely passive,
+//! where the application gives it data to encrypt for transmission or decrypt
+//! for reception. Ossuary does not generate any unrequested packets in this
+//! stage.
+//!
+//! In the case of errors, Ossuary always terminates the encrypted channel and
+//! drops back into the handshake stage. If it believes the channel might still
+//! be viable, the handshake stage will generate a packet to attempt to reset
+//! the remote host back into the handshake as well, and they will both attempt
+//! to recover the channel.
+//!
+//! ## API Overview:
+//!
+//! Ossuary fits into an application as a 'filter' on network traffic, and does
+//! not implement any network communication itself. Similarly, it does not have
+//! any persistent storage, leaving the storage of keys to the caller.
+//!
+//! The application must always check to see if it should drop back into the
+//! handshake, in case the connection failed. The main loop would typically be
+//! split between two cases: handshaking, or established channel.
+//!
+//! In pseudocode, typical use of the API looks like this:
+//!
+//! ```ignore
+//! fn main() {
+//! let socket = TCPSocket::get_socket_from_somewhere();
+//! let secret_key = FileSystem::get_securely_stored_file("secret.key");
+//! let ossuary = OssuaryConnection::new(ConnectionType::Whatever, Some(secret_key));
+//! let net_read_buf = [0u8; 1024]; // encrypted!
+//! let net_write_buf = [0u8; 1024]; // encrypted!
+//! let internal_buf = [0u8; 1024]; // plaintext!
+//!
+//! loop {
+//! // Always read encrypted data off the wire and append to our read buf
+//! socket.read_and_append(&mut net_read_buf);
+//!
+//! // Two paths depending on if we are handshaking
+//! match ossuary.handshake_done() {
+//! false => {
+//! // Parse received handshake packets.
+//! ossuary.recv_handshake(&net_read_buf);
+//!
+//! // Possibly write handshake packets.
+//! ossuary.send_handshake(&mut net_write_buf);
+//! },
+//!
+//! true => {
+//! // Decrypt data into internal buffer
+//! ossuary.recv_data(&net_read_buf, &mut internal_buf);
+//!
+//! // Do some application-specific thing with the data
+//! react_and_respond(&mut internal_buf);
+//!
+//! // Encrypt application's response
+//! ossuary.send_data(&internal_buf, &mut net_write_buf);
+//! },
+//! }
+//!
+//! // Always write all encrypted data onto the wire and clear the write buf
+//! socket.write_and_clear(&mut net_write_buf);
+//! }
+//! }
+//! ```
+//!
+//! A real implementation would also need to carefully handle removing consumed
+//! bytes from the read buffer, and handling errors at every step.
+//!
+//! Since Ossuary leaves the actual wire transmission to the caller, it can be
+//! used over any physical channel, or with any transmission protocol, so long
+//! as data is delivered (to Ossuary) reliably and in-order. It is just as
+//! viable for UNIX Domain Sockets, D-Bus, named pipes, and other IPC mechanisms
+//! as for TCP, if you somehow have a threat model that distrusts those.
+//!
//! ## Ciphers:
//!
//! * Ephemeral session keys: Curve25519 ECDH.
//! you may not use this file except in compliance with the License.
//! You may obtain a copy of the License at
//!
-//! http://www.apache.org/licenses/LICENSE-2.0
+//! http://www.apache.org/licenses/LICENSE-2.0
//!
//! Unless required by applicable law or agreed to in writing, software
//! distributed under the License is distributed on an "AS IS" BASIS,