Index: lldb/docs/code-signing.txt =================================================================== --- lldb/docs/code-signing.txt +++ /dev/null @@ -1,69 +0,0 @@ -To use the in-tree debug server on macOS, lldb needs to be code signed. The -Debug, DebugClang and Release builds are set to code sign using a code signing -certificate named "lldb_codesign". This document explains how to set up the -signing certificate. - -Note that it's possible to build and use lldb on macOS without setting up code -signing by using the system's debug server. To configure lldb in this way with -cmake, specify -DLLDB_CODESIGN_IDENTITY=''. - -If you have re-installed a new OS, please delete all old lldb_codesign items -from your keychain. There will be a code signing certification and a public -and private key. Reboot after deleting them. You will also need to delete and -build folders that contained old signed items. The darwin kernel will cache -code signing using the executable's file system node, so you will need to -delete the file so the kernel clears its cache. - -Automatic setup: -- Run scripts/macos-setup-codesign.sh - -Manual setup steps: -- Launch /Applications/Utilities/Keychain Access.app - -- In Keychain Access select the "login" keychain in the "Keychains" - list in the upper left hand corner of the window. - -- Select the following menu item: - - Keychain Access->Certificate Assistant->Create a Certificate... - -- Set the following settings - - Name = lldb_codesign - Identity Type = Self Signed Root - Certificate Type = Code Signing - -- Click Create -- Click Continue -- Click Done -- Click on the "My Certificates" -- Double click on your new lldb_codesign certificate -- Turn down the "Trust" disclosure triangle, scroll to the "Code Signing" trust - pulldown menu and select "Always Trust" and authenticate as needed using your - username and password. -- Drag the new "lldb_codesign" code signing certificate (not the public or private - keys of the same name) from the "login" keychain to the "System" keychain in the - Keychains pane on the left hand side of the main Keychain Access window. This will - move this certificate to the "System" keychain. You'll have to authorize a few - more times, set it to be "Always trusted" when asked. -- Remove "~/Desktop/lldb_codesign.cer" file on your desktop if there is one. -- In the Keychain Access GUI, click and drag "lldb_codesign" in the "System" keychain - onto the desktop. The drag will create a "~/Desktop/lldb_codesign.cer" file used in - the next step. -- Switch to Terminal, and run the following: - -sudo security add-trust -d -r trustRoot -p basic -p codeSign -k /Library/Keychains/System.keychain ~/Desktop/lldb_codesign.cer -rm -f ~/Desktop/lldb_codesign.cer - -- Drag the "lldb_codesign" certificate from the "System" keychain back into the - "login" keychain -- Quit Keychain Access -- Reboot -- Clean by removing all previously creating code signed binaries and rebuild - lldb and you should be able to debug. - -When you build your LLDB for the first time, the Xcode GUI will prompt you for permission -to use the "lldb_codesign" keychain. Be sure to click "Always Allow" on your first -build. From here on out, the "lldb_codesign" will be trusted and you can build from the -command line without having to authorize. Also the first time you debug using a LLDB that -was built with this code signing certificate, you will need to authenticate once. Index: lldb/docs/resources/build.rst =================================================================== --- lldb/docs/resources/build.rst +++ lldb/docs/resources/build.rst @@ -170,6 +170,79 @@ * ``LLDB_CODESIGN_IDENTITY:STRING`` : Determines the codesign identity to use. An empty string means skip building debugserver to avoid codesigning. +**Code-signing the debug server** + +To use the in-tree debug server on macOS, lldb needs to be code signed. The +Debug, DebugClang and Release builds are set to code sign using a code signing +certificate named ``lldb_codesign``. This document explains how to set up the +signing certificate. + +Note that it's possible to build and use lldb on macOS without setting up code +signing by using the system's debug server. To configure lldb in this way with +cmake, specify ``-DLLDB_CODESIGN_IDENTITY=''``. + +If you have re-installed a new OS, please delete all old ``lldb_codesign`` items +from your keychain. There will be a code signing certification and a public +and private key. Reboot after deleting them. You will also need to delete and +build folders that contained old signed items. The darwin kernel will cache +code signing using the executable's file system node, so you will need to +delete the file so the kernel clears its cache. + +*Automatic setup:* + +* Run ``scripts/macos-setup-codesign.sh``. + +*Manual setup steps:* + +* Launch ``/Applications/Utilities/Keychain Access.app``. + +* In Keychain Access select the ``login`` keychain in the ``Keychains`` + list in the upper left hand corner of the window. + +* Select the following menu item: ``Keychain Access->Certificate Assistant->Create a Certificate...``. + +* Set the following settings: + + * Name = ``lldb_codesign`` + * Identity Type = Self Signed Root + * Certificate Type = Code Signing + +* Click Create. +* Click Continue. +* Click Done. +* Click on the ``My Certificates``. +* Double click on your new lldb_codesign certificate. +* Turn down the ``Trust`` disclosure triangle, scroll to the ``Code Signing`` trust + pulldown menu and select ``Always Trust`` and authenticate as needed using your + username and password. +* Drag the new ``lldb_codesign`` code signing certificate (not the public or private + keys of the same name) from the ``login`` keychain to the ``System`` keychain in the + Keychains pane on the left hand side of the main Keychain Access window. This will + move this certificate to the ``System`` keychain. You'll have to authorize a few + more times, set it to be ``Always trusted`` when asked. +* Remove ``~/Desktop/lldb_codesign.cer`` file on your desktop if there is one. +* In the Keychain Access GUI, click and drag ``lldb_codesign`` in the ``System`` keychain + onto the desktop. The drag will create a ``~/Desktop/lldb_codesign.cer`` file used in + the next step. +* Switch to Terminal, and run the following: + + * ``sudo security add-trust -d -r trustRoot -p basic -p codeSign -k /Library/Keychains/System.keychain ~/Desktop/lldb_codesign.cer`` + + * ``rm -f ~/Desktop/lldb_codesign.cer`` + +- Drag the ``lldb_codesign`` certificate from the ``System`` keychain back into the + ``login`` keychain. +- Quit Keychain Access. +- Reboot. +- Clean by removing all previously creating code signed binaries and rebuild + lldb and you should be able to debug. + +When you build your LLDB for the first time, the Xcode GUI will prompt you for permission +to use the ``lldb_codesign`` keychain. Be sure to click ``Always Allow`` on your first +build. From here on out, the ``lldb_codesign`` will be trusted and you can build from the +command line without having to authorize. Also the first time you debug using a LLDB that +was built with this code signing certificate, you will need to authenticate once. + Building LLDB on Linux, FreeBSD and NetBSD ------------------------------------------