Improve documentation

Document that the `aeadSupported` parameter passed to
`SerializeEncryptedKeyAEAD[withHiddenOption]`,
`SerializeSymmetricKeyEncryptedAEADReuseKey`, and
`SerializeSymmetricallyEncrypted` must match.

Author: twiss

openpgp/packet/encrypted_key.go

@@ -321,7 +321,8 @@ func (e *EncryptedKey) Serialize(w io.Writer) error {
 
 // SerializeEncryptedKeyAEAD serializes an encrypted key packet to w that contains
 // key, encrypted to pub.
-// If aeadSupported is set, PKESK v6 is used else v4.
+// If aeadSupported is set, PKESK v6 is used, otherwise v3.
+// Note: aeadSupported MUST match the value passed to SerializeSymmetricallyEncrypted.
 // If config is nil, sensible defaults will be used.
 func SerializeEncryptedKeyAEAD(w io.Writer, pub *PublicKey, cipherFunc CipherFunction, aeadSupported bool, key []byte, config *Config) error {
 	return SerializeEncryptedKeyAEADwithHiddenOption(w, pub, cipherFunc, aeadSupported, key, false, config)
@@ -330,7 +331,8 @@ func SerializeEncryptedKeyAEAD(w io.Writer, pub *PublicKey, cipherFunc CipherFun
 // SerializeEncryptedKeyAEADwithHiddenOption serializes an encrypted key packet to w that contains
 // key, encrypted to pub.
 // Offers the hidden flag option to indicated if the PKESK packet should include a wildcard KeyID.
-// If aeadSupported is set, PKESK v6 is used else v4.
+// If aeadSupported is set, PKESK v6 is used, otherwise v3.
+// Note: aeadSupported MUST match the value passed to SerializeSymmetricallyEncrypted.
 // If config is nil, sensible defaults will be used.
 func SerializeEncryptedKeyAEADwithHiddenOption(w io.Writer, pub *PublicKey, cipherFunc CipherFunction, aeadSupported bool, key []byte, hidden bool, config *Config) error {
 	var buf [36]byte // max possible header size is v6

openpgp/packet/symmetric_key_encrypted.go

@@ -204,6 +204,8 @@ func SerializeSymmetricKeyEncryptedReuseKey(w io.Writer, sessionKey []byte, pass
 // The packet contains the given session key, encrypted by a key derived from
 // the given passphrase. The returned session key must be passed to
 // SerializeSymmetricallyEncrypted.
+// If aeadSupported is set, SKESK v6 is used, otherwise v4.
+// Note: aeadSupported MUST match the value passed to SerializeSymmetricallyEncrypted.
 // If config is nil, sensible defaults will be used.
 func SerializeSymmetricKeyEncryptedAEADReuseKey(w io.Writer, sessionKey []byte, passphrase []byte, aeadSupported bool, config *Config) (err error) {
 	var version int

openpgp/packet/symmetrically_encrypted.go

@@ -74,6 +74,10 @@ func (se *SymmetricallyEncrypted) Decrypt(c CipherFunction, key []byte) (io.Read
 // SerializeSymmetricallyEncrypted serializes a symmetrically encrypted packet
 // to w and returns a WriteCloser to which the to-be-encrypted packets can be
 // written.
+// If aeadSupported is set to true, SEIPDv2 is used with the indicated CipherSuite.
+// Otherwise, SEIPDv1 is used with the indicated CipherFunction.
+// Note: aeadSupported MUST match the value passed to SerializeEncryptedKeyAEAD
+// and/or SerializeSymmetricKeyEncryptedAEADReuseKey.
 // If config is nil, sensible defaults will be used.
 func SerializeSymmetricallyEncrypted(w io.Writer, c CipherFunction, aeadSupported bool, cipherSuite CipherSuite, key []byte, config *Config) (Contents io.WriteCloser, err error) {
 	writeCloser := noOpCloser{w}