[doc] user specified associated data API about aeads

[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