Update pseudo-code to latest design

[nguerrera]

Also move the pseudo-code from devdocs to docs.

[nguerrera]

I will wait for @michaelcfanning to review before merging and also for the matching implementation in #27 to be approved.

[michaelcfanning]

data

maybe add a comment here (because the CASK primary key has been determined to be valid, 'N' will comprise a number that is divisible by 3 #Closed

[michaelcfanning]

signature

if we preserve HIS v2 conventions, the leading character of every provider id must be an alpha character. Furthermore, this alpha character establishes a casing for the provider id that must be consistent with any other alpha chars in the signature. A signature with a leading upper-case character comprises a user-managed key (and all other chars in the sig must be upper-case). A signature with a leading lower-case char comprises a service-managed key (and all other chars in the sig must also be lowercase).

[nguerrera]

OK, should we preserve these? I found the upper and lower case thing confusing when I touched something related for the first time in HISv2, FWIW.

The current description matches the current code. And the current code was chosen by me when I discovered that the initial draft did no validation.

If we want to change this, I think it would be best to do it in its own PR that updates the code, tests, and pseudo-code.

[michaelcfanning]

OK. So, this convention is important/useful for providers but it doesn't have to be a requirement in the standard.

The core problem is ownership/remediation accountability. When a user-managed key is spilled, we want the user to be informed/to remediate. When a service-managed key is spilled, we obviously want to alert the service provider and the provider will benefit from time/air cover if possible to drive remediation.

Imagine a secret spilled into public OSS. For a user-managed key, you would reasonably inform the repo owner of the exposure. For a server managed secret, you might not want that kind of alerting, instead, you'd want a direct notification sent to the platform only (GitHub sends these notices to service owners today).

So let's check in what you have, and perhaps we have some supplemental content in our repo for advanced/nuanced extensions to the core requirements. How to encode a key lifetime is another example where some suggested techniques might make sense without having a hard standard.

[michaelcfanning]

characters

are we working in bytes or characters for this description, I'm getting a little confused.

if the provider data is chars, the length is a multiple of 4, not more than 20 encoded chars. if it is bytes, the length is a multiple of 3, no more than 15 bytes. #Resolved

[nguerrera]

I had a bug here with 3 and 4 inverted, but the limits in the code are currently, 32 chars / 24 bytes.

[michaelcfanning]

I don't believe this is correct. Validate my thinking.

33 random + 6 signatures + 3 timestamp + 6 (reserved + checksum)
That's 48 bytes. Now, we have a natural limit on this key of 64 bytes, otherwise the key risks triggering HMAC hashing on use as an initializer. Because of our 3 byte alignment, our natural limit is 63 bytes. 63 - 48 bytes == 15 byte limit on optional data.

[nguerrera]

I am avoiding changing the code in this change. I believe what I said is correct with respect to the current implementation. I will change the limit in code and pseudo-code in a follow-up.

[michaelcfanning]

makes sense, let's get this in and keep iterating.

[michaelcfanning]

[rwoll]

These keys/algorithm pack a lot in there. That's not necessarily a bad thing, but one thing missing from the documentation is the why behind a lot of these choices.

Depending on required properties of the keys, the simplest algorithm is:

<provider_id>_<crypt rand hex>_<checksum>

That's easy for someone to implement (efficiently), verify implementation, and find keys all within a few minutes compared with this pseudocode.

If I'm a stranger first encountering this spec and I look and see the "complicated" bits about timestamp embedding, I might go: "do I really need that? why is that useful? what scenarios do I use that in? Why is that required? If I'm a provider can and I need that, can I just put it in the reserved provider bits?"

It's out of scope for this PR, but another document to supplement the pseudocode would be one that rationalizes each component of the key and any major choices made along the way.

This is not suggesting to remove anything, just encouraging documenting the choices and scenarios before they are lost to time.