GDB Installation & Code-sign Steps on macOS X

21 Apr 2019 - Guanzhou Hu

TL;DR: Use lldb instead of GNU gdb on macOS >= 10.14 Mojave directly (app verification scheme on newer macOS gets really complicated). If you really wanna make it, the following procedure is what finally worked or me. 如下是在 Mojave 上 GDB debugger 安装使用踩坑后，最终成功的步骤总结。

Prerequisites

macOS X Mojave (10.14.x).
Met problems considering Codesign or “During startup program terminated with signal …” / “unknown load command 0x32”, etc.
Do NOT install gdb in advance. If you already have it (with brew for example), make a clean uninstallation (e.g. brew uninstall --force gdb).

Turn off System Intergrity (Debugging Component)

Shut down your Mac. Turn it on again, hold cmd + R when booting up, until  logo shows up. You should now be booting into Recovery Mode.
Select a language and enter the Recovery Mode UI. In the Menu, select “Utilities” → “Terminal” to open a terminal.
Run the command:
```
 csrutil enable --without debug
```
It won’t turn off system integrity protection entirely, only the Debugging Restriction component is turned off. This should be enough.
Reboot normally.

Type:

csrutil status

in your terminal to see if the Debugging Restriction component is “Disabled”.

Create Codesign Certificate

Open Keychain Access app.
Make sure there aren’t any GDB-related certificates. If you tried some steps before and left some previous (unsuccessful) certificates & keys in login / System keychain, delete them all, then cmd + Q to quit Keychain Access app and reopen for a refresh.
In the Menu, select “Keychain Access” → “Certificate Assistant” → “Create a certificate…“.
Name the certificate gdb-cert, set Identity Type to be “Self Signed Root” (default), and set Certificate Type to be “Code Signing”. Check “Let me override defaults”, then click “Continue” until “Specify a Location For The Certificate” screen.
(Though saving the certificate into System may succeed sometimes, it would probably trigger “Unknown Error: -214,…” error. So here we save it into login, then drag into System.) Do NOT change this option to “System” as suggested in ¹. Instead, leave it as “login”. Click “Continue” to create the certificate.
cmd + Q to quit Keychain Access app and reopen for a refresh.
You may now find the certificate gdb-cert in login keychains. Right-click System keychain → “Unlock …” to unlock it. (Now the lock icon should be unlocked.) Enter login keychain, drag the gdb-cert certificate (NOT the keys!) into System in GUI. The certificate should now be correctly placed in System keychain. cmd + Q to quit Keychain Access app.
Reopen Keychain Access app, double-click the gdb-cert certificate → click out Trust section → set Code Signing to “Always Trust”. Save and cmd + Q to quit Keychain Access app.

Use:

security find-certificate -c gdb-cert | grep System.keychain

to check whether a correct “System.keychain” exists.

Use

security find-certificate -p -c gdb-cert | openssl x509 -checkend 0

to check that it will not expire.

Check

security dump-trust-settings -d

to see if the trust info of your certificate is set.

Install GDB 8.0.1

Newer GDB versions are known to have “During startup program terminated with signal …” problems on macOS X. If you have installed them in advance, uninstall them cleanly. GDB 8.0.1, however, has the “unknown load command 0x32”” issues on Mojave which has not been patched on homebrew. (see ²) So we will need to build it from source, and manually patch the bfd component during the procedure.

Get GDB version 8.0.1 (stable) source from https://ftp.gnu.org/gnu/gdb/. Unzip it.
Modify the source code as guided by this Stackoverflow post ² (2 locations to modify).
Do the normal build procedure:
```
 ./configure && make && make install
```

Check

gdb --version

for your current gdb version, and it should be 8.0.1.

See

which gdb

for the actual thing executed when you type gdb command in shell.

Use

file /path/to/your/gdb  # normally /usr/local/bin/gdb

to check that it really is an executable, not a shell script or alias or something else.

Entitle and Codesign Your GDB

In some arbitrary user location, create an entitlement file gdb-entitlement.xml, whose content is as follows:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
     <key>com.apple.security.cs.debugger</key>
     <true/>
 </dict>
 </plist>
 </pre>

Open terminal at the same location, then do:
```
 sudo codesign --entitlements gdb-entitlement.xml -fs gdb-cert $(which gdb)
```
(You probably need sudo here because your gdb is likely to be in a root location, i.e. /usr/local/bin/). You have now successfully codesigned your GDB.
(Instead of killing taskgated process, which may sometimes fail,) The most reliable thing to do now is to reboot your Mac…
In ~/.gdbinit file (create it if you don’t have it currently), add a line:
```
 set startup-with-shell off
```
to avoid starting up GDB with a new shell.

Use

codesign -vv $(which gdb)

to check the Codesign result.

Use

codesign -d --entitlements - $(which gdb)

to examine the entitlement information.

You should now be able to use GDB Debugger as expected!

References

GDB Wiki: https://sourceware.org/gdb/wiki/PermissionsDarwin. ↩
Stackoverflow: https://stackoverflow.com/questions/52529838/gdb-8-2-cant-recognized-executable-file-on-macos-mojave-10-14. ↩ ↩²

Please comment below anything you wanna say! 😉

	guanzhou.hu (at) wisc.edu
	josehu (at) cs.wisc.edu