keystar

KeyStar v2.x

KeyStar v2.x+ introduces several incompatible changes to the underlying architecture aiming for improved security and ease of use. In particular, all transactions will be performed on encrypted data, regardless of the transport, that is decrypted by the client-side of the transaction. This means that once key data reaches the transport or storage layers, the service layer is incapable of reading it.

This introduces a few challenges, namely regarding key expiration and rotation since the server will no longer be able to automatically expire or rotate keys. Moreover, any other key metadata will be completely opaque. To address this, expiration and rotation will be managed on the client side of the transaction, with most features occurring at the time the key is read. As a side effect of this, read-time expiration and/or rotation obviates the need for any sort of background cron process required to perform maintenance duties.

Further, since the secrets will be encrypted (and signed), two distinct advantages arise out of this use case: Firstly, the cryptographic code required to secure secrets in KeyStar will be greatly simplified and offloaded to the client implementation, thereby keeping the server implementation as a storage layer (local access) or an HTTP API. Second, destroying secrets on the server-side no longer requires any form of implicit trust; once the client keys are destroyed, the secrets are--for all intents and purposes--irretrievable.

Internally, KeyStar leverages our go/vfs library for interfacing with file systems (including HTTP, which will use a VFS-compatible interface that will eventually be back ported into VFS).

Cryptographic Design

KeyStar will explore providing client- and server-based authentication using ED25519 keys similar in nature to SSH. In this mode, authenticated connections will exist within the confines of their own namespace and will be able to freely create key rings and secret stores without conflicting with other connections. This mode will be mostly limited to HTTP access.

In its current incantation, KeyStar will be using ChaCha20poly1305 for encrypting secrets. Using this mechanism, the entire secret, its metadata, and content will be encrypted before being dispatched to the storage layer. This will happen transparently via the backend interface, either before touching a remote HTTP instance, or before funneling the data into configured storage.

Storage Layer

Similarly to the KeyStar v1 API, v2 will provide a concept similar to namespaces. However, unlike v1, authenticated accessors will not be able to create namespaces themselves. Instead, each authenticated key will create its own unique namespace. Within that namespace, the account will be able to create multiple key rings for logically organizing related key and secret data.

For the on-disk or in-process API, namespaces will similarly be nixed and replaced by the keyring.

Keyrings will themselves see some changes. In particular, the option for rotating an entire keyring will be removed since key rotation and expiration will be handled on an individual basis at runtime and only when the key is accessed. This does infer that expired keys may persist indefinitely in storage, but automatically removing keys is not a particularly good idea; it should be left to the client to design when (or if) to remove a set of keys.

Keyrings will also no longer be mandatory. Keys can be attached directly to the current session, which will implicitly store them in a global keyring.

Composite keys will also no longer be an integral concept in KeyStar. How the key or secret is itself managed will depend on the caller. KeyStar will provide utilities for splitting out single secrets into multiple keys (including composite keys), but the conceptual limitations imposed by composite keys drove some of the prior KeyStar development into a direction that felt too limiting.