Signing gdb on macOS with codesign

codesign-gdb.sh

#!/bin/bash

CERT_ID='gdb-cert' # the name of the certificate used for signing

if ! security find-certificate -c "$CERT_ID" &>/dev/null; then
    echo >&2 "> ❌ certificate($CERT_ID) not found"
    echo "Here is a brief note on how to create one:"
    echo
    echo "1. Open Keychain Access"
    echo "2. Open the menu item: Keychain Access -> Certificate Assistant -> Create a Certificate..."
    echo "3. Choose a name (gdb-cert), set Identity Type to Self Signed Root, set Certificate Type to Code Signing and select the Let me override defaults"
    echo '4. Click several times on Continue until you get to the "Specify a Location For The Certificate screen", then set Keychain to System'
    echo '5. Quit Keychain Access, and run this script again'
    echo
    echo 'Or refer to this: https://sourceware.org/gdb/wiki/PermissionsDarwin'
    exit 1
fi

if ! GDB=$(command -v gdb); then
    echo >&2 "> ❌ gdb not found"
    exit 1
fi
echo "> 🔦 Found gdb: $GDB"

ENTITLEMENTS_XML=/tmp/gdb-entitlements.xml
cat >"$ENTITLEMENTS_XML" <<EOF
<?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>
EOF
echo "> 🔏 Signing"
codesign --entitlements "$ENTITLEMENTS_XML" -fs "$CERT_ID" "$GDB"
expected_entitlements=$(cat "$ENTITLEMENTS_XML")
rm -f "$ENTITLEMENTS_XML"

entitlements=$(codesign -d --entitlements :- "$GDB")
if [ "$entitlements" == "$expected_entitlements" ]; then
    echo "> ✅ Entitlements verified"
else
    printf >&2 "> ❌ Entitlements verification failed!\n‼️ Expected:\n%s\n‼️ Found:\n%s" "$expected_entitlements" "$entitlements"
    exit 1
fi

if codesign -vv "$GDB"; then
    echo "> ✅ Signature verified"
    echo "> ✅ Signing succeeded! You may need to restart for it to work."
else
    echo "> ❌ Signature verification failed!"
fi

macos_gdb.patch

:100644 100644 3bd8d8ce 00000000 M	gdb/darwin-nat.c

diff --git a/gdb/darwin-nat.c b/gdb/darwin-nat.c
index 3bd8d8ce..a35c44c0 100644
--- a/gdb/darwin-nat.c
+++ b/gdb/darwin-nat.c
@@ -1139,7 +1139,7 @@ darwin_nat_target::decode_message (mach_msg_header_t *hdr,
 			      res_pid, wstatus);
 
 	      /* Looks necessary on Leopard and harmless...  */
-	      wait4 (inf->pid, &wstatus, 0, NULL);
+	      wait4 (inf->pid, &wstatus, WNOHANG, NULL);
 
 	      inferior_ptid = ptid_t (inf->pid, 0, 0);
 	      return inferior_ptid;

Problem

This gist tries to help you to solve the following issues while running gdb on macOS.

1. No permission (not signed or signed incorrectly)

> gdb /path/to/something
Starting program: /path/to/something
Unable to find Mach task port for process-id 22280: (os/kern) failure (0x5).
 (please check gdb is codesigned - see taskgated(8))

2. Hangs (a potential bug of gdb on newer version of macOS)

> gdb something
Starting program: /path/to/something
[New Thread 0x1803 of process 22280]
# hangs here

The hanging issue might be fixed by echo 'set startup-with-shell off' >> ~/.gdbinit in simple cases, if it doesn't work, read on.

Solution

For problem 1

Sign gdb with codesign-gdb.sh

bash <(curl -sL https://gist.githubusercontent.com/tevino/8ce1fc3a18dc27afaf34025966c74673/raw/)

For problem 2

If gdb still hangs, you may need a patch in order to make gdb work especially on newer version of macOS(e.g. Catalina) with SIP enabled.

1. Edit brew formula to apply the patch

brew edit gdb

Below the depends_on, add the following:

  patch do
    url "https://gist.githubusercontent.com/tevino/8ce1fc3a18dc27afaf34025966c74673/raw/macos_gdb.patch"
    sha256 "f937c846271c2a7b48922dd693dc6f9423656748d7b8300bf4273227d4d7e29d"
  end

2. Reinstall gdb from source, so that the patch could be applied.

brew reinstall --build-from-source gdb

3. Sign the newly built binary by running codesign-gdb.sh again

Your gdb should work fine now, however you may still encounter error messages like below once in a while, simply try again would pass it.

(gdb) run
Starting program: /path/to/something 
[New Thread 0x1603 of process 41581]
During startup program terminated with signal ?, Unknown signal.

---

Potential upstream bug here: https://sourceware.org/bugzilla/show_bug.cgi?id=24069