RFC: Naming sets of keys

[franky47]

At the moment, the naming of some objects in both the client, the server and the API in between is very confusing, and caused some incomprehension, so better names should be defined to improve the developer experience.

Most of it has to do with abstraction leaks, from what the protocol for sharing keys looks like, and which transpired in the database modeling and the naming of counterpart objects on the client side.

Here's a description of the domain objects involved:

The client holds collections (note the plural) of keys.

Each collection has:

• A type of key associated with an encryption algorithm (eg: secretBox for symmetric encryption, sealedBox for form data key pairs)
• One or more keys (or key pairs), the most recent being used for encryption, and the other kept for backwards-decryptability.
• A purpose given by the application in the form of a string (what it's used for, eg: "contact-form" or "channels:#general").
• An internal secret, used to uniquely identify a collection

From the purpose string and the internal secret, a fingerprint (a one-way hash with a constant output length) is computed, and used throughout the API for reference. Knowledge of both the purpose string and the internal secret allows computing the fingerprint, and is used as a zero-knowledge proof of ownership when sending and receiving keys to/from others.

Keys within a collection are also identified with a fingerprint of the secret or private key. This is used when performing operations on a specific key in a specific collection (not just the most recent one, for which there are shortcuts).

One issue we encountered with this system was that a user may create a collection for the purpose foo, another user may do the same, and both would end up with different internal secrets, and therefore collection fingerprints, causing confusion.

Keeping the purpose in clear-text is not recommended as it may convey sensitive information that may fall under the end-to-end encryption targets. Moreover, its secrecy prevents the server from injecting keys.

Conveying the idea that creating a collection is very different from being shared access to an existing collection, even if the purpose strings may be the same, is important for documentation and DX improvement.

Another semantic improvement is to convey the public property of fingerprints (which are safe to send to both the e2esdk and the application servers), versus the privacy of the purpose string, which may be used by application code for filtering, retrieval of keys and UI display, but must not be disclosed to any server.

Currently, the confusing names are:

• nameFingerprint: the fingerprint of a collection of keys (safe to exchange with the server)
• payloadFingerprint: the fingerprint of a specific key in a collection (safe to exchange with the server)
• label: the purpose string
• keychainItem: the object describing a complete key, which collection it belongs to, along with secret key material. Internal to the client, not developer-facing.
• keychainItemMetadata: a developer-facing object representing a specific key, without the secret key material.

If we see a collection of keys as a keychain, keeping an analogy with physical key rings with multiple keys on it, then each key on it would be a keychain item. The client would hold one keychain per purpose. Physical keychains often come with a tag or some sort of way to identify them, so this is where we could fit the private purpose and public fingerprint.

We don't need a name for the collection of keychains, though if we needed to further the analogy, a key box as found in hotels or valet parking spaces would work.

[franky47]

Since the documentation branch also includes data-breaking bug fixes for the form signatures, I'd wager we could do a large renaming operation that requires resetting the database, while everything is in beta and there aren't any production-worthy implementations by third parties.

I will assist with the API updates in the socialgouv/template repository, there shouldn't be many other than following the new naming convention.

The renaming will go as follows:

Old name	New name	Description
name	encryptedKeychainName	Encrypted record in the database for the keychain name (purpose label + secret internal random string)
payload	encryptedKey	Encrypted record in the database for the key material (private key or secret key)
nameFingerprint	keychainFingerprint	Fingerprint of cleartext of the keychain name as above, for identification and queries
payloadFingerprint	keyFingerprint	Fingerprint of the key material, for targeting a specific key in a keychain
label	purpose	String associated with a keychain, used client-side for querying keychains

[revolunet]

yes, good time to rename things 👍