New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specification unclear #9

Closed
yaaminu opened this Issue Jan 4, 2018 · 5 comments

Comments

Projects
None yet
3 participants
@yaaminu

yaaminu commented Jan 4, 2018

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

This comment has been minimized.

Show comment
Hide comment
@paragonie-scott

paragonie-scott Jan 4, 2018

Member

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.

Member

paragonie-scott commented Jan 4, 2018

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

This comment has been minimized.

Show comment
Hide comment
@yaaminu

yaaminu Jan 4, 2018

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

yaaminu commented Jan 4, 2018

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

@paragonie-scott paragonie-scott self-assigned this Jan 4, 2018

@paragonie-scott

This comment has been minimized.

Show comment
Hide comment
@paragonie-scott

paragonie-scott Jan 4, 2018

Member

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.

Member

paragonie-scott commented Jan 4, 2018

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

This comment has been minimized.

Show comment
Hide comment
@ericchiang

ericchiang Jan 5, 2018

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?
  • 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.

ericchiang commented Jan 5, 2018

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?
  • 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

This comment has been minimized.

Show comment
Hide comment
@paragonie-scott

paragonie-scott Jan 7, 2018

Member

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.

Member

paragonie-scott commented Jan 7, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment