Service description (draft)

Draft version 0.5, 25 October 2026. This text is a draft and is not in force.

What Keylee is

Keylee keeps research data in encrypted containers on the storage of compute sites (clusters and registered workstations, such as a Mac) and holds the containers' keys in a separate service, the broker. People confirm requests with a passkey on an approval service; a web portal shows access and history; the keylee command creates containers and runs jobs.

Keylee at keylee.ethz.ch is a research service of ETH Zurich, run by the Biomedical Informatics group, Dept. of Computer Science, ETH Zurich (bmi.inf.ethz.ch).

Words used here:

• A project lead runs a project: invites, adds and removes members, confirms their site accounts, sets the project's folders and can give rights within the project. In the portal and the commands this role is called PI. A separate broker-wide permission, "May lead projects", which a broker admin gives, lets a person create projects and be named PI.
• An owner manages a container and gives access to it.
• A broker admin administers the deployment: users, sites, roles.
• The operator runs its servers.

What Keylee does

• Encrypts every container at rest, contents and file names, at every protection level. Visible to anyone who can read the storage: the folder tree, file counts, sizes, dates and name lengths. A plaintext marker file next to the container's configuration names the container's ID and the broker's address, so choose IDs that reveal nothing. The format does not authenticate file lengths or the tree: someone who can write the encrypted folder can truncate, swap or roll back files unnoticed; Keylee checks who can write the folder and its parents before each job, and warns where it cannot refuse.
• Releases a key only to an approved job, or once to the approved set-up of a new container on its initializer's device. A job is approved by its own user with a fresh passkey; it runs on a device linked to that user's account on the container's own site; the user needs a grant from an owner and active membership of the project at the time of the release. The key goes to the job's nodes only, sealed to the job's process. File data never passes through the broker.
• Owners give and take access. A grant names one person, one right (read, read and write, or audit, which shows history but never data) and a last day at most a year ahead. Taking access away needs no passkey and is recorded at once: it stops new key releases to that person immediately; their running mounts stop later, at their next check-in with the broker (see "Who can technically obtain keys").
• Records every decision (refusals best effort). Each person sees the entries about themselves; owners and audit-grant holders those of their containers; project leads those of their projects; broker admins everything; the operator everything, through the export.
• Does not control the files. A grant alone gives no access: the container's folder permissions belong to the site, and Keylee cannot change who may read, copy or delete the encrypted files. Pair a revocation with the removal of folder access. Keylee sends no notifications of requests: when a request waits for someone, a person tells them.

Where plaintext exists

The broker holds keys and records; it never receives a container's contents. Plaintext exists:

• Where a job runs: in its mounts, memory and page cache on a node of one of the sites registered with the deployment, or on a user's Mac, under that site's rules; the site's administrators can read it there.
• Wherever a job or its user writes outside the containers. Keylee does not protect that. Below Highly Protected it includes writes by path and over the network; at Limited a job's output may also pass through to the terminal or, on a cluster, to the scheduler's output file instead of a container. On a cluster with a scheduler, the scheduler's own records (job names, working folders, command lines) are plaintext at every level; who can see them depends on the site's rules.

Who can technically obtain keys

• The approved job's process on its node, and the device that sets a container up, once.
• Every owner of a container: an owner can grant any member of the project, themselves included.
• Everyone with a data grant, while their jobs run. A delivered key or a copy of the data cannot be recalled, and a container cannot be given a new key: give access only to people you would trust with a copy.
• Project leads are trusted for who joins a project and for attesting members' site accounts; they receive no key through the role.

Taking access back stops new key releases at once. A running mount ends at its next check-in with the broker (its heartbeat) or, on a node out of contact with the broker, when its offline allowance ends (set by the operator; never more than 6 hours).

The programs keep running and keep what they already read; only the job's user or the site's administrators stop them. One exception: whoever holds the deployment's private certificate authority key could keep a revoked mount served up to its absolute limit (at most 31 days).

Who is trusted

Keylee does not protect data against those who run it. These parties could defeat the protection and are therefore trusted:

• the operator: the broker's unseal key together with a storage snapshot, or its native operator token, reads every container's password;
• the broker host's administrators, the Informatikdienste at ETH Zurich, who administer the virtual machine with root access and so obtain everything on the host;
• whoever controls the approval service or its build: a confirm of any approval its signed-in users may confirm, and a modified client for everyone who installs from it;
• the sign-in service's administrators, or a holder of its signing key, who can act as any user, broker admins included;
• whoever holds the deployment's private certificate authority key, who can intercept the approval service's and the portal's traffic to the broker and keep a revoked mount served up to its absolute limit (at most 31 days);
• the compute sites' administrators, who read running jobs' memory and plaintext and, with users' device keys and unused node credentials on the shared home folder, obtain the keys of jobs not yet run.

Broker admins receive no key through their role (one who is also an owner or grantee gets keys as such). With a passkey they enrol users, register sites, set roles, record site assurances and can weaken the level policy on their own. They suspend users and sites at once, without a passkey, and see the whole audit.

Protection levels

Every container has a minimum protection level, Limited, Standard or Highly Protected, chosen by an owner at creation: its only classification. An owner raises it alone; lowering it needs a project lead of the container's project too. A level states what a job's computers must provide, not which data belongs there; the project lead decides that. This deployment's level policy describes each level in technical terms only.

A job runs at the highest minimum level of its containers (or a higher one it asks for) and may write only into containers at most one level below the highest minimum level of its containers.

What each level requires is set by this deployment's level policy, shown on the portal's Protection levels page and by keylee levels. The operator sets it; a weakening needs a broker admin's passkey, and one broker admin suffices. Fixed in Keylee whatever the policy says:

• Highly Protected always captures a job's output into a container and allows no direct ordinary network (the site's own control or keylee's barrier; a cluster's high-speed interconnect stays reachable). On Linux it always confines file writes to the containers and private temporary folders, unless the site's payload_boundary assurance, that the site is an approved enclave, stands in.
• On a Mac, Standard and Highly Protected always need the site's secure_host assurance that the host is secure in itself; without it a Mac site offers only Limited. Highly Protected on a Mac also needs keylee's sandbox with the site's payload_boundary assurance.

What keylee cannot check on a node, a broker admin may assert for a whole site with evidence and an expiry (a site assurance): a person's statement, not a check.

Main residual risks

The most important open risks:

1. Key custody. The unseal key with a snapshot, or the native operator token, reads every container password; the broker host's swap must be off or encrypted.
2. Identity. A sign-in service administrator can act as any user; a user without a passkey registers one after the first factor alone; any authenticator is accepted, software passkeys included.
3. An undetected rollback. A restore of the broker's records outside the procedure undoes revocations and lets consumed credentials redeem again.
4. The client's integrity. Nothing ties the keylee program on a node to a reviewed build, and whoever controls the approval service can serve a modified client.
5. Scale. Operation with many nodes and growth beyond test size are not shown.

Further risks a project lead should know:

• At Highly Protected on Linux, work started outside keylee run (a scheduler loaded later) escapes the guard.
• A cluster's high-speed interconnect stays reachable under the network barrier and can reach a receiver outside the job.
• The audit records are not tamper-evident against the broker host's administrator, and the cloud account's administrators can delete the off-site audit copy.
• The broker cannot verify where a device is; on a workstation only the client's own protections hold, and the account is the trust boundary.
• No cryptographic primitive has been audited, by the project or by an outside reviewer; the key exchange uses a hybrid scheme from an IETF draft.

Durability and backups

Keylee guarantees nothing beyond the file system. After a confirmed flush, what survives a crash is up to the storage, as for plain files. Encryption amplifies a few losses:

• without its gocryptfs.conf a container is unreadable, even by Keylee;
• without a folder's gocryptfs.diriv, that folder's names are lost;
• an interrupted write before a flush can lose a whole file.

Only a backup helps, and storage that purges old files can delete these files. Keylee makes no copy of a container, and the broker and its backups hold the only copy of each key: a copy of the folder protects against losing the storage, not against losing the key, and cannot be opened without it.

Back up a container's folder while no job writes to it, keep a versioned copy of each gocryptfs.conf outside the broker, and keep what you cannot recreate outside Keylee, under your own data rules. Today no approved way takes data out of a container.

Availability

There is no availability guarantee; the broker is a single service. An outage revokes nothing, but during it no job is approved or started, and running mounts stop when their offline allowance ends (never more than 6 hours). Keylee limits how many requests one person may make.

ETH Zurich may change, suspend or end the service (see the Terms of use). Because the broker holds the only copy of each container's key, the end of the service ends access to every container, and a copy of a container's encrypted folder cannot be opened without that key. The operator announces the end in advance. Projects keep their own copies (see "Durability and backups").

Accounts, containers, projects and sites

One state model applies to users, containers, projects and sites: active; suspended, an immediate brake by one responsible person, after which running jobs lose access at their next check-in; closed, no access at all, reading included, reversible; removed ("erase permanently" in the portal).

Removal is possible only from closed, waits at least 14 days after its confirmations and can be cancelled until the operator's removal run carries it out:

• a container: a second person among its owners, the project leads and the broker admins, within 72 hours; where nobody else can, the requester confirms a second time, separately;
• a project, with all its containers: a project lead and another project lead or a broker admin, within 72 hours, with the same exception;
• a site: two broker admins, always;
• a person: a broker admin alone, or the person's request and a broker admin's confirmation; not while the person holds a primary ownership, a project's last project-lead role or the broker-admin role.

Removing a container or project deletes its keys in the broker, at the operator's removal run. The encrypted files on the site's storage are not deleted by Keylee. The key survives in the broker's backups until they expire, and in any other copy of the server; the removal counts as complete only once a project lead or broker admin confirms those backups deleted.

Removing a person or a site deletes no key. A removed person's record with name and e-mail address, their approvals and the audit trail are kept; their login is disabled and refused. Leaving a project ends the person's rights in its containers.

A project lead's authority over a person is limited to the project: inviting or adding people, removing them from it and giving rights within it. A person removed from a project keeps their account, devices, site accounts and other projects. The person and a broker admin can revoke the person's devices, device links and site accounts; until the next release, a project lead of a project the person belongs to may also revoke them.

Records and retention

Today the deployment keeps decisions, approvals, jobs, the audit trail, the broker's request log and its archive without a time limit; ended or revoked items stay recorded as such. Some short-lived records and the backups are deleted after a limited time.

Planned, not yet implemented: each project gets a field "audit records kept after closing" (6 months to 10 years, by default 1 year), set by a project lead; the project's events and approvals are deleted that long after it closes, and a reopened project's period starts again at its next closing.

Details: the Privacy notice (section 7).

Personal data

The broker processes data about Keylee's users, never research data; the keylee program on a job's nodes processes the mounted plaintext there (see "Where plaintext exists"). The broker holds:

• each user's ID and display name, chosen at enrollment; the e-mail address and sign-in identifier of their login;
• site accounts and devices (a device ID is by default built from the machine's host name);
• host names and scheduler job IDs reported by nodes, which project leads see (a Mac's host name often names its owner);
• approval and audit events naming the acting and the affected person, with free-text reasons;
• the sign-in service's login data (name, e-mail address, password, passkeys, recovery codes, sessions and, with Google sign-in, the linked Google account);
• the broker's request log: the sign-in username and e-mail address behind each browser action, and the network address of each request.

The Privacy notice says what is collected, who sees it, where it goes, how long it is kept and what your rights are.

Where the service runs

• The broker, the approval service, the sign-in service and the portal run on one virtual machine at ETH Zurich, administered with root access by the Informatikdienste at ETH Zurich beside the operator.
• Encrypted off-site copies of the backups and of the audit archive are stored by Amazon Web Services in its Zurich region, which sees each upload's metadata.
• A public certificate authority issues the TLS certificates of the server's web addresses; it receives no user data.
• Users sign in with a password or an organisation's Google Workspace account, then with a passkey.
• Cookies, server logs and what the portal records: see the Privacy notice.

Interactive sessions

The current release offers no interactive sessions. Where Keylee offers them, a session is a job whose program is the user's shell with a terminal. What it shows can leave the container (scrollback, terminal logs, multiplexer buffers, copy and paste), so the captured-output rule does not hold for a session, and Keylee keeps no transcript. A session then rests on the users' training not to copy, export or log data shown on a terminal outside the containers.

Agreements with external data owners

Keylee does not replace a project's agreements: the data owner's agreement with the project's institution, and the use rules of each compute site. The broker's operator holds keys and records, never files. The project lead arranges the agreement.

Liability

ETH Zurich's liability for the Keylee service is governed by the law that applies to ETH Zurich. Use is governed by the Terms of use. [Liability clause: to be written by ETH Zurich's Legal Office, considering the Federal Liability Act.]

Related pages and contact

• Terms of use: your duties as a user, accounts and their removal, and what Keylee does and does not guarantee.
• Privacy notice: which personal data Keylee records, who sees it, where it goes and how long it is kept.
• Legal notice: the responsible unit, liability and copyright.
• Incidents, questions and data protection requests: raetsch@ethz.ch.