Reference sections
Reference โบ Cryptography
The Kitten Cryptography API is one module in two places: the kitten.crypto object on the server and /๐ฑ/library/crypto-1.js in the browser, as an ES module. Keys are 32 bytes. Where a parameter takes hex, it takes a hexadecimal string.
A Kitten server never has a personโs secret. Call the functions that take a private key or an ourPrivateKey parameter in the browser.
Secrets and encoding
secretToEmojiString(secret): Encodes a 32-byte secret as a KittenMoji string (see Cryptographic properties).emojiStringToSecret(emojiString): Decodes a KittenMoji string to the 32-byte secret.bytesToHex(bytes): Converts aUint8Arrayto hex.hexToBytes(hex): Converts hex to aUint8Array. Throws aRangeErrorfor a string that is not hex.randomBytes(bytesLength = 32): Returns cryptographically random bytes from the Web Crypto API.random32ByteTokenInHex(): Returns 32 random bytes as hex. Use it wherever you need a secret token, for example a domain token or a webhook secret.getPublicKey(secretKey): Derives the ed25519 public key for a 32-byte secret key.
Identity creation
createKeys(domain): Creates a random 32-byte secret and returns its key material:private.ed25519(the secret asasBytesand as a KittenMojiasString),private.ssh.asString,public.ed25519(asBytesand hexasString), andpublic.ssh(asBytes,asString, andfingerprint). Thedomainparameter is only used in the SSH keyโs comment,Kitten: person@<domain>. Kittenโs/๐/hello/page calls it in the browser.deriveKeysFromSecretKeyForDomain(secretKey, domain): Returns the key material that thecreateKeys()function returns for an existing secret, withoutprivate.ed25519.
Signing
sign(message, privateKey): Signs a message (bytes or hex) with an ed25519 private key (bytes, hex, or a Web CryptoCryptoKey) and returns the 64-byte EdDSA (Edwards-curve Digital Signature Algorithm) signature.verify(signature, message, publicKey): Returnstruewhen the signature is valid for the message and the ed25519 public key (bytes, hex, or aCryptoKey), andfalseotherwise, including for a malformed key or signature.
Encryption
encrypt(key, plaintext): Encrypts a UTF-8 string or bytes with XChaCha20-Poly1305 under a 32-byte key and a random 24-byte nonce, and returns nonce โ ciphertext.decrypt(key, encoded): Decrypts nonce โ ciphertext (bytes or hex) and returns the plaintext bytes. Rejects when the key is wrong or the ciphertext has been altered.
Domains
A domainโs identity is the ed25519 public key it publishes at https://<domain>/๐/id/. Where a function takes an ourPrivateKey parameter, pass the KittenMoji secret, the raw 32-byte secret, or the identity that the getIdentity() function returns from the key store (below).
publicKeyForDomain(domain): Fetches the ed25519 public key the domain publishes and returns its 32 raw bytes. Use it toverify()a signature made by the domainโs owner, in the browser or on a server; to pin a domainโs key and notice when it changes; or to show its fingerprint to compare in person. Rejects when the request fails, when the domain responds with an HTTP error status, or when the body is not a hex-encoded 32-byte key. Include the port in the domain when it is not 443.sharedSecretForDomain(domain, ourPrivateKey): Returns the 32-byte symmetric key shared with the domain. Maps the domainโs ed25519 public key to X25519, andourPrivateKeytoo when it is a secret, performs the Diffie-Hellman key agreement in Web Crypto, and derives the key with HKDF-SHA-256 (HMAC-based key derivation with SHA-256). The result is cached per domain.encryptMessageForDomain(message, ourPrivateKey, domain): Encrypts a string for the domain with the shared secret and returns a versioned envelope:v2:followed by the hex nonce โ ciphertext.decryptMessageFromDomain(encryptedMessage, ourPrivateKey, domain): Decrypts an envelope from the domain and returns the UTF-8 string. Rejects an envelope that does not start withv2:.getSharedSecret(privateKey, publicKey): Returns the raw X25519 Diffie-Hellman output for an ed25519 private key and an ed25519 public key, without HKDF. Prefer thesharedSecretForDomain()function.
Key store
In the browser, the /๐ฑ/library/key-store-1.js module stores a personโs identity as non-extractable Web Crypto keys in IndexedDB, or in memory for the session when IndexedDB is unavailable. The raw secret is never persisted. Kittenโs sign-in page stores the identity and its sign-out route clears it.
getIdentity(): Returns the stored identity, ornullwhen nobody is signed in. Pass it as theourPrivateKeyargument to the domain functions above.storeIdentity(secret): Imports a 32-byte secret as an identity and stores it.clearIdentity(): Removes the stored identity.importIdentity(secret): Imports a 32-byte secret as an identity without storing it.
An identity has the signingKey (ed25519, non-extractable), keyAgreementKey (X25519, non-extractable), ed25519PublicKeyHex, and x25519PublicKeyHex properties. See Browser support for a WebKit limitation on X25519 keys.
The security (and privacy) of Catalyst/Kitten are based on a 32-byte cryptographically-random secret string that only the person who owns/controls a Small Web place knows.
This is a Base256-encoded ed25519 secret key where the Base256 alphabet is a set of curated emoji surrogate pairs without any special modifiers chosen mainly from the animals, plants, and food groups with some exceptions (to avoid common phobias or triggers, etc.) that we call KittenMoji.
๐ต๐๐ฆ๐ฆง๐ถ๐๐ฆฎ๐ฉ๐บ๐ฆ๐ฆ๐ฑ๐๐ฆ๐ฏ๐
๐๐ด๐งฎ๐ฆ๐ฆ๐ฆ๐ฆฌ๐ฎ๐๐๐๐ท๐๐๐ฝ๐
๐๐๐ช๐ซ๐ฆ๐ฆ๐๐ฆฃ๐ฆ๐ฆ๐ญ๐๐๐น๐ฐ๐
๐๐ฆซ๐ฆ๐ฆ๐ป๐จ๐ผ๐ฆฅ๐ฆฆ๐ฆจ๐ฆ๐ฆก๐พ๐ฆ๐น๐
๐ฃ๐ค๐ฅ๐ฆ๐ง๐๐ฆ
๐ฆ๐ฆข๐ฆ๐ฆค๐ชถ๐ฆฉ๐ฆ๐ฆ๐ฒ
๐๐ข๐ฆ๐๐๐ฆ๐ฆ๐ณ๐๐ฌ๐ฆญ๐๐ ๐ก๐ฆ๐
๐๐๐ฆ๐๐๐๐ชฒ๐๐ฆ๐ญ๐๐งฌ๐ชฑ๐ฆ ๐๐ธ
๐ ๐๐น๐งฃ๐บ๐ป๐ผ๐ท๐ฑ๐ชด๐ฒ๐ณ๐ด๐ต๐พ๐ฟ
๐ค๐๐๐ชบ๐ฝ๐๐๐๐๐๐๐๐ฅญ๐๐๐
๐๐๐๐ซ๐ฅ๐
๐ซ๐ฅฅ๐ฅ๐๐ฅ๐ฅ๐ฝ๐งธ๐ซ๐ฅ
๐ฅฌ๐ฅฆ๐ง๐ง
๐๐ฅ๐ฐ๐๐ฅ๐ฅ๐ฉ๐ฅจ๐ฅฏ๐ฅ๐ง๐ง
๐ถ๐ธ๐พ๐จ๐๐ญ๐๐ญ๐ฅช๐ฎ๐ฏ๐ธ๐ท๐๐ฅ๐
๐ผ๐๐พ๐ป๐ฅ๐ฟ๐งฉ๐๐ฅซ๐ธ๐๐๐๐๐๐
๐ ๐ข๐ฃ๐ค๐ฅ๐ฅฎ๐ก๐ฅ๐ฅ ๐ฉฐ๐ฆ๐ฆ๐ฆ๐ฆ๐ก๐ฆ
๐ง๐จ๐ฉ๐ช๐๐ฐ๐ง๐ฅง๐ซ๐ฌ๐ญ๐ฎ๐๐ผ๐ฎ๐น
๐ซ๐๐๐๐งญ๐ ๐ช๐ช๐งต๐งถ๐ง๐๐ช๐๐๐
The KittenMoji standard was frozen in time on Friday, November 25th, 2022.
The string created by joining the list of the full KittenMoji alphabet has the following hash: d9b1533de36a75c9e47f1713aada4ff332918ff0d3cada5b645ca84d73dd50d6.
When setting up a Small Web app via Catalyst, this key is generated in the personโs browser, on their own computer, and is never communicated to either the Catalyst instance or the Kitten app being installed. Instead the ed25519 public key is sent to both and signed token authentication is used when the server needs to verify the ownerโs identity (e.g., before allowing access to the administration area).
Kitten uses the Web Crypto API and non-extractable keys to ensure that even if a session is intercepted by a cross-site scripting attack, the long-term secret key is still safe. (In such a hypothetical attack, if successful, the attacker will be able to sign/encrypt messages as the person who owns the Small Web site/app but will not have access to their key material.)
The expected/encouraged behaviour is for the person to store this secret in their password manager of choice.
For encryption, Kitten uses Diffie-Hellman key exchange and XChaCha20-Poly1305 where the secret key from the key exchange is run through the HKDF-SHA-256 key derivation function.
Static keys that never leave the client are a core aspect of Kittenโs usable security model. This means the number of messages encrypted with a single key is essentially unbounded. This is why Kitten uses XChaCha20, which has a 192-bit nonce thatโs safe to generate randomly. This lets us avoid the added complexity of key rotation or nonce-state management.
Kitten running on a development machine can also recreate these SSH keys and configure the personโs SSH access to their server when the secret key is provided.
The personโs ed25519 public key is used as their identity within the system and enables their Small Web place (Kitten app) to communicate with the Catalyst instance for administrative reasons (e.g., to cancel hosting, etc.)
The audience for Catalyst/Kitten and the Small Web in general is everyday people who use technology as an everyday thing and want privacy by default in the systems they use.
If you are an activist, etc., who might be specifically targetted by nation states, etc., please do not use this system as it does not protect against, for example, infiltration of hosting providers by nation state actors.
Given that the secret key material is generated in a web app, you must trust that the code being served by the server is what you expect it to be. Currently, there is no validation mechanism for this, although this is on the roadmap going forward (via, for example, a browser extension). This is not a problem unique to web apps, given that native apps are commonly dynamically built by app stores (at which point a nation state actor could inject malicious code) and given the lack of verifiable builds in mainstream supply chains.
You can, however, overcome this limitation by hosting Kitten and Catalyst yourself, on your own hardware (e.g., a single-board computer like a Raspberry Pi).
The other thing to be aware of is that the security of the system is based on your secret key remaining secret and, initially at least, there will not be a way to change this secret key. (On the longer roadmap, it would be nice to provide a means of changing it but this is not a trivial process, especially if encryption keys have been derived from it and encrypted messages exist within a Kitten app).
WebKit cannot read an X25519 CryptoKey back from IndexedDB (WebKit bug 312279). The write succeeds but the read returns null. Sign-in works in Safari. After sign-in, the getIdentity() function returns null, and end-to-end encryption does not work. There is currently no acceptable workaround that doesnโt weaken the cryptographic properties of Kitten. Until the bug is fixed in WebKit, use a non-WebKit/non-Safari browser for Small Web apps that require end-to-end encryption.