Keyczar docs and use cases?

[Will Sargent]

Hi all,

I've noticed that Keyczar documentation is missing some details -- it seems to assume users know why key management / rotation is a big deal, and what KeyCzar provides over the usual primitives.

For example, Signed Sessions and Timeout Verify are useful features, but are not mentioned in the README or in the PDF, and are only available on the wiki: 

* https://github.com/google/keyczar/wiki/OperationTimeoutVerify

* https://github.com/google/keyczar/wiki/OperationSignedSessions

In addition, the docs often don't explain the situation in which users would want to prefer one mode of interaction over another, for example Signed Session says:

"Encrypts a 128 bit AES symmetric key using another keyczar key in session material and uses it to encrypt communication between two parties. The ciphertext is all signed by the passed in signing key.  The session material is encrypted json containing an AES key and a WebSafeBase64 nonce. Note that session material is not signed."

My line of reasoning so far on sessions is that whereas you'd usually use TLS if you were sending data as part of a session, TLS only encrypts over the wire, and is verified to the hostname.  So, if you're on a hosted system like ngrok or a partial TLS solution like Cloudflare, and so don't have end to end TLS, then using a signed session on top of that will ensure that the data hasn't been read or modified in the case of a MiTM attack.

Likewise, looking at Keyczar's key tool feature, it's clear that key provisioning and rotation are considered to be integral to the system, but in practical terms, it doesn't tell you how to manage keys.  It'd be helpful to specify at least the references to key management that might be useful here, for example:

* https://en.wikipedia.org/wiki/Key_management 

* https://www.owasp.org/index.php/Cryptographic_Storage_Cheat_Sheet

* PCI DSS 3.0

* NIST SP 800-57 

* http://www.secureconsulting.net/Talks/key-mgmt-CIScon-2009.pdf

I'd like to make sure I'm not missing anything, but the usual sources of info / background are coming up blank on real world usage of KeyCzar.  There are a couple of examples:  

* Paul Querna: https://journal.paul.querna.org/articles/2013/11/09/security-of-infrastructure-secrets/

* Tomaz Muraus: https://www.tomaz.me/2013/12/27/designing-a-server-side-application-for-secure-storage-of-access-tokens-and-other-secrets.html

But I'd like to be able to provide grounded examples of why KeyCzar is a good idea, and in what context you would use it.  If you have any documentation or example projects, I'd love to see them.

Will.

[Will Sargent]

Following up to add the group discuss link on signed sessions ("I've avoided implementing it because of my lack of understanding as to why someone should choose to use this feature."):

https://groups.google.com/d/topic/keyczar-discuss/UpWhHdt8skw/discussion