Awesome

Firmware Password Manager 2.5

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

Contents

• Download - get the .dmg
• Contact
• System Requirements
• Install
• Uninstall
• Purpose
  • Why set the Firmware Password?
  • Firmware Password Manager
  • How FWPM keeps track of the current password
• Usage
  • Options
  • The configuration file
    • Flags
    • Keyfile
    • Logging
    • Slack
  • The keyfile
  • Security
  • Slack integration
  • nvram string
  • firmwarepasswd
  • Common error messages
  • JAMF Integration
    • JAMF FWPM installation policy
    • JAMF FWPM controller script
      • Editing the keylist variables
      • Editing the configuration file variables
    • JAMF JSS extention attribute
  • Skeleton Key
    • Using Skeleton Key
      • Current State
      • Location
        • Retrieve from JSS Script
        • Fetch from Remote Volume
        • Retrieve from Local Volume
        • Enter Firmware Password
      • Keyfile Hash
      • Status Messages
    • Rebuilding the binary
• Notes
• Update History

Download

Download the latest installer here!

Contact

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

System Requirements

• Python 3.7+ (which you can download here)
• Pexpect 3.3+ (which you can download here)
• Pyinstaller (which you can download here) Only needed if you wish to rebuild either binary.

Install

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

Uninstall

Remove the script/binary/application.

Purpose

Why set the Firmware Password?

In a nutshell, the firmware password in Apple computers prevents non-privileged users from booting from a foreign device.

The firmware password is one of three interlocking methods used to secure Apple computers. The other two are: using strong passwords on user accounts and FileVault to apply full disk encryption (FDE). Strong account passwords are always the first line of defense. FDE effectively scrambles the information written a storage device and renders it unreadable by unauthorized persons. Using all three methods can make a computer unusable should it be lost or stolen.

Depending on the age of computer, removing the firmware password can be easy or incredibly difficult, please refer to the Notes section for more information about removing the password.

Firmware Password Manager

When I began this project there wasn't a solution available for actively 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 that I call the keyfile. 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

Version 2 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.

How FWPM keeps track of the current password

When FWPM successfully sets or changes the firmware password it computes a hash based on the contents of the keyfile and stores the results in nvram. When FWPM is run again on a client it will compare the hash of the current keyfile and the hash stored on the machine, if they are different it will signal the need to change the firmware password to a new value.

A hash can be thought of as the finger print of a file. The goal of a hash function is that no two files will share the same hash value. FWPM uses SHA-256 to generate the hash, or the SHA-2 hash function at a length of 256 bits (32 bytes). Rather than simply hashing the password itself, FWPM hashes the entire keyfile for additional security.

Usage

firmware_password_manager [-h -v] [-c /path/to/configfile]

Options

The configuration file

Here is the default configuration file included with FWPM:

[flags]
use_firmwarepassword: yes
management_string_type: hash
custom_string:
use_reboot_on_exit:

[keyfile]
path: /YourVolume/this/location/example_keyfile.txt
use_obfuscation: No
remote_type: smb
server_path: server_path
username: user_name
password: pass_word

[logging]
use_logging: true
log_path: /tmp

[slack]
use_slack: true
slack_identifier: hostname

slack_info_url: https://hooks.slack.com/services/aaa/bbb/ccc
slack_info_channel: #fwpw_manager_info
slack_info_bot_name: FWPM informational message

slack_error_url: https://hooks.slack.com/services/xxx/yyy/zzz
slack_error_channel: #fwpw_manager_errors
slack_error_bot_name: FWPM error message

The configuration file is broken up into sections roughly approximating the command line flags used in the previous versions.

Flags

Keyfile

Logging

Slack

The keyfile

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 line contains the following: a note string, a colon, and a password string. 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, others are ignored.

Here is the keyfile format:

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.

Security

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.

Slack integration

We make heavy use of Slack in our office. The use_slack option directs FWPM to send informational messages to a slack channel. You simply need to add the URL and channel information for your Slack group to the script. Please see Slack's documentation for additional configuration options: https://api.slack.com/incoming-webhooks

This image shows example FWPM messages in Slack:

The slack_identifier option allows you to select how machines are identified in Slack messages. This feature request was issue #2. These flags are mutually exclusive.

nvram string

To make the most of FWPM, we suggest using the management_string_type 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 custom_string flag 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).

firmwarepasswd

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.

Common error messages

JAMF Integration

FWPM was originally written to work with our unique management system. During the python rewrite, I made an effort to make FWPM independent of any specific administration philosophy and making it easier to integrate into future management solutions. I've included sample scripts for integrating FWPM into JAMF Casper, UNIX and ARD. The source is included in the example scripts folder.

JAMF FWPM installation policy

You will need a policy to ensure that the FWPM binary is installed on each of your client machines.

JAMF FWPM controller script

The controller script directs the automated configuration and launch of FWPM. It contains the new and old firmware passwords, the logic to error check and create an obfuscated keyfile and configuration file, and launches FWPM.

Editing the keylist variables

KEYFILE = {
    'previous': ["oneOldPassword", "AnotherPasswordWeUsed"],
    'new': "myNewFWPW!"
}

Editing the configuration file variables

FWPM_CONFIG = {
    'flags': {
        'use_fwpw': True,
        'management_string_type': 'hash',
        'custom_string': '',
        'use_reboot_on_exit': False,
        'path_to_fw_tool': '',
        'use_test_mode': False,
    },

    'keyfile': {
        'path': '/tmp/current_fwpw.txt',
        'use_obfuscation': True,
    },

    'logging': {
        'use_logging': True,
        'log_path': '/var/log/fwpm_controller.log',
    },

    'slack': {
        'use_slack': True,
        'slack_identifier': 'hostname',

        'slack_info_url': 'https://hooks.slack.com/services/aaaa/bbbbb/cccc',
        'slack_error_url': 'https://hooks.slack.com/services/dddd/eeee/ffff',
    }
}

Please see the previous discussion of the configuration file for info on these values.

JAMF JSS extention attribute

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:

Skeleton Key

Skeleton Key was written to add a GUI to the firmwarepasswd command and Firmware Password Manager and give it mulitple ways to obtain the keylist file. Skeleton Key is designed to be used by technicians with limited experience or access.

Using Skeleton Key

Upon launching Skeleton Key, you must enter a valid administrator password to proceed.

You may also see the following message, press OK to continue.

This is the main interface for Skeleton Key. It can be broken down into three areas: Current State, Modifiers and Status messages.

Current State

The Current State area will tell you if there is a Firmware password in place, and if the keyfile you have given it was read correctly.

Location

The Location area is where you will specify the location of the keyfile you wish to use. You can copy it directly from the JSS FWPM controller script, from a remote file share, from a local disk or entered directly into the application.

Retrieve from JSS Script

This option allows you to specify the JAMF server that contains the FWPM Controller script for your environment. Skelton Key will parse the script and find the keylist automatically.

<img src="img/jamf_fetch_trimmed.png" alt="jamf_fetch_trimmed" style="zoom:50%;" />

Fetch from Remote Volume

This option allows you to specify a remote SMB or AFS file share where your keylist is located. Enter the complete URL, username and password.

<img src="img/remote_fetch_trimmed.png" alt="remote_fetch_trimmed" style="zoom:50%;" />

Retrieve from Local Volume

A standard MacOS X Open File dialog will appear allowing you to navigate to your keyfile.

Enter Firmware Password

This option allows you to directly enter the current or new firmware password of the machine.

Keyfile hash

When a keyfile is read successfully into memory, the hash will appear here. The hash is used in the JAMF Smart Group, to tell which machines are up to date and which need to be updated.

Status Messages

Any informational or error messages will appear in this location.

Rebuilding the binary

I use pyinstaller to build the binary. As long as you maintain the file structure, you should be able to rebuild the binary with the following command: pyinstaller --onefile skeleton_key.py

Notes

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

Only Apple Retail Stores or Apple Authorized Service Providers can unlock the following Mac models when protected by a firmware password:

• iMac (Mid 2011 and later)
• iMac Pro (2017)
• MacBook (Retina, 12-inch, Early 2015 and later)
• MacBook Air (Late 2010 and later)
• MacBook Pro (Early 2011 and later)
• Mac mini (Mid 2011 and later)
• Mac Pro (Late 2013)

If you can't remember your firmware password or passcode, schedule an in-person service appointment with an Apple Store or Apple Authorized Service Provider. Bring your Mac to the appointment, and bring your original receipt or invoice as proof of purchase.

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.

Update History