[WIP] Documentation Improvements and Implementation Guide #59
Conversation
| @@ -19,6 +19,12 @@ to assist in cross-platform library development. | |||
| * If there are only two versions, that means `v1` and `v2`. | |||
| * If a future post-quantum `v3` is defined, `v1` should no longer be accepted. | |||
| * If an additional version `v4` is defined, `v2` should no longer be accepted. | |||
| 5. New versions will be decided and formalized by the PASETO developers. | |||
| * User-defined homemade protocols are discouraged. If implementors wish to break | |||
There was a problem hiding this comment.
The README indicates that the protocol and the payload are in separate parts. Does this mean that we are still valid for v2/v1 if we make our payload a Protobuf or msgpack? If we have to use a new protocol, most parsers won't know what to do cryptographically even if we use the lower-level decryption methods, as the version is used as a key to determine which algorithms to use.
There was a problem hiding this comment.
The cryptography is totally agnostic to the underlying format. If you wanted to use a non-JSON format, you can do that, but for simplicity we're aiming for JWT replacement (the 80% problem) rather than all use cases (the 99% problem).
There was a problem hiding this comment.
Just for some context, I'm working on a new version of pypaseto that provides JSON encoding/decoding and limited claims validation. Part of my current function allows someone to specify an encoder object that has methods for encoding/decoding if they want to replace the JSON inside. As long as their encoder/decoder allows settings/reading an "exp" field, the "exp" field will be validated against the current time.
There was a problem hiding this comment.
I'm going to probably call the cryptography layer its own thing, and put it in its own section, when I write the PASETO RFC. That way you can say "we use PASETO-CRYPTO (name tentative) with Protobuf" but the shorthand "PASETO" just means "PASETO-CRYPTO with JSON payloads".
|
|
||
| Implementations should feel free to provide a means to extract the footer from a token, | ||
| before decryption, since the footer is used in the calculation of the authentication | ||
| tag for the encrypted payload. |
There was a problem hiding this comment.
Is there any recommended wording around emphasising that: when footers are extracted prior to decryption/verification of a message, then they have not been cryptographically verified.
i.e. given that we're telling users that the footer is authenticated in other parts of documentation, any recommended wording to make it abundantly clear that the footer has not been authenticated in this case.
(I mean, it's hopefully obvious – just trying eliminate any potential for confusion to arise here)
I've currently got this, but it's a little long winded – probably the more succinct the better :)
Unfinished, but should shore up all of our documentation loose ends (except a formal RFC):
Closes #9, #27, #29, #53, #54 upon merge.