docs: Add instructions on how to self-sign bitcoin-core binaries for macOS #30982

pull Christewart wants to merge 1 commits into bitcoin:master from Christewart:2024-09-26-selfsign-mac-instructions changing 1 files +7 −0
  1. Christewart commented at 3:29 pm on September 26, 2024: contributor

    Related to #15774

    This PR adds instructions to the release notes to tell users how to self sign bitcoin core binaries so they are executable on macOS.

    Tested on

    0Darwin Chriss-MacBook-Pro.local 23.6.0 Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:46 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6031 arm64
    

    These commands do not appear to require ‘phoning home’. I tested these commands when disconnected from a network connection and things worked.

  2. DrahtBot commented at 3:29 pm on September 26, 2024: contributor

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    Code Coverage

    For detailed information about the code coverage, see the test coverage report.

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    ACK andrewtoth, achow101
    Concept ACK hebasto, RandyMcMillan, itornaza, epiccurious

    If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

  3. DrahtBot added the label Docs on Sep 26, 2024
  4. in doc/release-notes-30982.md:1 in bc5e179d25 outdated
    0@@ -0,0 +1,19 @@
    1+How to Upgrade
    


    maflcko commented at 3:37 pm on September 26, 2024:

    I think you’d want to edit the template doc/release-notes-empty-template.md, because snippets are deleted.

    Also, wasn’t the point that this no longer works on macOS Sequoia? Would be nice to test it there.


    Christewart commented at 3:46 pm on September 26, 2024:

    Moved to releae-notes-empty-template.md

    Idk about Sequoia, that OS appears to have shipped 10 days ago. I think its safe to assume the majority of our macOS users will be encountering this issue when trying to use 28.0 (and older versions of bitcoin core).

  5. Christewart force-pushed on Sep 26, 2024
  6. willcl-ark commented at 4:18 pm on September 26, 2024: member
    I think it might be good to also include instructions for signing a downloaded Bitcoin-Qt.app, as I would think that might be what a lot (majority?) of MacOS users are downloading.
  7. Christewart commented at 4:31 pm on September 26, 2024: contributor

    I think it might be good to also include instructions for signing a downloaded Bitcoin-Qt.app, as I would think that might be what a lot (majority?) of MacOS users are downloading.

    I presume this is the GUI? I’m not sure if assuming command line literacy makes sense for that.

  8. willcl-ark commented at 4:34 pm on September 26, 2024: member

    I think it might be good to also include instructions for signing a downloaded Bitcoin-Qt.app, as I would think that might be what a lot (majority?) of MacOS users are downloading.

    I presume this is the GUI? I’m not sure if assuming command line literacy makes sense for that.

    Well, as the app does not work at all on macOS without that it seems better to me to at least provide the required steps, rather than nothing at all?

  9. Christewart commented at 6:47 pm on September 26, 2024: contributor

    I think it might be good to also include instructions for signing a downloaded Bitcoin-Qt.app, as I would think that might be what a lot (majority?) of MacOS users are downloading.

    I presume this is the GUI? I’m not sure if assuming command line literacy makes sense for that.

    Well, as the app does not work at all on macOS without that it seems better to me to at least provide the required steps, rather than nothing at all?

    That makes sense to me, but i’m not user of the .app. I’m unfamiliar with how it works and don’t know how to verify it works. I’ll let someone else contribute that in a different PR.

  10. jarolrod commented at 1:03 am on September 27, 2024: member

    That makes sense to me, but i’m not user of the .app. I’m unfamiliar with how it works and don’t know how to verify it works. I’ll let someone else contribute that in a different PR.

    it’s the same instructions, just for the .app file

  11. hebasto commented at 9:53 am on September 27, 2024: member

    Concept ACK.

    I’ve tested the content of the bitcoin-28.0rc2-x86_64-apple-darwin.tar.gz on macOS (Apple M1) Sequoia 15.0 (24A335).

    The code sign -s - ... command is not required to run downloaded binaries. However, I didn’t test other maOS versions.

  12. hebasto added the label macOS on Sep 27, 2024
  13. fanquake commented at 9:55 am on September 27, 2024: member

    The code sign -s - … command is not required to run downloaded binaries.

    How are the binaries running if they aren’t codesigned at all? If this isn’t an issue why are we adding these instructions?

  14. willcl-ark commented at 10:15 am on September 27, 2024: member

    Concept ACK.

    I’ve tested the content of the bitcoin-28.0rc2-x86_64-apple-darwin.tar.gz on macOS (Apple M1) Sequoia 15.0 (24A335).

    The code sign -s - ... command is not required to run downloaded binaries. However, I didn’t test other maOS versions.

    I certainly see an error and ask for it to be removed, also on 15.0

     0~/Downloads
     1$ tar xzvf bitcoin-28.0rc1-arm64-apple-darwin.tar.gz
     2x bitcoin-28.0rc1/
     3x bitcoin-28.0rc1/bin/
     4x bitcoin-28.0rc1/bin/bitcoin-cli
     5x bitcoin-28.0rc1/bin/bitcoin-qt
     6x bitcoin-28.0rc1/bin/bitcoin-tx
     7x bitcoin-28.0rc1/bin/bitcoin-util
     8x bitcoin-28.0rc1/bin/bitcoin-wallet
     9x bitcoin-28.0rc1/bin/bitcoind
    10x bitcoin-28.0rc1/bin/test_bitcoin
    11x bitcoin-28.0rc1/bitcoin.conf
    12x bitcoin-28.0rc1/share/
    13x bitcoin-28.0rc1/share/man/
    14x bitcoin-28.0rc1/share/man/man1/
    15x bitcoin-28.0rc1/share/man/man1/bitcoin-cli.1
    16x bitcoin-28.0rc1/share/man/man1/bitcoin-qt.1
    17x bitcoin-28.0rc1/share/man/man1/bitcoin-tx.1
    18x bitcoin-28.0rc1/share/man/man1/bitcoin-util.1
    19x bitcoin-28.0rc1/share/man/man1/bitcoin-wallet.1
    20x bitcoin-28.0rc1/share/man/man1/bitcoind.1
    21x bitcoin-28.0rc1/share/rpcauth/
    22x bitcoin-28.0rc1/share/rpcauth/README.md
    23x bitcoin-28.0rc1/share/rpcauth/rpcauth.py
    24
    25~/Downloads
    26$ cd bitcoin-28.0rc1/
    27
    28~/Downloads/bitcoin-28.0rc1
    29$ ./bin/bitcoind --version
    30fish: Job 1, './bin/bitcoind --version' terminated by signal SIGKILL (Forced quit)
    31
    32~/Downloads/bitcoin-28.0rc1
    33 cd bin
    34
    35/Downloads/bitcoin-28.0rc1/bin
    36$ xattr -d com.apple.quarantine bitcoin-cli bitcoin-qt bitcoin-tx bitcoin-util bitcoin-wallet bitcoind test_bitcoin
    37
    38/Downloads/bitcoin-28.0rc1/bin
    39$ ./bitcoind --version
    40fish: Job 1, './bitcoind --version' terminated by signal SIGKILL (Forced quit)
    41
    42/Downloads/bitcoin-28.0rc1/bin
    43 codesign -fs will-clark-codesigning bitcoind
    44
    45/Downloads/bitcoin-28.0rc1/bin
    46$ ./bitcoind --version
    47Bitcoin Core version v28.0.0rc1
    48Copyright (C) 2009-2024 The Bitcoin Core developers
    49
    50Please contribute if you find Bitcoin Core useful. Visit
    51<https://bitcoincore.org/> for further information about the software.
    52The source code is available from <https://github.com/bitcoin/bitcoin>.
    53
    54This is experimental software.
    55Distributed under the MIT software license, see the accompanying file COPYING
    56or <https://opensource.org/licenses/MIT>
    
  15. hebasto commented at 10:18 am on September 27, 2024: member
    My bad! I downloaded binaries for x86_64 arch on arm64 machine. They were using the Rosetta framework.
  16. willcl-ark commented at 10:21 am on September 27, 2024: member

    I downloaded binaries for x86_64 arch on arm64 machine. They were using the Rosetta framework.

    A very sneaky undocumented workaround!

  17. RandyMcMillan commented at 3:22 am on September 28, 2024: contributor
    Concept ACK
  18. itornaza approved
  19. itornaza commented at 2:19 pm on September 28, 2024: contributor

    Concept ACK.

    I can also verify that the steps described in the pr work properly on macOS Sequoia 15.0 (24A335).

    I think it might be good to also include instructions for signing a downloaded Bitcoin-Qt.app, as I would think that might be what a lot (majority?) of macOS users are downloading.

    In my view, users who download the app directly can always be referenced to the standard Apple procedure for installing unknown developer apps https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac. This should not be an issue for them as it is a very common thing. Otherwise, the steps described in the pr can be easily adapted and applied to the Bitcoin Core.app as well.

  20. DrahtBot added the label CI failed on Sep 29, 2024
  21. DrahtBot removed the label CI failed on Sep 29, 2024
  22. achow101 commented at 5:08 pm on September 30, 2024: member
    Should also add this to the current release notes draft: https://github.com/bitcoin-core/bitcoin-devwiki/wiki/28.0-Release-Notes-Draft
  23. epiccurious commented at 12:00 pm on October 1, 2024: contributor

    Concept ACK.

    For added context, I believe the codesign step is only required on arm64 machines. From my testing, the failure doesn’t reproduce on amd64 / x86_64 machines.

  24. epiccurious commented at 12:07 pm on October 1, 2024: contributor

    Looks like there may be a workaround by ~building~ signing the macOS binaries on a macOS host machine.

    Due to the mandatory code signing requirement, before the executable is distributed to end users, it must be signed with the “codesign” utility of macOS, otherwise, it will be immediately killed by kernel on launch.

    Source (can’t find a direct source from Apple): https://github.com/vercel/pkg/issues/1243#issuecomment-873631365

  25. andrewtoth commented at 3:03 pm on October 3, 2024: contributor

    ACK 6c52d6ed8a5b3cdfff9b565c139e35b821647f6b

    Downloaded 27.1 tar and ran ./bitcoin-cli and got the broken popup. Ran the command, ran ./bitcoin-cli and got the help output.

    Ran into this issue before with other apps on macOS, and just ran xattr -cr <filename>. This seems to be a better approach though. Tried just that command and it just shows zsh: killed, so I guess the codesign command is needed.

  26. DrahtBot requested review from itornaza on Oct 3, 2024
  27. DrahtBot requested review from hebasto on Oct 3, 2024
  28. docs: Add instructions on how to self-sign bitcoin-core binaries for macOS
    Remove link and clear up language
    
    Move instructions to release-notes-empty-template.md
    
    Capitalize 'Bitcoin Core' project name
    27709f51ee
  29. in doc/release-notes-empty-template.md:35 in 6c52d6ed8a outdated
    31@@ -32,6 +32,13 @@ Upgrading directly from a version of Bitcoin Core that has reached its EOL is
    32 possible, but it might take some time if the data directory needs to be migrated. Old
    33 wallet versions of Bitcoin Core are generally supported.
    34 
    35+Running bitcoin core binaries on macOS requires self signing.
    


    sipa commented at 3:09 pm on October 3, 2024:
    Please capitalize the project name: Bitcoin Core.

    Christewart commented at 3:31 pm on October 3, 2024:
    Done in 27709f5
  30. Christewart force-pushed on Oct 3, 2024
  31. Christewart requested review from sipa on Oct 3, 2024
  32. Christewart requested review from maflcko on Oct 3, 2024
  33. in doc/release-notes-empty-template.md:37 in 27709f51ee
    31@@ -32,6 +32,13 @@ Upgrading directly from a version of Bitcoin Core that has reached its EOL is
    32 possible, but it might take some time if the data directory needs to be migrated. Old
    33 wallet versions of Bitcoin Core are generally supported.
    34 
    35+Running Bitcoin Core binaries on macOS requires self signing.
    36+```
    37+cd /path/to/bitcoin-core/bin
    


    andrewtoth commented at 3:40 pm on October 3, 2024:

    The path won’t be bitcoin-core, but bitcoin-28.0.

    0cd /path/to/bitcoin-28.0/bin
    

    andrewtoth commented at 3:41 pm on October 3, 2024:
    Oh I see this is the template.

    Christewart commented at 4:11 pm on October 3, 2024:
    I modified the 28.0 release notes to use this path: https://github.com/bitcoin-core/bitcoin-devwiki/wiki/28.0-Release-Notes-Draft
  34. andrewtoth commented at 3:42 pm on October 3, 2024: contributor
    reACK 27709f51ee02ed4f8c9c7e1c25c6f16faa0ef08b
  35. Christewart commented at 4:52 pm on October 3, 2024: contributor
    This seems to be a spurious CI failure as this PR is a docs only change, can someone restart ? https://github.com/bitcoin/bitcoin/actions/runs/11164991068/job/31035622913?pr=30982
  36. achow101 commented at 4:54 pm on October 3, 2024: member

    ACK 27709f51ee02ed4f8c9c7e1c25c6f16faa0ef08b

    Tested on MacOS 15.0 on both x86_64 and arm64. On x86_64, codesign was not needed, but it was needed on arm64. xattr needed for both.

  37. achow101 merged this on Oct 3, 2024
  38. achow101 closed this on Oct 3, 2024


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2024-10-08 16:12 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me