Updated comments to reflect latest changes.

shadowaead/cipher.go

@@ -63,6 +63,8 @@ func aesGCM(key []byte) (cipher.AEAD, error) {
 	return cipher.NewGCM(blk)
 }
 
+// AESGCM creates a new Cipher with a pre-shared key. len(psk) must be
+// one of 16, 24, or 32 to select AES-128/196/256-GCM.
 func AESGCM(psk []byte) (Cipher, error) {
 	switch l := len(psk); l {
 	case 16, 24, 32: // AES 128/196/256
@@ -72,6 +74,8 @@ func AESGCM(psk []byte) (Cipher, error) {
 	return &metaCipher{psk: psk, makeAEAD: aesGCM}, nil
 }
 
+// Chacha20IETFPoly1305 creates a new Cipher with a pre-shared key. len(psk)
+// must be 32.
 func Chacha20IETFPoly1305(psk []byte) (Cipher, error) {
 	if len(psk) != chacha20poly1305.KeySize {
 		return nil, KeySizeError(chacha20poly1305.KeySize)

shadowaead/doc.go

@@ -6,8 +6,8 @@ Stream-oriented connections (e.g. TCP) assume reliable and orderly delivery of b
 Packet-oriented connections (e.g. UDP) assume unreliable and out-of-order delivery of packets,
 where each packet is either delivered intact or lost.
 
-An encrypted stream starts with a nonce, followed by any number of encrypted records.
-Each encrypted record has the following structure:
+An encrypted stream starts with a random salt to derive a session key, followed by any number of
+encrypted records. Each encrypted record has the following structure:
 
     [encrypted payload length]
     [payload length tag]
@@ -16,20 +16,20 @@ Each encrypted record has the following structure:
 
 Payload length is 2-byte unsigned big-endian integer capped at 0x3FFF (16383).
 The higher 2 bits are reserved and must be set to zero. The first AEAD encrypt/decrypt
-operation uses the nonce at the beginning of the stream. After each encrypt/decrypt operation,
+operation uses a counting nonce starting from 0. After each encrypt/decrypt operation,
 the nonce is incremented by one as if it were an unsigned little-endian integer.
 
 
 Each encrypted packet transmitted on a packet-oriented connection has the following structure:
 
-    [nonce]
+    [random salt]
     [encrypted payload]
     [payload tag]
 
-Packets are encrypted/decrypted independently.
+The salt is used to derive a subkey to initiate an AEAD. Packets are encrypted/decrypted independently
+using zero nonce.
 
 In both stream-oriented and packet-oriented connections, length of nonce and tag varies
-depending on which AEAD is used. Nonces are assumed to be randomly generated and
-of sufficient length (at least 12 bytes).
+depending on which AEAD is used. Salt should be at least 16-byte long.
 */
 package shadowaead

shadowaead/packet.go

@@ -10,9 +10,9 @@ import (
 // ErrShortPacket means that the packet is too short for a valid encrypted packet.
 var ErrShortPacket = errors.New("short packet")
 
-// Pack encrypts plaintext using aead with a randomly generated nonce and
+// Pack encrypts plaintext using Cipher with a randomly generated salt and
 // returns a slice of dst containing the encrypted packet and any error occurred.
-// Ensure len(dst) >= aead.NonceSize() + len(plaintext) + aead.Overhead().
+// Ensure len(dst) >= ciph.SaltSize() + len(plaintext) + aead.Overhead().
 func Pack(dst, plaintext []byte, ciph Cipher) ([]byte, error) {
 	saltSize := ciph.SaltSize()
 	salt := dst[:saltSize]
@@ -33,8 +33,8 @@ func Pack(dst, plaintext []byte, ciph Cipher) ([]byte, error) {
 	return dst[:saltSize+len(b)], nil
 }
 
-// Unpack decrypts pkt using aead and returns a slice of dst containing the decrypted payload and any error occurred.
-// Ensure len(dst) >= len(pkt) - aead.NonceSize() - aead.Overhead().
+// Unpack decrypts pkt using Cipher and returns a slice of dst containing the decrypted payload and any error occurred.
+// Ensure len(dst) >= len(pkt) - aead.SaltSize() - aead.Overhead().
 func Unpack(dst, pkt []byte, ciph Cipher) ([]byte, error) {
 	saltSize := ciph.SaltSize()
 	if len(pkt) < saltSize {