Designing an Identity Manager

If you’re unfamiliar with the concept of an identity manager, check out our introductory posts on how we’re approaching consumer identity at Uno and why passwords suck.

Zzz...

There are people who find scrambling bits and prime number arithmetic exciting, if that’s you, consider a career in cryptography. For the rest of us, this stuff is boring. But, in the case of cryptographic applications, boring is exactly what you want.

From a security angle, “boring” means:

• use off the shelf standard battle-tested cryptographic primitives
• from community verified and expert audited projects
• implemented in memory-safe languages
• applied in simple, obvious, and intended ways.

So that’s what we did for Uno’s core identity and security layer.

QED

Yeah, right. It'd be nice if it were that easy, but we're serious about good security and thin promises aren't that. Instead, I’m going to walk through exactly what design choices we made so you can understand, audit, and critique our implementation yourself. And of course, the source code to our rust reference implementation is freely available if source dives are more your style.

Cryptographic Identity Foundation

User Entropy

Every Uno user generates 256 bits of entropy drawn from their operating system’s cryptographically secure pseudo random number generator (CSPRNG). This constitutes a user’s identity seed. Fundamentally, everything a user needs is derived from these 256 bits. These bits are what our application helps the user store and protect, shard and socially escrow, and synchronize across devices. Like a DeFi/Web3 “wallet”, a user is a single seed.

At rest, a user’s identity seed is always encrypted using the system’s hardware device backed cryptographic primitives e.g. Apple’s secure enclave, or generically a trusted platform module. Unlike a traditional password manager, Uno does not ask the user to remember a password. Consequently, our application is designed to be used only on devices that have hardware security modules.

From the seed entropy we derive use-case specific keys and secrets because it’s bad to cross your cryptographic streams.

Key Derivation

We derive keys using Blake3. Blake3 is an efficient 3-in-1 hash function, key derivation function, and extendable output function (XOF) which we find very convenient. Should Blake3 prove weak or broken upon future cryptanalysis, HKDF is a perfectly conservative (albeit computationally wasteful) alternative.

Each user needs a set of Ed25519 signing keys, X25519 asymmetric encryption keys, and a private symmetric vault encryption key. When deriving sub-keys, it is imperative that an application-scoped, use-case specific context be used. We use an application tag "uno seed" plus " " plus the specific use case (e.g. "identity keypair", or "encryption secret").

Key derivation simply looks like:

let subkey = blake3::derive_key("context string", &seed);

The most important concept is that these sub-keys are deterministic but also cryptographically independent from the main seed and can be used freely for their own purposes without worrying about cross pollination.

Key Usage

With the three derived keys a user can:

1. encrypt documents that should only be accessible by the same user, e.g. their digital “vault”,
2. sign messages to other components of our system, including other users, and
3. establish a shared encryption key with another party in order to exchange secret messages.

Together, these actions plus our relevant domain logic compose into the foundation for a secure, cryptographically independent, application layer that does not depend on the security of the any networking, transport, or storage systems except during the explicitly out-of-band key-exchange segment.

Digital Vault

One of the core features we offer users is credential document management. Colloquially, we save your logins. Of course we do a lot more than that, but these sensitive credentials need to be protected which is why we go through all the trouble.

We use ChaCha20-Poly1305 as our authenticated encryption with additional data (AEAD) primitive. We generate a new random 12-byte nonce for every vault encryption operation and prepend it to the resulting cipher text when storing it. The cipher is keyed using the symmetric encryption key derived from a user’s seed.

A user’s vault is just a JSON document the structure of which is not relevant right now. One thing to point out is that we encrypt and decrypt the entire vault, not individual key paths. The entire vault is an opaque encrypted blob to anything without the key.

One more tidbit, all our encrypt and decrypt operations use independent additional data strings to bind arbitrary cipher-text to specific use cases. This often overlooked step is important to ensure that an adversary can’t pull out valid encrypted blobs from one part of the application and use them in another spot.

That’s really all there is to the vault right now. Of course we expect to build in more sophistication over time (perhaps occasional and/or automated rekeying, perhaps exposing some of the non-sensitive structure to the server application to help manage distributed data synchronization, etc.) but fundamentally an Uno vault is just an encrypted document that, once decrypted, you can read and write using jq.

Signed Documents

The second key usage is document signing. Documents may be messages to other users or http requests to the API backend. We use the Ed25519 signature scheme for document verification. Signing documents is perhaps the most widely used cryptographic primitive and there isn’t much extra to add here regarding our application of Ed25519. We simply construct a user’s private key from the derived bytes, and from that compute the public key. Signing is a primitive operation that an Ed25519 private key can perform and results in an EdDSA signature.

let private_key = ed25519_dalek::SecretKey::from_bytes(&subkey_signing);
let keypair = private_key.into();
let signature = keypair.sign(message);

It is important to note that we use the public signing key for user identity purposes. This key is essentially a user’s database ID, except we don’t have a central database. It is a somewhat arbitrary selection since we could use the X25519 public key or derive an independent id, but since every message in our application is signed it’s proven rather consistent to expect that components needing to verify messages and index user operations have the user’s unique public signing key at hand. After all, the point of a public key is to uniquely identify some entity.

Secure Messaging

Our identity manager is social. I cover the motivation behind that in the Replacing passwords with people post because there’s a whole can of worms to unpack. For the scope of this overview just know that it’s important to be able to securely communicate with other Uno users in a way that the server cannot observe. The use case is not like a traditional secure messenger app designed to allow journalists to report on whistler-blowers without the prying eye of nation-sates, that’s best left to the secure messenger domain. But, rather, in our domain simply used for privately coordinating certain actions related to managing your identity like informing others about updates to your recovery shares, or sending someone your Netflix password.

The algorithm used to implement our encrypted messages is X25519 Elliptic Curve Diffie-Hellman. The Uno public key exchange is also the topic of another essay. For now assume two users have acquired each others’ public X25519 keys. Once public keys are exchanged the two peers can compute a static symmetric ECDH shared key.

let private_key = x25519_dalek::StaticSecret::from(&subkey_encryption);
let peer_pubkey = x25519_dalek::PublicKey::from(&peer_pubkey_bytes);
let shared_secret = private_key.diffie_hellman(&peer_pubkey);

We could use the static key to directly encrypt messages, but it’s better form to derive per-message keys off the static key so that compromise of any single message’s key does not compromise the integrity of other messages, past or future. To this end every message has an ID (we use a UUID). After each client computes their shared static DH key, we

let per_message_key = blake3::derive_key("message uuid", &shared_secret);

and use the resulting 32 bytes as the per-message encryption key which we use with our standard AEAD and authenticate with a context unique to the message’s use case.

The messaging protocol itself deserves some in-depth coverage at some point, but for now rest assured all messages are signed by the sender and encrypted for the recipient. Signatures are verified before the message is further processed.

Wake Up

I notice you dozed off. Don’t worry I’m not offended, that’s a good sign. It means we’re not doing anything interesting and simply using bog standard cryptographic primitives in unassuming ways. If you didn’t nod off, please [join our discord] and let us know. We are always looking for ways to improve, even especially on the boring stuff.