openwall-com-au / bootunlock Goto Github PK

View Code? Open in Web Editor NEW

48.0 4.0 7.0 154 KB

A helper script that unlocks macOS'es encrypted APFS volumes before login

License: GNU General Public License v3.0

Makefile 0.16% Shell 76.00% XSLT 8.78% Rich Text Format 15.06%

osx macos apfs boot unlock

bootunlock's Introduction

BootUnlock

A helper script that unlocks macOS'es encrypted APFS volumes before login

The idea behind this package was to leverage the standard system tools to overcome the limitation of macOS. A quick search on the Internet showed that similar tools were created obviously by developers who are eager to write something up from scratch. However, good engineering requires critical thinking and if the problem can be addressed using the existing tools, then this is the challenge worth puzzling your head with. The entire package is using bash scripting language only.

To build an macOS package you can either use "make" (if you have Xcode installed) or just run "build/build.sh" (if you do not want to install Xcode). The result will be the same: a package is going to be created in the "out" directory.

Alternatively, if you do not want to build the package yourself, you can grab the premade one from the releases section here.

To install the package just open it in Finder and follow the installation prompts.

Use case

The typical usage scenario is the following:

One adds a dedicated encrypted APFS volume to hold home directories for the normal users on the system (e.g. by going to the Disk Utility application and adding a volume over there as an administrator);
The newly created volume is manually mounted by the administrator;
Then the required home directories need to be moved over to that new volume (use Finder as an administrator and drag and drop the folders, this will ensure that all the necessary permissions and extended attributes are preserved -- you cannot easily copy over a home directory via the Terminal application, unfortunately);
Now, to modify the home directory for the required users, one need to open System Setting (or System Preferences in older macOS versions), find the "Users & Groups" section, and after right-clicking on a user account, select "Advanced Options ...": there the home directory can be changed to point to the new volume;
Finally, this is where BootUnlock comes in: to automatically unlock the newly created volume for home directories upon the user login, install BootUnlock and specify the password for the volume during the installation.

This approach allows you to easily upgrade macOS (or even run different versions of macOS on different APFS volumes), yet have your user data intact and in one place. For example, you may want to trial a new beta of macOS by creating a new APFS volume, installing the beta over there, then attach the volume with home directories to that new installation, and update your account in the beta to use the home directory on that volume: your home will be shared between two versions of macOS with all the settings preserved. There is a slight chance that the new macOS version may make an incompatible change to the preferences which would not be recognised by the older version, but I was running Yosemite, Big Sur, Catalina, and Monterey -- switching between them regularly and did not experience any issues.

bootunlock's People

Contributors

Stargazers

Watchers

Forkers

galaxy4public keychainx netj letranloc monk3i techdragon zer010101

bootunlock's Issues

When do you publish the BootUnlock?

Your Idea ist great, but when i can test your tool?

Greets

Recognise FileVault's rate-limiting

If the user entered incorrect password multiple times during the installation, FileVault will lock the volume for 15 minutes. Currently, BootUnlock is unaware of this and will continue to attempt to unlock the volume. The worst is that even if you try to rollback by rebooting into a different volume where everything was working, the rate-limited volume won't be mounted. We need to recognise the rate-limit, possibly extracting the info for how long we need to wait, and provide some meaningful feedback to the user.

Compatibility tests.

Isn't exactly an issue, but I think it would be interesting to let people know.

I've tested with a clean install of Big Sur and it works fine (using an extra admin account to make the file copy operations and the install).
Updated to Ventura using the admin account, the system works as expected.

Thanks.

macOS Catalina support

BootUnlock package fails to install on macOS Catalina. All steps up to the selection of the encrypted volumes are fine, but once the encrypted volumes are selected (even if it just one) there is no prompt for unlocking password.

Does not work on MacOS Monterey 12.0.1

I tried on iMac M1 with OSX Monterey 12.0.1 and the tool does not seem to work as expected.
I have a user home on an external, APFS encrypted SSD. Hence I wanted to use this tool to get the disk unlocked at boot time and before login.
But after installation I tried to login with that user and it did not work.
So I logged back in with an administrator account and immediately after login I get a prompt asking me to authorize MacOS to use the system keychain. After I enter a username/password I get the drive unlocked.
So it seems Monterey has enforced and limited the access to the system keyring at boot time for APFS volumes.

Contents of /var/log/BootUnlock.log

=== Mon Dec 13 18:50:32 CET 2021 ===
===[ update.sh: Mon Dec 13 18:50:32 CET 2021 ]===
Verifying the specific cryptographic user A16FAAD5-1466-402D-A95E-79BAB41C6BE5 on APFS Volume disk8s1
Passphrase valid
Adding password for volume "Dati Mac" with UUID A16FAAD5-1466-402D-A95E-79BAB41C6BE5 to the System keychain...
=== Mon Dec 13 18:52:40 CET 2021 ===
Trying to unlock volume "Dati Mac" with UUID A16FAAD5-1466-402D-A95E-79BAB41C6BE5 ...
NOTICE: could not find the secret on the System keychain, skipping the volume.

Failure to unlock volumes on attached Apple_RAID

Doesn't seem to work until after a user is logged in. Would love any suggestions/thoughts/help.

No problems:

Building.
Installing.
Adding an encrypted volume pw to the System keychain.
Unlocking and mounting an encrypted volume after a user logs in.

Process to recreate the issue (after install and configuring BootUnlock):

Reboot the system.
Admin "test1" user pw entered at pre-boot login (FileVault boot decryption).
System boots.
Admin "test1" username and pw entered for login. This user's home dir is located on the encrypted external drive (i.e. "/Volumes/Users").
Admin "test1" login fails with a pop-up containing the error 'You are unable to log in to the user account "test1" at this time. Logging in to the account failed because an error occurred.'
Admin "test2" username and pw entered for login. This user's home dir is located on the encrypted boot drive (i.e. "Macintosh HD").
Admin "test2" login succeeds.
From the "test2" account, test logging in as the "test1" user via "ssh [email protected]". Login as "test1" succeeds and test1's HOME is on the encrypted external drive ("/Volumes/Users") -- where it should be.

Basic info:

macOS 10.15.7
Volume "Macintosh HD" is internal, APFS, encrypted
Volume "Users" is external, APFS, encrypted. This volume is physically located on an internal m.2 SSD (via PCIe riser card).
BootUnlock v1.5.0. No errors during installation.
In keychain.app --> System --> Name=Users --> Access Control --> "Always allow access by these applications" includes "BootUnlock" (it's the only entry).

BootUnlock.log (cleared just before reboot and the Process to recreate the issue described above):

[email protected]:/var/log [48] % cat BootUnlock.log
=== Wed Oct 28 11:27:30 PDT 2020 ===
=== Wed Oct 28 11:28:16 PDT 2020 ===
Trying to unlock volume "Users" with UUID 73E6E581-C9A1-4D84-9B99-B831CF1E9EC3 ...
Unlocking any cryptographic user on APFS Volume disk7s3
Unlocked and mounted APFS Volume
=== Wed Oct 28 11:28:24 PDT 2020 ===
=== Wed Oct 28 11:30:13 PDT 2020 ===
Trying to unlock volume "Users" with UUID 73E6E581-C9A1-4D84-9B99-B831CF1E9EC3 ...
Unlocking any cryptographic user on APFS Volume disk7s3
Unlocked and mounted APFS Volume
=== Wed Oct 28 11:30:25 PDT 2020 ===
=== Wed Oct 28 11:30:36 PDT 2020 ===
=== Wed Oct 28 11:41:35 PDT 2020 ===

Messages from syslog:

[email protected]:/var/log [49] % grep BootUnlock /var/log/system.log
/var/log/system.log:Oct 28 11:27:31 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock[5653]): Service exited with abnormal code: 1
/var/log/system.log:Oct 28 11:28:20 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock): Service only ran for 6 seconds. Pushing respawn out by 4 seconds.
/var/log/system.log:Oct 28 11:28:24 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock[370]): Service exited with abnormal code: 1
/var/log/system.log:Oct 28 11:30:27 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock[1607]): Service exited with abnormal code: 1
/var/log/system.log:Oct 28 11:30:35 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock): Service only ran for 9 seconds. Pushing respawn out by 1 seconds.
/var/log/system.log:Oct 28 11:30:36 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock[1815]): Service exited with abnormal code: 1
/var/log/system.log:Oct 28 11:41:36 machine com.apple.xpc.launchd[1] (au.com.openwall.BootUnlock[2349]): Service exited with abnormal code: 1

Manual execution of 'helper.sh' works fine:

[email protected]:/var/log [50] % sudo /Library/PrivilegedHelperTools/au.com.openwall.BootUnlock/helper.sh
=== Wed Oct 28 11:53:59 PDT 2020 ===
Trying to unlock volume "Users" with UUID 73E6E581-C9A1-4D84-9B99-B831CF1E9EC3 ...
Unlocking any cryptographic user on APFS Volume disk7s3
Unlocked and mounted APFS Volume

No way to skip the prompt for a selected encrypted disk

If the user chooses an encrypted disk during the installation, they will be presented with a password dialog. However, despite that there is a "Skip" button on the dialog, the button does not work and the user is left with never ending cycle of error message followed by the prompt.

External volumes are not always mounted at boot

@netj reported that for an external encrypted volume BootUnlock is doing a poor job of reliably mounting such a volume at boot. The root cause for such a behaviour is that BootUnlock hooks in at the boot up sequence and fires just once. However, some external volumes may take time to initialise and be available to the operating system.

A pull-request (#5) has been submitted, but it was just improving a wrong design decision. Instead, BootUnlock is supposed to get triggered on the "mount" event, so we should let the operating system decide when a volume is attached and launch our script.

macOS Ventura

After upgrading to Ventura it doesn't seem to work anymore. I tried reinstalling to no avail. Is there a way I can debug this issue?

Add a check for the presence of `xcrun`

Several users stumbled upon the requirement of xcrun during the installation of the package. This problem can be resolved by running xcode-select --install in the Terminal app, but BootUnlock should handle this automatically for the convenience sake, I think.

Help with Install

Hello - Hope all is well and thank you for working on this. I am running Mac OS 10.14.6 and the installer for 1.1 is giving The Installation failed error. I am not a power user, and barely understand terminal, scripts, etc. Can you assist on this?

In the install log, the first error is here:

020-04-06 20:24:00-07 Blank-iMac-2017 installd[681]: ./postinstall: xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

The files mentioned in the readme, helper.sh, update.sh and the bootunlock executable are in the privileged helpertools folder though.

Installation fails on fresh macOS Sonoma 14

At least on M2 with a fresh install of Sonoma BootUnlock fails to install with no meaningful error message. The reason for the failure is the absence of Xcode Command Line tools. So, some work is needed to check the presence of the tools and if they are not present, request the installation of them.

How to uninstall?

Is there any document to remove this tool?

Installation failed, Mojave

I tried to install is with the BootUnlock 1.1.0 installer downloaded here, and it failed. I don't know enough to fix. What's the problem, and can you fix it? Thank you.
Error log:

Oct 23 00:19:09 Weibens-iMac Installer[3725]: Package Authoring Error: has an unsupported MIME type: image/data
Oct 23 00:19:09 Weibens-iMac Installer[3725]: Package Authoring Error: <background_scaling> has an unsupported MIME type: X-NSObject/NSNumber
Oct 23 00:19:09 Weibens-iMac Installer[3725]: Package Authoring Error: <background_alignment> has an unsupported MIME type: X-NSObject/NSNumber
Oct 23 00:19:09 Weibens-iMac Installer[3725]: Package Authoring Error: has an unsupported MIME type: X-NSObject/NSNumber
Oct 23 00:19:26 Weibens-iMac installd[3686]: PackageKit: ----- Begin install -----
Oct 23 00:19:27 Weibens-iMac installd[3686]: PackageKit: Install Failed: Error Domain=PKInstallErrorDomain Code=112 "An error occurred while running scripts from the package “BootUnlock-1.1.0.pkg”." UserInfo={NSFilePath=./postinstall, NSURL=file:///Users/weiben/Downloads/BootUnlock-1.1.0.pkg#BootUnlock-1.1.0-dist.pkg, PKInstallPackageIdentifier=au.com.openwall.BootUnlock, NSLocalizedDescription=An error occurred while running scripts from the package “BootUnlock-1.1.0.pkg”.} {
NSFilePath = "./postinstall";
NSLocalizedDescription = "An error occurred while running scripts from the package \U201cBootUnlock-1.1.0.pkg\U201d.";
NSURL = "file:///Users/weiben/Downloads/BootUnlock-1.1.0.pkg#BootUnlock-1.1.0-dist.pkg";
PKInstallPackageIdentifier = "au.com.openwall.BootUnlock";
}
Oct 23 00:19:27 Weibens-iMac Installer[3725]: Install failed: The Installer encountered an error that caused the installation to fail. Contact the software manufacturer for assistance.
Oct 23 00:19:27 Weibens-iMac Installer[3725]: Displaying 'Install Failed' UI.
Oct 23 00:19:28 Weibens-iMac Installer[3725]: 'Install Failed' UI displayed message:'The Installer encountered an error that caused the installation to fail. Contact the software manufacturer for assistance.'.

APFSUserAgent Prompt On Login

Hi,

I installed the latest version on my Mac mini running macOS 14.2. I enabled FileVault, created a second encrypted volume on my USB dock and went through the set up. Everything seemed fine but when I log into my original account (the account on the internal SSD) I get the following prompt:

It happens every time, if I enter my login details the drive gets successfully mounted however if I click Deny then the normal decryption prompt shows:

Am I doing something wrong? I have Xcode installed.