This directory contains Python modules that modify the Chrome application bundle for various release channels, sign the resulting bundle, package it into .dmg
/.pkg
files for distribution, and sign those resulting .dmg
/.pkg
files.
Signing requires a statically linked build (i.e. is_component_build = false
), which you can set up in a new GN out directory with the following args:
is_debug = false is_component_build = false
The scripts are invoked using the driver located at //chrome/installer/mac/sign_chrome.py
. In order to sign a binary, a signing identity is required. Googlers can use the internal development identity; otherwise you must supply your own. Note that a self-signed identity is incompatible with the library validation signing option that Chrome uses.
A sample invocation to use the internal Google development identity during development would be:
$ ninja -C out/release chrome chrome/installer/mac $ ./out/release/Chromium\ Packaging/sign_chrome.py --input out/release --output out/release/signed --identity 'Google Development' --development --disable-packaging
The --disable-packaging
flag skips the creation of DMG and PKG files, which speeds up the signing process when one is only interested in a signed .app bundle. The --development
flag skips over code signing requirements and checks that do not work without the official Google signing identity, and it injects the com.apple.security.get-task-allow
that lets the app be debugged.
The above section speaks of the --identity
parameter to sign_chrome.py
, and how the normal development identity will do, and how a self-signed identity will not work. However, the identity used for Installer (.pkg) files is different.
Installer files require a special Installer Package Signing Certificate, which is different than a normal certificate in that it has a special Extended Key Usage extension.
For the normal identity, Apple provides both a development and a deployment certificate, and while the deployment certificate can be (and should be) carefully guarded, the development certificate can be more widely used by the development team. However, Apple provides only a deployment installer certificate. For development purposes, you must self-sign your own.
Directions on how to create a self-signed certificate with the special Extended Key Usage extension for installer use can be found on security.stackexchange.
You will need to explicitly mark the certificate as trusted. This can be done with sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain my_installer_cert.crt
. Be sure that sudo security -v find-identity
lists this new certificate as a valid identity.
There are slight differences between the official Google Chrome signed build and a development-signed Chromium build. Specifically, the entitlements will vary because the default chrome/app/app-entitlements.plist omits specific entitlements that are tied to the official Google signing identity.
In addition, the Chromium code sign config only produces one Distribution to sign just the .app. An is_chrome_branded=true
build produces several Distributions for the official release system.
If you attempt to sign an is_chrome_branded=true
build locally, the app will fail to launch because certain entitlements are tied to the official Google code signing identity/certificate. To test an is_chrome_branded=true
build locally, build with include_branded_entitlements=false
or replace the contents of app-entitlements-chrome.plist
with an empty plist.
MacOS grants applications access to privileged resources using the TCC (Transparency, Consent, and Control) subsystem. TCC records user authorization decisions, in part, based on the code signing identity of the responsible application.
One important point, as discussed in the debugging tips is if Chrome/Chromium is launched as a subprocess of another GUI application (such as Terminal), the parent GUI process – not the browser – is considered the responsible application for TCC's purposes.
An authorization decision can be reset manually using the tccutil(1)
command. For example, this would reset the microphone access permission:
tccutil reset Microphone org.chromium.Chromium
Unfortunately there is not an authoritative list of service names for resetting, but the value All
will remove all decisions. The decisions are recorded in a SQLite database, which can be inspected using the command below. This requires granting the Full Disk Access permission in System Settings to the Terminal or disabling System Integrity Protection.
sqlite3 ~"/Library/Application Support/com.apple.TCC/TCC.db"
The access.service
column's values corresponds to the tccutil reset
service, sans the kTCCService
prefix.
MacOS may itself sign Chromium build binaries when it needs to record a signature for certain OS operations. The signature is not attached to the application bundle, as the signing scripts do, but it is instead recorded in a detached signature database. This happens, e.g. when a network request is filtered by the Application Firewall.
If you get errors saying the build is already signed, before signing the build yourself, this is likely the issue. To fix it:
sudo rm /var/db/DetachedSignatures
The signing
module is thoroughly unit-tested. When making changes to the signing scripts, please be sure to add new tests too. To run the tests, simply run the wrapper script at //chrome/installer/mac/signing/run_mac_signing_tests.py
.
You can pass --coverage
or -c
to show coverage information. To generate a HTML coverage report and Python coverage package is available (via pip install coverage
), run:
coverage3 run -m unittest discover -p '*_test.py' coverage3 html
The code is automatically formatted with YAPF. Run:
git cl format --python