Add better documentation on the auth_data

[intentionally-left-nil]

I'm trying to understand what auth_data for GCM mode is. Between https://crypto.stackexchange.com/questions/35727/does-aad-make-gcm-encryption-more-secure which says that it's optional, and https://en.wikipedia.org/wiki/Galois/Counter_Mode has this blurb: As with any message authentication code, if the adversary chooses a t-bit tag at random, it is expected to be correct for given data with probability 2−t. With GCM, however, an adversary can choose tags that increase this probability, proportional to the total length of the ciphertext and additional authenticated data (AAD). Consequently, GCM is not well-suited for use with very short tag lengths or very long messages.

Basically, can I omit this data if I control my metadata elsewhere (e.g. protocol negotiation takes place elsewhere)?

Either way, can you update the documentation to be a little more descriptive here? The samples just have "other auth data" which doesn't help me understand how it could be used practically.

[ntrepid8]

Yeah that makes sense. Usually the "other auth data" is something that isn't secret but should uniquely identify the message. If I'm remembering my bock cipher modes correctly the authentication data is just used to produce a signature that can be used to authenticate the message prior to any decryption operation.

It's designed to reduce the possibility that someone using a block cipher would forget to authenticate the message or would decrypt the cipher text prior to authenticating the signature. Omitting the signature authentication step or doing it out of order would open you up to a timing based attack.

In GCM mode the signature authentication step isn't optional or left to the user to implement the way it is in other block cipher modes like CBC. Does that help?