Add a package overview for the base noise package

pom.xml

@@ -35,4 +35,48 @@
             <scope>test</scope>
         </dependency>
     </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>build-helper-maven-plugin</artifactId>
+                <version>3.5.0</version>
+                <executions>
+                    <execution>
+                        <id>add-demos</id>
+                        <phase>generate-test-sources</phase>
+                        <goals>
+                            <goal>add-test-source</goal>
+                        </goals>
+                        <configuration>
+                            <sources>
+                                <source>src/example/java</source>
+                            </sources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <plugin>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.2.5</version>
+                <configuration>
+                    <includes>
+                        <include>**/*Example.java</include>
+                        <include>**/*Test.java</include>
+                        <include>**/*Tests.java</include>
+                    </includes>
+                </configuration>
+            </plugin>
+
+            <plugin>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>3.6.3</version>
+                <configuration>
+                    <additionalOptions>--snippet-path ${project.basedir}/src/example/java</additionalOptions>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
 </project>

src/example/java/SimpleHandshakeExample.java

@@ -0,0 +1,54 @@
+import com.eatthepath.noise.NamedProtocolHandshakeBuilder;
+import com.eatthepath.noise.NoSuchPatternException;
+import com.eatthepath.noise.NoiseHandshake;
+import com.eatthepath.noise.NoiseTransport;
+import org.junit.jupiter.api.Test;
+
+import javax.crypto.AEADBadTagException;
+import java.nio.charset.StandardCharsets;
+import java.security.NoSuchAlgorithmException;
+import java.security.spec.InvalidKeySpecException;
+import java.util.Arrays;
+
+@SuppressWarnings("NewClassNamingConvention")
+public class SimpleHandshakeExample {
+
+  @Test
+  void simpleHandshake() throws NoSuchAlgorithmException, NoSuchPatternException, InvalidKeySpecException, AEADBadTagException {
+    // @start region="build-handshake"
+    final String noiseProtocolName = "Noise_NN_25519_ChaChaPoly_SHA256";
+
+    final NoiseHandshake nnInitiatorHandshake =
+        new NamedProtocolHandshakeBuilder(noiseProtocolName, NoiseHandshake.Role.INITIATOR).build();
+
+    final NoiseHandshake nnResponderHandshake =
+        new NamedProtocolHandshakeBuilder(noiseProtocolName, NoiseHandshake.Role.RESPONDER).build();
+    // @end
+
+    // @start region="handshake-messages"
+    // -> e (with no additional payload)
+    final byte[] eMessage = nnInitiatorHandshake.writeMessage(null);
+    nnResponderHandshake.readMessage(eMessage);
+
+    // <- e, ee (with no additional payload)
+    final byte[] eEeMessage = nnResponderHandshake.writeMessage(null);
+    nnInitiatorHandshake.readMessage(eEeMessage);
+
+    // At this point, the handshake is finished, and we can "split" the handshake into a Noise transport
+    assert nnInitiatorHandshake.isDone();
+    assert nnResponderHandshake.isDone();
+    // @end
+
+    // @start region="transport-messages"
+    final NoiseTransport initiatorTransport = nnInitiatorHandshake.toTransport();
+    final NoiseTransport responderTransport = nnResponderHandshake.toTransport();
+
+    final byte[] plaintext = "Hello, world!".getBytes(StandardCharsets.UTF_8);
+    final byte[] ciphertext = initiatorTransport.writeMessage(plaintext);
+
+    final byte[] decryptedPlaintext = responderTransport.readMessage(ciphertext);
+
+    assert Arrays.equals(plaintext, decryptedPlaintext);
+    // @end
+  }
+}

src/main/java/com/eatthepath/noise/NoiseHandshake.java

@@ -54,7 +54,7 @@ public class NoiseHandshake {
 
   private static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
 
-  enum Role {
+  public enum Role {
     INITIATOR,
     RESPONDER
   }

src/main/java/com/eatthepath/noise/package-info.java

@@ -0,0 +1,49 @@
+/**
+ * Provides classes and interfaces for performing handshakes and exchanging messages via a Noise protocol. This package
+ * covers Noise handshakes and steady-state message transport.
+ * <p>
+ * A Noise protocol begins with a handshake (see {@link com.eatthepath.noise.NoiseHandshake}). During a handshake, two
+ * parties exchange messages containing key material and optional, possibly-encrypted payloads as prescribed by a chosen
+ * handshake pattern (see {@link com.eatthepath.noise.HandshakePattern}). Once the handshake is complete, parties
+ * exchange an effectively unbounded sequence of encrypted messages via a {@link com.eatthepath.noise.NoiseTransport}.
+ *
+ * <h2>Example</h2>
+ *
+ * The following example illustrates constructing Noise handshakes and exchanging messages via a steady-state Noise
+ * transport. To begin, we choose a Noise protocol (in this case, {@code Noise_NN_25519_ChaChaPoly_SHA256}, which
+ * specifies an NN handshake pattern, an X25519 key agreement algorithm, a ChaCha20-Poly1305 cipher, and a
+ * SHA-256 hash). Then, we construct a pair of handshake objects. In most practical scenarios, the two "ends" of a
+ * handshake are likely to be controlled by different processes (e.g. a client and server), but for this example, we
+ * control both.
+ *
+ * {@snippet file="SimpleHandshakeExample.java" region="build-handshake"}
+ *
+ * Note that in this case, we construct the handshake objects by providing a full Noise protocol name to a
+ * {@link com.eatthepath.noise.NamedProtocolHandshakeBuilder}. For more complex handshake patterns, callers would be
+ * responsible for providing any keys required for the handshake. Callers may wish to use
+ * {@link com.eatthepath.noise.NoiseHandshakeBuilder} for more complex handshake patterns, since its static initializer
+ * methods provide compile-time assurances that the correct key material is provided for the chosen handshake pattern
+ * and role.
+ * <p>
+ * The NN handshake pattern is defined as:
+ * <p>
+ * <pre>NN:
+ *   -&gt; e
+ *   &lt;- e, ee</pre>
+ * <p>
+ * To carry out the handshake, we pass messages between the initiator and responder handshakes for each message pattern
+ * in the handshake pattern. In the case of an NN handshake pattern, the initiator sends its ephemeral key to the
+ * responder. The responder receives and processes the ephemeral key message, then sends its own ephemeral key to the
+ * initiator and performs a DH key agreement operation between the two ephemeral keys. The initiator receives the
+ * responder's ephemeral key and performs the same key agreement operation.
+ *
+ * {@snippet file="SimpleHandshakeExample.java" region="handshake-messages"}
+ *
+ * With the handshake finished, the handshake objects can be "split" (in the terminology of the Noise protocol) into
+ * steady-state transport channels, and then messages can be passed between the initiator and responder at will.
+ *
+ * {@snippet file="SimpleHandshakeExample.java" region="transport-messages"}
+ *
+ * @see <a href="https://noiseprotocol.org/noise.html">The Noise Protocol Framework</a>
+ */
+package com.eatthepath.noise;