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

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.

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.

DrahtBot added the label Docs on Sep 26, 2024

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).

Christewart force-pushed on Sep 26, 2024

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.

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.

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?

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.

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

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.

hebasto added the label macOS on Sep 27, 2024

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?

hebasto commented at 10:15 am on September 27, 2024: member

The GUI users may be able to temporarily override their Mac security settings to open it (tested on the same machine for Bitcoin Core.app downloaded from https://bitcoincore.org/bin/bitcoin-core-28.0/test.rc2/bitcoin-28.0rc2-x86_64-apple-darwin.zip).

UPD. Also tested for https://bitcoincore.org/bin/bitcoin-core-28.0/test.rc2/bitcoin-28.0rc2-arm64-apple-darwin.zip.

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>

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.

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!

RandyMcMillan commented at 3:22 am on September 28, 2024: contributor

Concept ACK

itornaza approved

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.

DrahtBot added the label CI failed on Sep 29, 2024

DrahtBot removed the label CI failed on Sep 29, 2024

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

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.

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

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.

DrahtBot requested review from itornaza on Oct 3, 2024

DrahtBot requested review from hebasto on Oct 3, 2024

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

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

Christewart force-pushed on Oct 3, 2024

Christewart requested review from sipa on Oct 3, 2024

Christewart requested review from maflcko on Oct 3, 2024

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

andrewtoth commented at 3:42 pm on October 3, 2024: contributor

reACK 27709f51ee02ed4f8c9c7e1c25c6f16faa0ef08b

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

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.

achow101 merged this on Oct 3, 2024

achow101 closed this on Oct 3, 2024

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

Code Coverage

Reviews