Documentation
¶
Overview ¶
Package replycerts provisions and retains FileVault encryption identities.
Design ¶
Prepare generates an RSA certificate and private key entirely in Go, persists them, then supplies the DER certificate to RotateFileVaultKey. Personal rotations use ReplyEncryptionCertificate; institutional rotations use NewCertificate. No shell command or operating-system certificate tool is used. EscrowProfile prepares an InstallProfile command with a FileVault recovery-key escrow payload referencing its generated certificate in the same profile.
Enrollment identity and command UUID bind each key to its command. Atomic state updates make concurrent retries reuse the same identity and reject conflicting command bodies or externally supplied certificates. New commands receive separate keys. Persistent adapters must encrypt records at rest.
Recipient retrieves the retained key for privileged response processing, even after certificate expiry. Forget is explicit: retain escrow identities while their profiles or encrypted keys remain in use, and retain command identities until all replies are recovered or deliberately abandoned. Automatic expiry must not destroy decryption keys. The reference server prepares certificates before enqueueing through its administrative API. Embedders call Prepare or EscrowProfile before Core.Enqueue.
References ¶
Design decision: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/research/decisions/0054-filevault-encryption-identities.md
Apple rotation certificate fields: https://developer.apple.com/documentation/devicemanagement/rotatefilevaultkeycommand/command-data.dictionary
Apple encrypted result: https://developer.apple.com/documentation/devicemanagement/rotatefilevaultkeyresponse/rotateresult-data.dictionary
Apple escrow payload: https://developer.apple.com/documentation/devicemanagement/fderecoverykeyescrow
macOS 26 bootstrap-token rotation: https://support.apple.com/en-us/124963
Protocol helpers: https://github.com/deploymenttheory/go-apple-dm/blob/main/docs/operations/protocol-helpers.md
Index ¶
- Variables
- type Manager
- func (m *Manager) EscrowProfile(ctx context.Context, id mdm.EnrollmentID, ...) (*mdm.Command, error)
- func (m *Manager) Forget(ctx context.Context, id mdm.EnrollmentID, commandUUID string) error
- func (m *Manager) Prepare(ctx context.Context, id mdm.EnrollmentID, command *mdm.Command) (*mdm.Command, error)
- func (m *Manager) Recipient(ctx context.Context, id mdm.EnrollmentID, commandUUID string) (*x509.Certificate, crypto.Decrypter, error)
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalid = errors.New("replycerts: invalid command or stored identity") ErrConflict = errors.New( "replycerts: command identity or encryption certificate conflicts with workflow", ) )
Errors deliberately omit certificate, password and private-key bytes.
Functions ¶
This section is empty.
Types ¶
type Manager ¶
Manager creates one RSA certificate per command. Concurrent/retried prepares select the same persisted key. New commands get new keys automatically. A certificate is never renewed in place after binding it to a command.
func (*Manager) EscrowProfile ¶
func (m *Manager) EscrowProfile( ctx context.Context, id mdm.EnrollmentID, commandUUID, identifier, location string, ) (*mdm.Command, error)
EscrowProfile prepares an InstallProfile command containing a system-scoped FileVault recovery-key escrow payload and its automatically generated RSA certificate. Retain commandUUID to retrieve the matching Recipient. Repeating the same request preserves the certificate and every payload UUID.
On macOS 26, installing this profile can rotate an existing personal recovery key automatically when a bootstrap token is present. The caller must establish those prerequisites, check for an existing escrow profile, and arrange secure retrieval through SecurityInfo. Removing the profile does not restore a prior recovery key. Keep this binding while the profile or its encrypted keys exist. https://support.apple.com/en-us/124963 https://developer.apple.com/documentation/devicemanagement/fderecoverykeyescrow
func (*Manager) Forget ¶
Forget removes a settled workflow's key. The caller must first save the recovered secret in persistent storage and rule out pending/replayed responses, or deliberately abandon the command. There is intentionally no age-based automatic deletion. For escrow profiles, retain the binding while the profile remains installed or any encrypted recovery key still depends on it, regardless of command status.
func (*Manager) Prepare ¶
func (m *Manager) Prepare( ctx context.Context, id mdm.EnrollmentID, command *mdm.Command, ) (*mdm.Command, error)
Prepare fills ReplyEncryptionCertificate for a personal-key rotation, or NewCertificate for an institutional-key rotation, before queueing. It rejects externally supplied encryption certificates. A retry may include the exact certificate already generated by this workflow. Other commands pass through. The enrollment and command UUID bind the retained key to the intended reply.
func (*Manager) Recipient ¶
func (m *Manager) Recipient( ctx context.Context, id mdm.EnrollmentID, commandUUID string, ) (*x509.Certificate, crypto.Decrypter, error)
Recipient loads the exact retained certificate/key after an authenticated response. Pass them to cms.DecryptEnvelope for EncryptedNewRecoveryKey or the CMS envelope produced by a profile prepared with EscrowProfile. This privileged API must never be exposed as an administrative key export.
Source Files