[doc] user specified associated data API

[alxiong]

Currently documentation on trait aead::Aead and specific instantiation of AEAD suites only cover how to directly encrypt a message with (by default) an empty associated data field,

The Payload type can be used to provide Additional Associated Data (AAD) along with the message: this is an optional bytestring which is not encrypted, but is authenticated along with the message. Failure to pass the same AAD that was used during encryption will cause decryption to fail, which is useful if you would like to "bind" the ciphertext to some other identifier, like a digital signature key or other identifier.

If I construct my own Payload with msg and aad specified, then how to pass to the encrypt() function is not so clear to me, cuz Payload itself doesn't implement Into<Payload>.

I could be misunderstanding things, but maybe some examples in the documentation would be helpful.
Thanks!

[tarcieri]

All types have a blanket impl of impl<T> From<T> for <T>:

https://docs.rs/aead/0.3.2/aead/struct.Payload.html#impl-From%3CT%3E

...and all types that impl From have a blanket impl for Into:

https://doc.rust-lang.org/std/convert/trait.Into.html#impl-Into%3CU%3E

...so Payload receives a blanket impl of Into<Payload> as well.

I agree the documentation for aead::Aead could be better there.

[alxiong]

Ah I see, thanks for the clarification!

Understood now, can close the issue. 👍🏻

[tarcieri]

I'll leave it open to track adding better documentation

[alxiong]

hmm... 🤔 the following gives me Err, not sure why

// message: &[u8], assoc_data: &u8, nonce and recipient_box is properly constructed.
let ct = recipient_box.encrypt(&nonce,
                               Payload { msg: &message,
                                         aad: &assoc_data });

Just to double check with you @tarcieri , ☝️ this is the correct way to use Payload right?

---

update: if I set assoc_data to an empty slice, then it will pass. but if aad is non empty, it will fail. -- feels like a bug 🪲 ?

to reproduce it, see playground here: https://repl.it/repls/OutstandingWildNature#src/lib.rs

[tarcieri]

crypto_box and the xsalsa20poly1305 construction it's based on doesn't support AAD as an algorithm. Unfortunately it's unclear from the current API it's unsupported and you're getting an unhelpful error.

We have this tracking issue open for traits which better reflect constructions like xsalsa20poly1305 which don't support AAD: RustCrypto/traits#261

[alxiong]

the xsalsa20poly1305 construction it's based on doesn't support AAD as an algorithm

so will the team add support for AAD in the near future (if so, mind me asking roughly when)? or this exclusion has some rationale behind?

We have this tracking issue open for traits which better reflect constructions like xsalsa20poly1305 which don't support AAD: RustCrypto/traits#261

so basically, xsalsa20poly1305 is "designed to not have AAD support"?

[tarcieri]

The design of the xsalsa20poly1305 algorithm itself has no support for AAD. It's the only such algorithm in this repo which doesn't.

The similar chacha20poly1305 construction supports it. We could potentially add support for it to crypto_box

[alxiong]

I see.

The similar chacha20poly1305 construction supports it. We could potentially add support for it to crypto_box

that would be great

[tarcieri]

I think this was ultimately addressed in #225