A Python script to help Macintosh administrators manage the firmware passwords of their computers.

• Download - get the .dmg
• Contact
• System Requirements
• Install
• Uninstall
• Purpose
• Usage
  • Options
  • The keyfile
  • Security
  • Example
  • Slack integration
  • JAMF JSS extention attribute
  • nvram
  • firmwarepasswd
  • Error messages
• Notes
• Update History

Download the latest installer here!

If you have any comments, questions, or other input, either file an issue or send us an email. Thanks!

• Python 2.7+ (which you can download here)
• Pexpect 3.3+ (which you can download here)
• Management Tools - version 1.6.0 or greater

Place the script in a root-executable location. We use /usr/local/sbin/. Make sure it is executable.

Remove the script.

Version 2.0 represents a complete rewrite of Firmware Password Manager (FWPM). The previous version, a shell script, always felt brittle to me. The new version is written in Python. I also focused on utilizing firmwarepasswd, rather than the outdated setregproptool.

When I began this project there wasn't a solution available for managing firmware passwords, other than the "set-it-and-forget-it" method. This approach seems error-prone and difficult to maintain beyond more than a small handful of machines. My solution centers on maintaining a single list of current and formerly used passwords. This approach allows the administrator to easily bring any number of machines up to the current password, and identify those whose firmware passwords aren't in the master list and need additional maintenance.

firmware_password_manager.py will use your keyfile to set a firmware password on a machine with no existing firmware password, attempt to change the existing firmware password to your new password or remove the current password. The script is best used when it can be installed and left on the machine for future use. This allows the admin to then create an installer package containing the keyfile and a postflight action to run FWPM. Or the admin could create a launchagent to run FWPM at every boot

firmware_password_manager.py [-hv] [-#rmn] [-k keyfile] [-t] [-s]

Certain flags are mutually exclusive. The script will refuse to run if more than one of the following flags are used: -remove -management -hash -nostring

The script works with a text document I call the keyfile. It contains the new password, as well as any previously used passwords. Having previously used passwords available allows the script to update machines that may have been missed during previous runs of the script.

The script requires a specific format for the keyfile. Each lines contains the following: a note string, a colon, and a password string. No additional colons. I assume the newest passwords will be at the end of the file, and the script will try those first. Only the new note has a special meaning, other are ignored.

Here is the keyfile format:

note:previouspassword <-- other notes are ignored.
#new:currentpassword  <-- hash marks can be used to signal older passwords.
new:newpassword     <-- the new password to be installed.

Here's an example keyfile:

previous:mGoBlue
other:brownCow
#new:short3rPasswd
new:goUtes

Version 1 made use of the current note to designate what was thought to be current password. Version 2 discovers the current password on its own and will ignore this note.

The keyfile contains, of course, incredibly sensitive information. When the script successfully completes or encounters an error, it attempts to securely delete the keyfile from the disk.

firmware_password_manager.py -s -k path/to/keyfile -#

This command will place a hash in nvram, slack informational messages and use the keyfile at path/to/keyfile.

We make heavy use of Slack in our office. The --slack flag directs FWPM to send informational messages to a slack team. FWPM can be easily modified to fit your team. We created a free team to use as a short-term logging service. Setting up the Incoming Webhooks Integration allows you to curl JSON messages to the Slack server from FWPM. Out of the box, FWPM assumes two channels: one for errors and the other for success reports.

FWPM uses four variables to allow interaction with Slack:

You can combine the output into a single channel, setting both the error and info groups to the same channel

Please see Slack's documentation for additional configuration options: https://api.slack.com/incoming-webhooks

This image shows example messages in Slack:

We can leverage the nvram string and smart groups in JAMF Casper to automate the distribution of an updated keyfile package and direct clients to change their firmware passwords. We do this by defining an extension attribute (EA) in the JSS. We've included the script we run in the repository for FWPM 2.0.

The EA script runs during recon and pushes the hash up to the JSS. We then define a smart group that contains any machine not sharing the same hash as the current keyfile. This makes it possible to apply a policy directing those machines to download the new keyfile package and run FWPM.

The following image shows the EA page in the JSS:

This image shows the two possible smart group built using the EA:

Here is how the smart groups are built:

To make the most of FWPM, we suggest using the --hash flag to store the hash of the keyfile used to create the current firmware password. This allows you to use a variety of tools to remotely check the status of the firmware password on a machine. Using this flag the script will create an SHA-2 hash of the new keyfile and store it in non-volitile RAM (nvram) when the password is changed. The hash can then be accessed locally through the terminal or remotely with SSH, ARD or other tool.

The --managment allows you to define any string to place in nvram. You could record the date the password was changed last or a cryptic hint to help you remember the password in the future (not recommended).

Version 2 of FWPM uses Apple's firmwarepasswd tool to make changes to the firmware password. firmwarepasswd was shipped beginning with Mac OS X 10.10 "Yosemite". If you need to manage firmware passwords on OS X prior to 10.10, consider using the previous version of Firmware Password Manager.

If you have forgotten the firmware password for a machine your available options depend upon the age of the machine.

If the machine is a MacBook Air (Late 2010) and later, MacBook Pro (Early 2011) and later, iMac (Mid 2011) and later, and Mac mini (Mid 2011) you will need to contact Apple. Please see these pages for additional info:

https://jamfnation.jamfsoftware.com/discussion.html?id=5474 http://www.ernieflores.net/osx-page-5/recovering-a-lost-firmware-password/

If you have an earlier machine, it's much easier:

1. Shutdown the machine. Remove the battery, if possible.
2. Change the configuration of RAM by removing a module.
3. Restart the machine and zap the PRAM 3 times. (Hold down Option, Command, p and r after you press the power botton, and wait for three restarts)
4. Shut the machine down and remove the battery, if possible.
5. Reinstall the RAM module.
6. Restart and the firmware password should be removed.

Thank you to macmule for http://macmule.com/2014/05/11/ea-check-efi-password-state/, which helped me get things working in version 1.