Hlín

Signed One-Time Unlock

Problem

A tool that restricts a Mac (a network filter in block mode, a lockdown profile) will sooner or later restrict the wrong thing: the Mac loses the network, the fix needs the network, and the user cannot undo the restriction because the admin deliberately took that away. Admins need a break-glass path. The usual answers are bad: a shared "master password" that leaks and cannot be revoked per person, a local admin switch the user can use any time, or a re-image.

Context & forces

• The unlock must work with the Mac cut off from everything: no server round trip.
• The user (or anyone on the Mac) must not be able to produce a valid code. That includes someone who has the app, its code and every file on the disk.
• Each technician should have their own key, so one departed or leaked key can be removed without touching the others.
• A code must not be reusable on another Mac, or twice, or later.
• A local administrator can change the clock, so time cannot be the only safeguard.

Solution

Use public-key signatures and a challenge. The Mac only ever holds public keys (delivered in the configuration profile, one per technician). The technician holds the private key.

 User's Mac                                   Technician
 ──────────                                   ──────────
 1. makes a one-time request code  ───────▶  (read out over the phone)
    (device tag + random part)
                                              2. signs: request code + minutes
                                                 with their private key
 4. checks signature against every   ◀─────  3. sends back a short code
    listed public key, the request
    code, the age of the request,
    the time limit
 5. opens for N minutes, then closes again

The request code is generated on the Mac and is valid for a few minutes. The technician signs that exact code together with the number of minutes. Because the code was made by this Mac, a signed answer works only there and only once; because the Mac holds no private key, nothing on it can make an answer.

For developers

• Keys: one Ed25519 key pair per technician. The profile lists public keys with a name and an optional expiry date. Removing a key from the profile is real revocation. The expiry date is measured on the Mac's clock, which a local administrator can set back, so it is advisory.
• Request code: a device tag (the first characters of the hardware UUID, so the technician can see which Mac it is) plus random characters, stored with its creation time on a clock that ignores date changes and runs through sleep. The same request is returned until it is used or expires, so a second ask does not invalidate the first.
• Answer: a short prefix and version, the minutes and the signature over request code, minutes and options, in one pasteable string. Refuse on wrong key, wrong request, tampering, expired request, or a duration above the policy maximum.
• State: the unlock end is stored as a point on the monotonic clock plus the boot ID; a reboot ends it. - Effect: the unlock lifts the restriction, including managed denies, for the minutes in the code, and optionally shows the app. Every step goes to the audit log.
• A small command-line tool for technicians generates keys and issues codes and shares the verification code with the app, so both sides are tested against each other.

Consequences

• Break-glass without a server, a shared password or a local admin switch.
• One technician's key can be revoked without affecting the others.
• A code is bound to one Mac and one request, so a leaked code is worthless an hour later.
• The user cannot forge a code even with the full source. The security of the profile channel still matters: whoever can deliver a profile with their own public key can unlock the Mac, so profile installation must stay under MDM control.
• Someone on a phone call must read out about twenty characters and paste about a hundred.
• An unlock is all-or-nothing for its duration; it does not say what the user did meanwhile (the audit log and the connection history do).

Known uses

• Gjallarhorn: the helpdesk unlock for a Mac in block mode. Keys in the profile (UnlockPublicKeys, with name and expiry), a 5-minute request code, a technician tool (gjallarhorn-unlock), a maximum duration (UnlockMaxMinutes), and an unlock that ends at a reboot. The audit log records issued, granted, refused, expired and ended unlocks.

Name

Hlín is the goddess of refuge, who protects those Frigg wants to carry out of danger. The code is a way out of a lockdown that nobody else can open.