Specification unclear

[yaaminu]

Hello, I'd like to write few implementations in node and java but find the documentation fairly inadequate.
Is there a well written specification document available?

[paragonie-scott]

What is the level of specificity you need right now?

Currently, the plan is to hammer out any warts and ambiguities in the reference implementation, then write a formal RFC draft. The main reason I'm not delving into this right now is that such a document will be an incredible timesink that involves redefining e.g. XChaCha20-Poly1305 since there isn't an internet standard that defines HChaCha20 or the extended-nonce AEAD construction used in libsodium.

[yaaminu]

I think I understand now.... I'd have to wait till the RFC is ready then.

[paragonie-scott]

I'm going to track the progress of writing drafts in #16. Feel free to leave this open until the moment you're satisfied with the progress in the other issue.

[ericchiang]

Wrote a Go implementation today and have some feedback on this issue. I tried implementing the package by only reading the docs but had to dig through the source code on several occasions to figure out what to do.

https://github.com/ericchiang/go-past
https://github.com/paragonie/past/tree/master/docs

Some parts of the doc that I found underspecified:

• v1.enc is underspecified.
  • Info tags for HKDF isn't documented ("past-encryption-key", "past-auth-key-for-aead").
  • Which half of the nonce is used for the key split vs. the CTR IV isn't clear.
• Input to PAE isn't specified. What order are the arguments provided?
  • Header, payload, (optional nonce,) footer?
  • Is the header v1.enc or v1.enc.?
  • Footer is always supplied to PAE even if its empty and not added to the final token.
  • Payload is sometimes included in PAE input, sometimes not?
    • v2.auth: https://github.com/paragonie/past/blob/d2985105/src/Protocol/Version2.php#L44
    • v2.enc: https://github.com/paragonie/past/blob/d2985105/src/Protocol/Version2.php#L217
• LE64 encoding isn't well defined. Do all bytes have to be ASCII escaped? Are ASCII valid points okay?
  • Does LE64(64) encode as @\x00\x00\x00\x00\x00\x00\x00 or \x40\x00\x00\x00\x00\x00\x00\x00?
• How are the MACs and nonces combined with the payload to produce the third token component?
  • It can be base64(payload|mac) or base64(nonce|ciphertext|mac) or base64(nonce|ciphertext).

Happy to volunteer some time for reviews or writing up docs.

[paragonie-scott]

Some of the work in #24 should help here.

Happy to volunteer some time for reviews or writing up docs.

Thanks @ericchiang, if you'd give it a look over before I merge it, I'd greatly appreciate it.