· 7 years ago · Nov 22, 2018, 02:10 AM
1CODESIGN(1) BSD General Commands Manual CODESIGN(1)
2
3NAME
4 codesign -- Create and manipulate code signatures
5
6SYNOPSIS
7 codesign -s identity [-i identifier] [-r requirements] [-fv] [path ...]
8 codesign -v [-R requirement] [-v] [path|pid ...]
9 codesign -d [-v] [path|pid ...]
10 codesign -h [-v] [pid ...]
11
12DESCRIPTION
13 The codesign command is used to create, check, and display code signatures, as well as inquire into the
14 dynamic status of signed code in the system.
15
16 codesign requires exactly one operation option to determine what action is to be performed, as well as
17 any number of other options to modify its behavior. It can act on any number of objects per invocation,
18 but performs the same operation on all of them.
19
20 codesign accepts single-character (classic) options, as well as GNU-style long options of the form --name
21 and --name=value. Common options have both forms; less frequent and specialized options have only long
22 form.
23
24OPTIONS
25 The options are as follows:
26
27 --all-architectures
28 When verifying a code signature on code that has a universal ("fat") Mach-O binary, separately
29 verify each architecture contained. This is the default unless overridden with the -a (--archi-
30 tecture) option.
31
32 -a, --architecture architecture
33 When verifying or displaying signatures, explicitly select the Mach-O architecture given. The
34 architecture can be specified either by name (e.g. i386) or by number; if by number, a sub-archi-
35 tecture may be appended separated by a comma. This option applies only to Mach-O binary code and
36 is ignored for other types. If the path uses the Mach-O format and contains no code of the given
37 architecture, the command will fail. The default is to operate on the native host architecture
38 as specified by the local system.
39 Note that when signing, codesign will always sign all architectures contained in a universal
40 Mach-O file.
41
42 --bundle-version version-string
43 When handling versioned bundles such as frameworks, explicitly specify the version to operate on.
44 This must be one of the names in the "Versions" directory of the bundle. If not specified,
45 codesign uses the bundle's default version. Note that most frameworks delivered with the system
46 have only one version, and thus this option is irrelevant for them. There is currently no facil-
47 ity for operating on all versions of a bundle at once.
48
49 -d, --display
50 Display information about the code at the path(s) given. Increasing levels of verbosity produce
51 more output. The format is designed to be moderately easy to parse by simple scripts while still
52 making sense to human eyes. In addition, the -r, --file-list, --extract-certificates, and
53 --entitlements options can be used to retrieve additional information.
54
55 -D, --detached filename
56 When signing, designates that a detached signature should be written to the specified file. The
57 code being signed is not modified and need not be writable. When verifying, designates a file
58 containing a detached signature to be used for verification. Any embedded signature in the code
59 is ignored.
60
61 --deep-verify
62 When verifying a bundle, specifies that any bundles and executables that are contained as helper
63 executables, frameworks, plugins or XPC services will be verified as well.
64
65 --detached-database
66 When signing, specifies that a detached signature should be generated as with the --detached
67 option, but that the resulting signature should be written into a system database, from where it
68 is made automatically available whenever apparently unsigned code is validated on the system.
69 Writing to this system database requires elevated process privileges that are not available to
70 ordinary users.
71
72 -f, --force
73 When signing, causes codesign to replace any existing signature on the path(s) given. Without
74 this option, existing signatures will not be replaced, and the signing operation fails.
75
76 -h, --hosting
77 Constructs and prints the hosting chain of a running program. The pid arguments must denote run-
78 ning code (pids etc.) With verbose options, this also displays the individual dynamic validity
79 status of each element of the hosting chain.
80
81 -i, --identifier identifier
82 During signing, explicitly specify the unique identifier string that is embedded in code signa-
83 tures. If this option is omitted, the identifier is derived from either the Info.plist (if
84 present), or the filename of the executable being signed, possibly modified by the --prefix
85 option. Note that it is a very bad idea to sign multiple programs with the same identifier.
86
87 -o, --options flag,...
88 During signing, specifies a set of option flags to be embedded in the code signature. The value
89 takes the form of a comma-separated list of names (with no spaces). Alternatively, a numeric
90 value can be used to directly specify the option mask (CodeDirectory flag word). See OPTION FLAGS
91 below.
92
93 -P, --pagesize pagesize
94 Indicates the granularity of code signing. Pagesize must be a power of two. Chunks of pagesize
95 bytes are separately signed and can thus be independently verified as needed. As a special case,
96 a pagesize of zero indicates that the entire code should be signed and verified as a single, pos-
97 sibly gigantic page. This option only applies to the main executable and has no effect on the
98 sealing of associated data, including resources.
99
100 -r, --requirements requirements
101 During signing, indicates that internal requirements should be embedded in the code path(s) as
102 specified. See "specifying requirements" below. Defaults will be applied to requirement types
103 that are not explicitly specified; if you want to defeat such a default, specify "never" for that
104 type.
105 During display, indicates where to write the code's internal requirements. Use -r- to write them
106 to standard output.
107
108 -R, --test-requirement requirement
109 During verification, indicates that the path(s) given should be verified against the code
110 requirement specified. If this option is omitted, the code is verified only for internal
111 integrity and against its own designated requirement.
112
113 -s, --sign identity
114 Sign the code at the path(s) given using this identity. See SIGNING IDENTITIES below.
115
116 -v, --verbose
117 Sets (with a numeric value) or increments the verbosity level of output. Without the verbose
118 option, no output is produced upon success, in the classic UNIX style. If no other options
119 request a different action, the first -v encountered will be interpreted as --verify instead (and
120 does not increase verbosity).
121
122 -v, --verify
123 Requests verification of code signatures. If other actions (sign, display, etc.) are also
124 requested, -v is interpreted to mean --verbose.
125
126 --continue
127 Instructs codesign to continue processing path arguments even if processing one fails. If this
128 option is given, exit due to operational errors is deferred until all path arguments have been
129 considered. The exit code will then indicate the most severe failure (or, with equal severity,
130 the first such failure encountered).
131
132 --dryrun
133 During signing, performs almost all signing operations, but does not actually write the result
134 anywhere. Cryptographic signatures are still generated, actually using the given signing identity
135 and triggering any access control checks normally, though the resulting signature is then dis-
136 carded.
137
138 --entitlements path
139 When signing, take the file at the given path and embed its contents in the signature as entitle-
140 ment data. If the data at path does not already begin with a suitable binary ("blob") header, one
141 is attached automatically.
142 When displaying a signature, extract any entitlement data from the signature and write it to the
143 path given. Use "-" to write to standard output. By default, the binary "blob" header is
144 returned intact; prefix the path with a colon ":" to automatically strip it off. If the signa-
145 ture has no entitlement data, nothing is written (this is not an error).
146
147 --extract-certificates prefix
148 When displaying a signature, extract the certificates in the embedded certificate chain and write
149 them to individual files. The prefix argument is appended with numbers 0, 1, ... to form the
150 filenames, which can be relative or absolute. Certificate 0 is the leaf (signing) certificate,
151 and as many files are written as there are certificates in the signature. The files are in ASN.1
152 (DER) form. If prefix is omitted, the default prefix is "codesign" in the current directory.
153
154 --file-list path
155 When signing or displaying a signature, codesign writes to the given path a list of files that
156 may have been modified as part of the signing process. This is useful for installer or patcher
157 programs that need to know what was changed or what files are needed to make up the "signature"
158 of a program. The file given is appended-to, with one line per absolute path written. An argument
159 of "-" (single dash) denotes standard output. Note that the list may be somewhat pessimistic -
160 all files not listed are guaranteed to be unchanged by the signing process, but some of the
161 listed files may not actually have changed. Also note that changes may have been made to
162 extended attributes of these files.
163
164 --ignore-resources
165 During static validation, do not validate the contents of the code's resources. In effect, this
166 will pass validation on code whose resources have been corrupted (or inappropriately signed). On
167 large programs, it will also substantially speed up static validation, since all the resources
168 will not be read into memory. Obviously, the outcome of such a validation should be considered
169 on its merits.
170
171 --keychain filename
172 During signing, only search for the signing identity in the keychain file specified. This can be
173 used to break any matching ties if you have multiple similarly-named identities in several key-
174 chains on the user's search list. Note that the standard keychain search path is still consulted
175 while constructing the certificate chain being embedded in the signature.
176
177 --prefix string
178 If no explicit unique identifier is specified (using the -i option), and if the implicitly gener-
179 ated identifier does not contain any dot (.) characters, then the given string is prefixed to the
180 identifier before use. If the implicit identifier contains a dot, it is used as-is. Typically,
181 this is used to deal with command tools without Info.plists, whose default identifier is simply
182 the command's filename; the conventional prefix used is com.domain. (note that the final dot
183 needs to be explicit).
184
185 --preserve-metadata=list
186 When re-signing code that is already signed, reuse some information from the old signature. If
187 new data is specified explicitly, it is preferred. You still need to specify the -f (--force)
188 option to enable overwriting signatures at all. If this option is absent, any old signature has
189 no effect on the signing process.
190 This option takes a comma-separated list of names, which you may reasonably abbreviate:
191
192 identifier Preserve the signing identifier (--identifier) instead of generating a default
193 identifier.
194
195 entitlements Preserve the entitlement data (--entitlements).
196
197 resource-rules Preserve and reuse the resource rules (--resource-rules).
198
199 requirements Preserve the internal requirements (--requirements option), including any
200 explicit Designated Requirement. Note that all internal requirements are pre-
201 served or regenerated as a whole; you cannot pick and choose individual elements
202 with this option.
203 For historical reasons, this option can be given without a value, which preserves all of these
204 values as presently known. This use is deprecated and will eventually be removed; always specify
205 an explicit list of preserved items.
206
207 --resource-rules filename
208 During signing, this option overrides the default rules for collecting bundle resources to be
209 sealed into the signature. The argument is the path to a property list (plist) file containing
210 resource scanning instructions.
211
212 --timestamp [URL]
213 During signing, requests that a timestamp authority server be contacted to authenticate the time
214 of signing. The server contacted is given by the URL value. If this option is given without a
215 value, a default server provided by Apple is used. Note that this server may not support signa-
216 tures made with identities not furnished by Apple. If the timestamp authority service cannot be
217 contacted over the Internet, or it malfunctions or refuses service, the signing operation will
218 fail.
219 If this option is not given at all, a system-specific default behavior is invoked. This may
220 result in some but not all code signatures being timestamped.
221 The special value none explicitly disables the use of timestamp services.
222
223OPERATION
224 In the first synopsis form, codesign attempts to sign the code objects at the path(s) given, using the
225 identity provided. Internal requirements and entitlements are embedded if requested. Internal require-
226 ments not specified may be assigned suitable default values. Defaulting applies separately to each type
227 of internal requirement. If an identifier is explicitly given, it is sealed into all path(s). Other-
228 wise, each path derives its identifier independently from its Info.plist or pathname. The pagesize can
229 be used to control the granularity of the code hash table. Usually, only specific sizes are acceptable to
230 the verifying agents; this option should be used only in special cases.
231
232 In the second synopsis form, codesign verifies the code signatures on all the path(s) given. The verifi-
233 cation confirms that the code at those path(s) is signed, that the signature is valid, and that all
234 sealed components are unaltered. If a requirement is given, each path is also checked against this
235 requirement (but see DIAGNOSTICS below). If verbose verification is requested, the program is also
236 checked against its own designated requirement, which should never fail for a properly signed program.
237 If a path begins with a decimal digit, it is interpreted as the process id of a running process in the
238 system, and dynamic validation is performed on that process instead. This checks the code's dynamic sta-
239 tus and just enough static data to close the nominal security envelope. Add at least one level of ver-
240 bosity to also perform a full static check.
241
242 In the third synopsis form, codesign displays the contents of the signatures on the path(s) given. More
243 information is displayed as the verbosity level increases. This form may not completely verify the sig-
244 natures on the path(s); though it may perform some verification steps in the process of obtaining infor-
245 mation about the path(s). If the -r path option is given, internal requirements will be extracted from
246 the path(s) and written to path; specify a dash "-" to write to standard output. If the code does not
247 contain an explicit designated requirement, the implied one will be retrieved and written out as a source
248 comment. If the --entitlements path option is given, embedded entitlement data will be extracted like-
249 wise and written to the file specified.
250
251 In the fourth synopsis form, codesign constructs the hosting path for each pid given and writes it, one
252 host per line, to standard output. The hosting path is the chain of code signing hosts starting with the
253 most specific code known to be running, and ending with the root of trust (the kernel). If the --verbose
254 option is given, the dynamic validity status of each host is also displayed, separated from the path by a
255 tab character. Note that hosting chains can at times be constructed for invalid or even unsigned code,
256 and the output of this form of the codesign command should not be taken as a statement of formal code
257 validity. Only codesign --verify can do that; and in fact, formal verification constructs the hosting
258 chain as part of its operation (but does not display it).
259
260SIGNING IDENTITIES
261 To be used for code signing, a digital identity must be stored in a keychain that is on the calling
262 user's keychain search list. All keychain sources are supported if properly configured. In particular,
263 it is possible to sign code with an identity stored on a supported smart card. If your signing identity
264 is stored in a different form, you need to make it available in keychain form to sign code with it.
265 If the --keychain argument is used, identity is only looked-for in the specific keychain given. This is
266 meant to help disambiguate references to identities. Even in that case, the full keychain search list is
267 still consulted for additional certificates needed to complete the signature.
268
269 The identity is first considered as the full name of a keychain identity preference. If such a prefer-
270 ence exists, it directly names the identity used. Otherwise, the identity is located by searching all
271 keychains for a certificate whose subject common name (only) contains the identity string given. If there
272 are multiple matches, the operation fails and no signing is performed; however, an exact match is pre-
273 ferred over a partial match. These comparisons are case sensitive. Multiple instances of the exactly
274 same certificate in multiple keychains are tolerated as harmless.
275
276 If identity consists of exactly forty hexadecimal digits, it is instead interpreted as the SHA-1 hash of
277 the certificate part of the desired identity. In this case, the identity's subject name is not consid-
278 ered.
279
280 Both identity preferences and certificate hashes can be used to identify a particular signing identity
281 regardless of name. Identity preferences are global settings for each user and provide a layer of indi-
282 rection. Certificate hashes are very explicit and local. These choices, combined with what is placed into
283 Xcode project and target build variables and/or script settings, allows for very flexible designation of
284 signing identities.
285
286 If identity is the single letter "-" (dash), ad-hoc signing is performed. Ad-hoc signing does not use an
287 identity at all, and identifies exactly one instance of code. Significant restrictions apply to the use
288 of ad-hoc signed code; consult documentation before using this.
289
290 codesign will attempt to embed the entire certificate chain documenting the signing identity in the code
291 signature it generates, including any intermediate certificates and the anchor certificate. It looks for
292 those in the keychain search list of the user performing the signing operation. If it cannot generate the
293 entire certificate chain, signing may still succeed, but verification may fail if the verifying code does
294 not have an independent source for the missing certificates (from its keychains).
295
296SPECIFYING REQUIREMENTS
297 The requirement(s) arguments (-r and -R) can be given in various forms. A plain text argument is taken to
298 be a path to a file containing the requirement(s). codesign will accept both binary files containing
299 properly compiled requirements code, and source files that are automatically compiled before use. An
300 argument of "-" requests that the requirement(s) are read from standard input. Finally, an argument that
301 begins with an equal sign "=" is taken as a literal requirements source text, and is compiled accordingly
302 for use.
303
304OPTION FLAGS
305 When signing, a set of option flags can be specified to change the behavior of the system when using the
306 signed code. The following flags are recognized by codesign; other flags may exist at the API level. Note
307 that you can specify any valid flags by giving a (single) numeric value instead of a list of option
308 names.
309
310 kill Forces the signed code's kill flag to be set when the code begins execution. Code with the kill
311 flag set will die when it becomes dynamically invalid. It is therefore safe to assume that code
312 marked this way, once validated, will have continue to have a valid identity while alive.
313
314 hard Forces the signed code's hard flag to be set when the code begins execution. The hard flag is a
315 hint to the system that the code prefers to be denied access to resources if gaining such access
316 would invalidate its identity.
317
318 host Marks the code as capable of hosting guest code. You must set this option if you want the code
319 to act as a code signing host, controlling subsidiary ("guest") code. This flag is set automati-
320 cally if you specify an internal guest requirement.
321
322 expires Forces any validation of the code to consider expiration of the certificates involved. Code sig-
323 natures generated with this flag will fail to verify once any of the certificates in the chain
324 has expired, regardless of the intentions of the verifier. Note that this flag does not affect
325 any other checks that may cause signature validation to fail, including checks for certificate
326 revocation.
327
328 Note that code can set the hard and kill flags on itself at any time. The signing options only affect
329 their initial state. Once set by any means, these flags cannot be cleared for the lifetime of the code.
330 Therefore, specifying such flags as signing options guarantees that they will be set whenever the signed
331 code runs.
332
333 If the code being signed has an Info.plist that contains a key named CSFlags, the value of that key is
334 taken as the default value for the options. The value of CSFlags can be a string in the same form as the
335 --options option, or an integer number specifying the absolute numeric value. Note however that while you
336 can abbreviate flag names on the command lines, you must spell them out in the Info.plist.
337
338EXAMPLES
339 To sign application Terminal.app with a signing identity named "authority":
340 codesign -s authority Terminal.app
341
342 To sign the command-line tool "helper" with the same identity, overwriting any existing signature, using
343 the signing identifier "com.mycorp.helper", and embedding a custom designated requirement
344 codesign -f -s authority --prefix=com.mycorp. -r="designated => anchor /tmp/foo" helper
345
346 To verify the signature on Terminal.app and produce some verbose output:
347 codesign --verify --verbose Terminal.app
348
349 To verify the dynamic validity of process 666:
350 codesign --verify 666
351
352 To display all information about Terminal.app's code signature:
353 codesign --display --verbose=4 Terminal.app
354
355 To extract the internal requirements from Terminal.app to standard output:
356 codesign --display -r- Terminal.app
357
358DIAGNOSTICS
359 codesign exits 0 if all operations succeed. This indicates that all codes were signed, or all codes veri-
360 fied properly as requested. If a signing or verification operation fails, the exit code is 1. Exit code 2
361 indicates invalid arguments or parameters. Exit code 3 indicates that during verification, all path(s)
362 were properly signed but at least one of them failed to satisfy the requirement specified with the -R
363 option.
364
365 For verification, all path arguments are always investigated before the program exits. For all other
366 operations, the program exits upon the first error encountered, and any further path arguments are
367 ignored, unless the --continue option was specified, in which case codesign will defer the failure exit
368 until after it has attempted to process all path arguments in turn.
369
370SIGNING ATOMICITY
371 When a signing operation fails for a particular code, the code may already have been modified in certain
372 ways by adding requisite signature data. Such information will not change the operation of the code, and
373 the code will not be considered signed even with these pieces in place. You may repeat the signing opera-
374 tion without difficulty. Note however that a previous valid signature may have been effectively
375 destroyed if you specified the -f option.
376 If you require atomicity of signing stricter than provided by codesign, you need to make an explicit copy
377 of your code and sign that.
378
379FILES
380 /var/db/DetachedSignatures System-wide database of detached code signatures for unsigned code.
381
382SEE ALSO
383 csreq(1) xcodebuild(1)
384
385HISTORY
386 The codesign command first appeared in Mac OS 10.5.0 (Leopard).
387
388BUGS
389 Some options only apply to particular operations, and codesign ignores them (without complaining) if you
390 specify them for an operation for which they have no meaning.
391
392 The --preserve-metadata option used to take no value, and varied across releases in what exactly it pre-
393 served. The ensuing confusion is still with you if you need to make backward-compatible scripts.
394
395 The dual meaning of the -v option, indicating either verbosity or verification, confuses some people. If
396 you find it confusing, use the unambiguous long forms --verbose and --verify instead.
397
398NOTES
399 The Xcode build system invokes codesign automatically if the CODE_SIGN_IDENTITY build variable is set.
400 You can express any combination of codesign options with additional build variables there.
401
402 codesign has several operations and options that are purposely left undocumented in this manual page
403 because they are either experimental (and subject to change at any time), or unadvised to the unwary.
404 The interminably curious are referred to the published source code.
405
406BSD May 7, 2011 BSD