# Team keys and the Recovery Kit

> How a Team Cloud team's keys are made on an admin's Mac, what the Team Recovery Kit can do, where to keep it, and how the Team Security code checks every Mac agrees.

Source: https://docs.subcloak.com/cloak-proxy/team/team-keys/

Added in Cloak Proxy 0.7.0.

{/* L9 draft. Sources: PLAN 5, 6.2, 6.6; T3, T4.4, T5.5. Re-check labels against L8. */}

A team's data is encrypted with keys that exist only on members' Macs, on the CI tokens admins create (for the spaces they're given) and on one printed page, the **Team Recovery Kit**. This page explains how the keys are made, what the kit can do and how the **Team Security code** lets you check that every Mac agrees on who is in the team.

## How the keys are made

{/* PLAN 6.2, 5 */}

The first admin's Mac makes the team's keys in **Settings › Team › Set Up Team Keys**. Only public keys and sealed copies reach Subcloak's server; it can't open the sealed copies:

- **The team key** encrypts every **open** space. Each member's Mac gets its own sealed copy, which only that Mac can open. It's replaced with a new one whenever someone is removed or the kit is used.
- **Space keys** encrypt each **restricted** space, such as a vault folder. A Mac gets one only through a signed grant, and only if its owner is listed in that space's access list.
- **Each Mac's own keys** sign everything it writes and receive the sealed copies. They're made separately for each team, apart from Personal Cloud's, and stay in the Mac's Keychain.
- **The Team Recovery Kit** is a spare way in: every team key and every restricted space's key is also sealed to it.

Each Mac also makes encryption keys for the spaces it writes in, a new one after each change of the team key. A team can hold up to 15,000 of these, and one member's Macs can make up to 300 a day. Past the daily limit a Mac's changes wait until the next day. A team that reaches 15,000 can't make new ones, so its Macs can't upload changes to spaces that need a new key; **Settings › Team** says so next to Sync. Nothing in the app frees them yet: contact [support@subcloak.com](mailto:support@subcloak.com).

See [Security model](https://docs.subcloak.com/cloak-proxy/team/security-model/) for the algorithms.

## The Team Recovery Kit

{/* PLAN 6.2 step 4, 6.6; T5.5 */}

> **Whoever holds the kit can read all of the team's data:**
> The kit opens every open space and every restricted space, vault folders included, and can make its holder an admin. Store it where your company keeps critical secrets, such as a safe or a password manager only the owner and a backup person can open.

The kit is a one-page PDF your Mac shows once, when the keys are set up. Save or print it. An admin's Mac reports to the console that it was stored, which ticks the setup checklist.

| You can | How |
|---|---|
| **Recover the team** when every admin's Mac is lost | On a new Mac, in **Settings › Team**, **No Admin's Mac Left? Recover with the Recovery Kit…**. See [Recovery and start over](https://docs.subcloak.com/cloak-proxy/team/recovery-and-start-over/). |
| **Make a new kit** | **Settings › Team › Security › Make a New Kit…** on an admin's Mac. The audit log records it (`kit.rotated`). |
| **See whether it's stored** | **Settings › Team › Security** shows the kit's state. |

{/* VERIFY(L1/L7) before applying: what the old kit can still open after Make a New Kit (T4 rotate_recovery). */}

Every member's Mac lists each use under **Settings › Team › Security** ("The Team Recovery Kit was used"), admins' Macs also ask "Was this you or someone you trust?", and the audit log records `kit.used`. The server can't hide this: each Mac works it out from the team's signed member list. {/* PLAN 12.3 item 15 */}

## The Team Security code

{/* T4.4 */}

**Settings › Team › Security** shows a 20-digit **Team Security code**, in 5 groups of 4 digits. It's worked out on each Mac from the team's members, their roles, their Macs, the current team key, the Recovery Kit and the team's key options. Two members whose Macs show the same code agree on exactly who can read the team's data.

The code changes whenever someone joins or leaves, a role or a Mac changes, the kit is used or replaced, or an option such as [automatic approval after SSO](https://docs.subcloak.com/cloak-proxy/team/invite-and-approve/#approve-macs-automatically-after-sso) changes.

Compare it now and then, and always after a Mac joined by automatic approval.

## Where the keys live on a Mac

{/* T1 (keychain item per team), PLAN 6.7 */}

- Each team's Mac keys are in the login Keychain, one item per team, separate from Personal Cloud's.
- Team data is in `~/Library/Application Support/Cloak Proxy/Teams/<team id>/`.
- When a Mac leaves a team or is removed, it deletes that team's keys and local copies of team data.

## Related

  - [Recovery and start over](https://docs.subcloak.com/cloak-proxy/team/recovery-and-start-over/): Using the kit, and what to do without one.
  - [Invite and approve people](https://docs.subcloak.com/cloak-proxy/team/invite-and-approve/): How a new Mac gets the keys.
  - [Security model](https://docs.subcloak.com/cloak-proxy/team/security-model/): Keys, signatures and the limits.