Code Signing for macOS: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		> Note: For Apple Notarization requirements for kernel extensions and applications from Mojave 10.14.5 onwards (for kernel extensions from 7 April 2019 and for developers whose first use of their code signing certificate occurred from 7 April 2019) and for all software from Catalina 10.15 onwards that is not distributed via the App Store, see [[Notarization for macOS 10.14.5+]]
2	2
3	3		## Introduction
4	4
5	5		[[Code signing]] ensures both authenticity and integrity of executables that have been downloaded from wide area networks like the Internet. The discussion below applies equally to App Store distribution and distribution outside the App Store.
6	6
7	7		Code signing is required in [[Portal:iOS\|iOS]]. On [[Portal:Mac\|macOS]] 10.7 and later, it enables programs downloaded from the Internet to be opened without any warnings (if they are signed with an Apple-issued certificate) and it is required when using certain functionality (eg APIs used by debuggers; note that in this case a self-signed certificate that is marked as "trusted" suffices). This functionality is performed by Apple's Gatekeeper software.
8	8
9	9		## The evolution of Gatekeeper
10	10
11	11		Gatekeeper, first introduced in Mountain Lion (10.8, 2012), is a Mac security feature that was designed to protect Apple computers from malicious software. Gatekeeper checks applications against the list of apps that Apple has approved for its App Store or have been code signed by developers who have Apple-issued certificates where the application is not offered through the app store. It does not perform any safety checks by itself, other than that the application wasn't changed since the developer signed it, nor does it offer any guarantees about the developer other than that they are paying Apple \$US 99 per year (aka an "Identified Developer").
12	12
13	13		The original Gatekeeper options introduced in Mountain Lion, accessed from Preferences \> Security and Privacy \> General, were:
14	14
15	15		- App Store
16	16		- App Store and Identified Developers
17	17		- Anywhere
18	18
19	19		By choosing the Anywhere option, the user was once able to entirely disable Gatekeeper. The default setting only allowed the launching of applications from the App Store or from a developer who had signed their application with an Apple-issued certificate.
20	20
21	21		When macOS Sierra was released in 2016, Apple made some important changes to Gatekeeper and limited the the Gatekeeper options to:
22	22
23	23		- App Store
24	24		- App Store and Identified Developers
25	25
26	26		However, you can restore the missing Gatekeeper Anywhere' option in Preferences by opening a terminal and executing the command:
27	27
28	28		$ sudo spctl --master-disable
29	29
30	30		which still works up to and including macOS Catalina. The better, as in more secure, alternative was to instead bypass Gatekeeper by opening the application from the right-click context menu or by control clicking on the application. This still triggered the alert dialog but it now contained an Open button to successfully launch the application. This method of bypassing Gatekeeper still works in macOS Catalina, except that on Catalina you need to launch the application a second time with the control-click or right-click to successfully bypass Gatekeeper - the first time you launch the application Gatekeeper cannot be bypassed whether you control-click or right-click or not.
31	31
32	32		### Big Sur and later on Apple M1 ARM64 processors
33	33
34	34		And then Apple changed the game.
35	35
36	36		When Big Sur is running on an Apple M1 (ARM64) processor, all native ARM64 code must be signed or the operating system prevents its execution; and this new Gatekeeper requirement cannot be bypassed by users. Developers can bypass it by running the following command in an Applications \> Utilities \> Terminal window:
37	37
38		-	~~`spctl developer-mode enable-terminal`~~
	38	+	```
	39	+	spctl developer-mode enable-terminal
	40	+	```
39	41
40	42		and then going to System Preferences \> Security & Privacy \> Privacy, scrolling down until you see an entry for "Developer Tools", authenticate and then tick the checkbox next to Terminal.
41	43
42	44		Intel executables being run under Big Sur on an Apple M1 processor via Rosetta 2 can still be run even though they are unsigned using the control-click or right-click method to bypass Gatekeeper.
43	45
44	46		For more details, see: [[macOS Big Sur changes for developers\|Big Sur changes for developers: Code signing - Intel vs M1]].
45	47
46	48		## Gatekeeper Dialogs
47	49
48	50		![](/wiki-images/2/26/Load_security_warning_dmg_leopard_en.png)
49	51
50	52		Simple warning after opening a downloaded application in Leopard.
51	53
52	54		![](/wiki-images/3/31/Load_security_warning_dmg_mavericks_en.png)
53	55
54	56		Default settings are more strict in Mavericks, where they prevent downloaded unsigned apps from being started via double-clicking.
55	57
56	58		![](/wiki-images/2/20/Load_security_warning_mavericks_context_en.png)
57	59
58	60		If the application is launched via context menu in Mavericks a simple warning is displayed similar to that of earlier versions.
59	61
60	62		![](/wiki-images/c/c3/Simple_load_security_warning_mavericks_en.png)
61	63
62	64		Gatekeeper shows a simplified warning, if a code-signed app has been downloaded and launched for the first time. In subsequent launches the program is starts immediately.
63	65
64	66		![](/wiki-images/1/15/Codesigning.png)
65	67
66	68		Overview of code-signing a program written with Lazarus and Free Pascal
67	69
68	70		## Overview
69	71
70	72		The basic steps to sign an application that has been written with Lazarus and/or Free Pascal are:
71	73
72	74		1. Obtain a Developer ID from Apple and install it in your system's key chain.
73	75		2. Note the alphanumeric key of your Developer ID (aka TeamIdentifier).
74	76		3. Sign your application with the codesign command.
75	77		4. Sign your installer pkg with the productsign command.
76	78
77	79		It is not possible to use certificates from third-party providers like Comodo because they will not pass Gatekeeper which requires an Apple developer issued certificate. Also note that you cannot sign Windows applications with the Apple developer certificate (this time you do need a third-party Comodo etc certificate).
78	80
79	81		A macOS application distributed outside the Mac App Store will generally have 3–4 separate layers of signing:
80	82
81	83		- The application itself will be code signed using an application certificate.
82	84		- If the application has an installer, the package file will be signed using an installer certificate.
83	85		- The disk image containing the application or installer will be signed using an application certificate.
84	86		- The disk image will [[Notarization for macOS 10.14.5+\|notarized]], and then the ticket generated by the notary service will be [[Notarization for macOS 10.14.5+\|stapled]] to it.
85	87
86	88		## Gatekeeper requirements
87	89
88	90		- Your application should be standalone with no unacceptable external dependencies. The only acceptable external dependencies are system libraries. All other dependencies should be copied to your MyApp.app bundle folder. Gatekeeper rejects any application that has non-system external dependencies.
89	91
90	92		- All binary files inside MyApp.app should be code signed.
91	93
92	94		- All binary files should be located in standard locations inside the MyApp.app bundle folder. Refer to the table below.
93	95
94	96		\| Location \| Description \|
95	97		\|----\|----\|
96	98		\| Contents \| Top content directory of the bundle \|
97	99		\| Contents/MacOS \| Main executable; helper apps and tools \|
98	100		\| Contents/Frameworks \| Frameworks, dylibs \|
99	101		\| Contents/PlugIns \| Plug-ins, both loadable and extensions \|
100	102		\| Contents/XPCServices \| XPC services \|
101	103		\| Contents/Helpers \| Helper apps and tools \|
102	104		\| Contents/Library/Automator \| Automator actions \|
103	105		\| Contents/Library/Spotlight \| Spotlight importers \|
104	106		\| Contents/Library/LoginItems \| Installable login items \|
105	107		\| Contents/Library/LaunchServices \| Privileged helper tools installed by the ServiceManagement framework \|
106	108
107	109		Standard locations for code inside a bundle
108	110
109	111		Note: No non-binary files should ever be located in the folders specified in the table above.
110	112
111	113		## Using codesign to sign your application
112	114
113	115		1. Sign your application with:
114	116
115	117		``` bash
116	118		codesign -f -o runtime --timestamp -s "Developer ID Application: YOUR NAME (TEAM_ID)" /path/to/bundle.app
117	119		```
118	120
119	121		2. Display basic information about the result of the signing process:
120	122
121	123		``` bash
122	124		codesign -dv -r- /path/to/bundle.app
123	125		```
124	126
125	127		If your application was successfully signed this command will return information similar to this:
126	128
127	129		Executable=/Users/apple/Desktop/your.app/Contents/MacOS/yourappname
128	130		Identifier=org.yourdomain.yourappname
129	131		Format=app bundle with Mach-O thin (x86_64)
130	132		CodeDirectory v=20500 size=101470 flags=0x10000(runtime) hashes=3164+3 location=embedded
131	133		Signature size=9063
132	134		Timestamp=7 Dec 2019 at 18:36:08
133	135		Info.plist entries=16
134	136		TeamIdentifier=<10 alpha numeric digits>
135	137		Runtime Version=10.14.0
136	138		Sealed Resources version=2 rules=13 files=45
137	139		designated => identifier "org.yourdomain.yourappname" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists / and certificate leaf[field.1.2.840.113635.100.6.1.13] / exists */ and certificate leaf[subject.OU] = <10 alpha numeric digits>
138	140
139	141		3. Verify your signature:
140	142
141	143		``` bash
142	144		codesign -vv /path/to/bundle.app
143	145		```
144	146
145	147		If your app was successfully signed this command will return the strings "valid on disk" and "satisfies its Designated Requirement", respectively, after the path to your application.
146	148
147	149		## Using productsign to sign your pkg installer
148	150
149	151		1. Sign your installer pkg file with:
150	152
151	153		``` bash
152	154		productsign --timestamp --sign "Developer ID Installer: YOUR NAME (TEAM_ID)" /path/to/unsigned.pkg /path/to/signed.pkg
153	155		```
154	156
155	157		2. Verify your signature with:
156	158
157	159		``` bash
158	160		spctl -vv --assess --type install /path/to/your.pkg
159	161		```
160	162
161	163		which should yield information similar to this if it was successful:
162	164
163	165		your.pkg: accepted
164	166		source=Developer ID
165	167		origin=Developer ID Installer: YOUR NAME (<10 alpha numeric digits>)
166	168
167	169		## Using codesign to sign your disk image
168	170
169	171		Beginning in macOS 10.11.5, you can apply a code signature to read-only, compressed disk images that you use to distribute content. In this case you do not need to separately sign your application.
170	172
171	173		1. Sign your disk image with:
172	174
173	175		``` bash
174	176		codesign -f -o runtime --timestamp -s "Developer ID Application: YOUR NAME (TEAM_ID)" /path/to/YourImage.dmg
175	177		```
176	178
177	179		2. Verify your signature with:
178	180
179	181		``` bash
180	182		spctl -a -t open --context context:primary-signature -vv /path/to/YourImage.dmg
181	183		```
182	184
183	185		which should yield information similar to this if it was successful:
184	186
185	187		YourImage.dmg: accepted
186	188		source=Developer ID
187	189		origin=Developer ID Application: YOUR NAME (<10 alpha numeric digits>)
188	190
189	191		After 3 February 2020 Apple is fully enforcing notarization for macOS 10.14.5+ (Mojave) with the consequence that the above verification of your disk image will now return information similar to this:
190	192
191	193		YourImage.dmg: rejected
192	194		source=Unnotarized Developer ID
193	195		origin=Developer ID Application: YOUR NAME (<10 alpha numeric digits>)
194	196
195	197		See [[Notarization for macOS 10.14.5+]] for more details.
196	198
197	199		## Updating a signed file
198	200
199	201		Whenever you update a signed file, create a new file. Do not copy a new signed file over an old signed file.
200	202
201	203		Specifically, the code signing information (code directory hash) is hung off the vnode within the kernel, and modifying the file behind that cache will cause problems. You need a new vnode, which means a new file, that is, a new inode. Documented in WWDC 2019 Session 703 All About Notarization - see [slide 65 (PDF)](https://devstreaming-cdn.apple.com/videos/wwdc/2019/703yqvyjv9mi5ur6/703/703_all_about_notarization.pdf).
202	204
203	205		## Ad hoc signing
204	206
205	207		This is especially important on ARM64 M1 Apple processors which require all native code to be validly signed (if only ad hoc) or the operating system will not execute it, instead killing it on launch. To ad hoc sign an application:
206	208
207		-	~~` codesign --force --deep -s - lazarus.app`~~
	209	+	```
	210	+	codesign --force --deep -s - lazarus.app
	211	+	```
208	212
209	213		or to ad hoc sign an executable file:
210	214
211		-	~~` codesign --force -s - lazarus`~~
	215	+	```
	216	+	codesign --force -s - lazarus
	217	+	```
212	218
213	219		A single dash/hyphen on its own for the identity makes it an ad hoc signature with no certificate.
214	220
215	221		You can check the validity of an ad hoc signed executable with:
216	222
217		-	~~` codesign -dv -r- lazarus`~~
	223	+	```
	224	+	codesign -dv -r- lazarus
	225	+	```
218	226
219	227		which should produce output similar to the below:
220	228
221		-	~~`Executable=/Users/trev/lazarus-src/lazarus`\~~
222		-	~~`Identifier=lazarus`\~~
223		-	~~`Format=Mach-O thin (arm64)`\~~
224		-	~~`CodeDirectory v=20400 size=336137 flags=0x2(adhoc) hashes=10498+2 location=embedded`\~~
225		-	~~`Signature=adhoc`\~~
226		-	~~`Info.plist=not bound`\~~
227		-	~~`TeamIdentifier=not set`\~~
228		-	~~`Sealed Resources=none`\~~
229		-	~~`# designated => cdhash H"2e6f474452344d6fa42feee3db14a05c14d595a3"`~~
	229	+	```
	230	+	Executable=/Users/trev/lazarus-src/lazarus
	231	+	Identifier=lazarus
	232	+	Format=Mach-O thin (arm64)
	233	+	CodeDirectory v=20400 size=336137 flags=0x2(adhoc) hashes=10498+2 location=embedded
	234	+	Signature=adhoc
	235	+	Info.plist=not bound
	236	+	TeamIdentifier=not set
	237	+	Sealed Resources=none
	238	+	# designated => cdhash H"2e6f474452344d6fa42feee3db14a05c14d595a3"
	239	+	```
230	240
231	241		In cases where you have compiled the executable yourself, the macOS linker will ad hoc sign the executable for you in which case you need do nothing. You can check the validity with the command above in which case the CodeDirectory output line will indicate that the linker signed the executable with an ad hoc signature as follows::
232	242
233		-	~~` CodeDirectory v=20400 size=336032 flags=0x20002(adhoc,linker-signed) hashes=10498+0 location=embedded`~~
	243	+	```
	244	+	CodeDirectory v=20400 size=336032 flags=0x20002(adhoc,linker-signed) hashes=10498+0 location=embedded
	245	+	```
234	246
235	247		## Code signing an x86_64 binary on an aarch64 machine
236	248
237	249		## How to install certificates on a second computer
238	250
239	251		There are two ways to do this:
240	252
241	253		1. using the Keychain Access application; and
242	254		2. using Xcode.
243	255
244	256		### Using the Keychain Access application
245	257
246	258		- On the first computer which has the certificates, open the Keychain Access application and create a new keychain. Now select your existing login keychain, and then My Certificates. Your certificates should be shown on the right. There should be a disclosure arrow on the left side, and selecting that should reveal your private key. Select each certificate, and copy and paste (do not drag or you'll remove it from your login keychain) it into your new keychain.
247	259
248	260		- Copy the newly created keychain from your first computer to your second computer, open it with the Keychain Access application and copy/paste/drag the certificate to your second computer's login keychain.
249	261
250	262		### Using Xcode
251	263
252	264		- On the first computer which has the certificates, open Xcode and go to Preferences \> Accounts, select your account, select the gear symbol in the bottom left, choose Export Apple ID and Code Signing Assets, and then save the file.
253	265
254	266		- Copy the developer profile file you saved on your first computer to the second computer, open Xcode, go to Preferences \> Accounts, select your account, select the gear symbol in the bottom left, and then choose Import Apple ID and Code Signing Assets.
255	267
256	268		## How to check what certificates are installed
257	269
258	270		Once you have created or imported the certificates on your computer, you can check for their presence by opening an Applications \> Utilities \> Terminal and executing the following command:
259	271
260		-	~~`$ security find-identity -p basic -v`~~
	272	+	```
	273	+	$ security find-identity -p basic -v
	274	+	```
261	275
262	276		This command will list all available certificates on this computer. Make sure that you can see the presence of the Developer ID Application and Developer ID Installer certificates. If you are a member of more than one team, you may see multiple certificates for each team.
263	277
264	278		You can identify the certificates by the hexadecimal number or by the descriptive name, eg "Developer ID Application: Your Name (AB123456DE)"
265	279
266	280		The ten character alpha-numeric code at the end of your name is your Developer Team ID. If you are a member of multiple developer teams, you will have multiple certificates and the team ID will help you distinguish them.
267	281
268	282		## See also
269	283
270	284		- [[macOS Big Sur changes for developers\|Code signing: Intel vs Apple Silicon]]
271	285		- [[Apple Developer Certificates]]
272	286		- [[Notarization for macOS 10.14.5+]]
273	287		- [[Hardened runtime for macOS]]
274	288		- [[Sandboxing for macOS]]
275	289		- [[Signing and Notarization FAQ]]
276	290		- [[macOS Gatekeeper Debugging Tips]]
277	291
278	292		## External links
279	293
280	294		- [Apple Developer portal](https://developer.apple.com/)
281	295		- [Apple: Code Signing Overview](https://developer.apple.com/support/technical/code-signing/)
282	296		- [Apple: Code Signing Guide](https://developer.apple.com/library/mac/documentation/Security/Conceptual/CodeSigningGuide/)
283	297		- [Apple: TN2206 - macOS Code Signing In Depth](https://developer.apple.com/library/archive/technotes/tn2206/_index.html)
284	298		- [Apple: Code signing x86_64 binaries on aarch64](https://developer.apple.com/forums/thread/673323).
285	299
286	300		---
287	301		From the Free Pascal wiki, page "Code Signing for macOS", as it stood on 2022-02-13 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history