How macadmins/escrow-buddy works
Project type and purpose
• Escrow Buddy is an open-source macOS authorization plugin (written in Objective-C/Swift) plus packaging scripts and CI workflows. Its purpose is to generate and escrow FileVault personal recovery keys to an MDM server when a Mac lacks one.
File structure
Top-level:
• “Escrow Buddy/” – Xcode project for the authorization plugin.
– EBAuthPlugin.h/.m: plugin entry points.
– Bridging header to mix Obj-C and Swift.
– Mechanisms/EBMechanism.swift & Invoke.swift: the logic that runs during authorization.
– Utility/AuthDBSetup.sh & AuthDBTeardown.sh: shell helpers to manipulate the authorization database.
• scripts/ – packaging tooling.
– build_and_pkg.sh: builds the plugin and creates a .pkg installer.
– pkg/ – payload layout and postinstall script.
– uninstall.sh
• .github/workflows – continuous integration definitions for building on push and PR.
• images/, README.md, LICENSE, CHANGELOG.md
README for additional insights
• Describes the high-level flow: MDM deploys installer, then on next user login the plugin creates a new FileVault key via fdesetup, which is automatically escrowed by the MDM’s FDERecoveryKeyEscrow payload.
• Dependencies: macOS ≥10.14.4, MDM with FileVault key-escrow support.
Main components
a. Developer/CI environment
– Xcode + Swift/Obj-C compiler
– build_and_pkg.sh & GitHub Actions (build_main.yml/build_pr.yml)
– Output: Signed .pkg installer
b. MDM Server
– Hosts the FDERecoveryKeyEscrow profile
– Delivers the Escrow Buddy .pkg to enrolled Macs
c. macOS Client
– Installer .pkg deploys:
• Authorization Plugin bundle (com.netflix.Escrow-Buddy) installed under /Library/…
• Utility scripts (AuthDBSetup/Teardown)
– Authorization Services
• On user login or when triggered by “defaults write … GenerateNewKey” setting
• Plugin (EBAuthPlugin) dispatches Mechanism (EBMechanism, Invoke)
– fdesetup Command
• Generates new FileVault personal recovery key
– MDM escrow endpoint
• The system’s FDERecoveryKeyEscrow payload automatically sends the new key back to the MDM
d. Local Authorization Database
– The plugin uses AuthDBSetup/Teardown to insert its mechanism into the auth chain
Component relationships and data flow
1. CI triggers build_and_pkg.sh → compiles plugin & scripts → creates .pkg
2. MDM deploys the .pkg to macOS clients
3. Admin sets GenerateNewKey preference via MDM-run shell command
4. User logs in → Authorization Services invokes EBAuthPlugin → EBMechanism.swift runs
5. Mechanism runs fdesetup → OS generates recovery key
6. macOS automatically escrows the key to MDM via the installed FDERecoveryKeyEscrow profile
7. Optionally, AuthDBTeardown cleans up the auth configuration
Architectural patterns and principles
• Plugin Architecture: leverages macOS Authorization Services API
• Modular layering:
• Core logic (Swift/Obj-C plugin)
• Utility scripts (bash) for pre/post auth DB changes
• Packaging scripts decoupled from code
• CI pipelines in GitHub Actions
• Separation of concerns: build vs. runtime; client vs. MDM vs. CI
Final advice
– Label every component clearly (include actual file/identifier names where helpful).
– Annotate key technologies (Swift, Objective-C, Bash, GitHub Actions, macOS Authorization Services, fdesetup, MDM API).