1.Dd May 7, 2011 2.Dt CODESIGN 1 3.Os 4.Sh NAME 5.Nm codesign 6.Nd Create and manipulate code signatures 7.Sh SYNOPSIS 8.\" sign code (-s) 9.Nm 10.Ar -s identity 11.Op -i identifier 12.Op -r requirements 13.Op Fl fv 14.Op Ar path ... 15.\" verify code (-v) 16.Nm 17.Ar -v 18.Op -R requirement 19.Op Fl v 20.Op Ar path|pid ... 21.\" display code signatures (-d) 22.Nm 23.Ar -d 24.Op Fl v 25.Op Ar path|pid ... 26.\" display hosting paths (-h) 27.Nm 28.Ar -h 29.Op Fl v 30.Op Ar pid ... 31.Sh DESCRIPTION 32The 33.Nm 34command is used to create, check, and display code signatures, as well as 35inquire into the dynamic status of signed code in the system. 36.Pp 37.Nm 38requires exactly one 39.Ar operation 40option to determine what action is to be performed, as well as any number of 41other options to modify its behavior. It can act on any number of objects per invocation, 42but performs the same operation on all of them. 43.Pp 44.Nm 45accepts single-character (classic) options, as well as GNU-style long 46options of the form --name and --name=value. Common options have both 47forms; less frequent and specialized options have only long form. 48Note that the form --name value (without equal sign) will not work as expected 49on options with optional values. 50.Pp 51.Sh OPTIONS 52The options are as follows: 53.Bl -tag -width indent 54.It Fl -all-architectures 55When verifying a code signature on code that has a universal ("fat") Mach-O binary, 56separately verify each architecture contained. This is the default unless overridden 57with the -a (--architecture) option. 58.It Fl a, -architecture Ar architecture 59When verifying or displaying signatures, explicitly select the Mach-O architecture 60given. The 61.Ar architecture 62can be specified either by name (e.g. i386) or by number; if by number, a sub-architecture 63may be appended separated by a comma. 64This option applies only to Mach-O binary code and is ignored for other types. 65If the 66.Ar path 67uses the Mach-O format and contains no code of the given architecture, the command will fail. 68The default for verification is --all-architectures, to verify all architectures present. 69The default for display is to report on the native architecture of the host system. 70When signing, 71.Nm 72will always sign all architectures contained in a universal Mach-O file. 73.It Fl -bundle-version Ar version-string 74When handling versioned bundles such as frameworks, explicitly specify the version 75to operate on. This must be one of the names in the "Versions" directory of the bundle. 76If not specified, 77.Nm 78uses the bundle's default version. 79Note that most frameworks delivered with the system have only one version, and thus 80this option is irrelevant for them. 81There is currently no facility for operating on all versions of a bundle at once. 82.It Fl d, -display 83Display information about the code at the path(s) given. Increasing levels 84of verbosity produce more output. 85The format is designed to be moderately easy to parse by simple scripts while still 86making sense to human eyes. 87In addition, the -r, --file-list, --extract-certificates, and --entitlements options can be used to retrieve additional information. 88.It Fl D, -detached Ar filename 89When signing, designates that a detached signature should be written to 90the specified file. The code being signed is not modified and need not be 91writable. 92When verifying, designates a file containing a detached signature to be used 93for verification. Any embedded signature in the code is ignored. 94.It Fl -deep 95When signing a bundle, specifies that nested code content such as helpers, frameworks, 96and plug-ins, should be recursively signed in turn. Beware that all signing options you 97specify will apply, in turn, to such nested content. 98.br 99When verifying a bundle, specifies that any nested code content will be recursively 100verified as to its full content. By default, verification of nested content is limited 101to a shallow investigation that may not detect changes to the nested code. 102.br 103When displaying a signature, specifies that a list of directly nested code should be 104written to the display output. This lists only code directly nested within the subject; 105anything nested indirectly will require recursive application of the 106.Nm 107command. 108.It Fl -detached-database 109When signing, specifies that a detached signature should be generated as with 110the --detached option, but that the resulting signature should be written into a system 111database, from where it is made automatically available whenever apparently unsigned 112code is validated on the system. 113.br 114Writing to this system database requires elevated process privileges that are 115not available to ordinary users. 116.It Fl f, -force 117When signing, causes 118.Nm 119to replace any existing signature on the path(s) given. Without this option, 120existing signatures will not be replaced, and the signing operation fails. 121.It Fl h, -hosting 122Constructs and prints the hosting chain of a running program. The 123.Ar pid 124arguments must denote running code (pids etc.) With verbose options, this also 125displays the individual dynamic validity status of each element of the hosting chain. 126.It Fl i, -identifier Ar identifier 127During signing, explicitly specify the unique identifier string that is embedded 128in code signatures. If this option is omitted, the identifier is derived from 129either the Info.plist (if present), or the filename of the executable being signed, 130possibly modified by the --prefix option. 131It is a \fBvery bad idea\fR to sign different programs with the same identifier. 132.It Fl o, -options Ar flag,... 133During signing, specifies a set of option flags to be embedded in the code 134signature. The value takes the form of a comma-separated list of names (with 135no spaces). Alternatively, a numeric value can be used to directly 136specify the option mask (CodeDirectory flag word). See OPTION FLAGS below. 137.It Fl P, -pagesize Ar pagesize 138Indicates the granularity of code signing. Pagesize must be a power of two. 139Chunks of pagesize bytes are separately signed and can thus be independently verified as needed. 140As a special case, a pagesize of zero 141indicates that the entire code should be signed and verified as a single, 142possibly gigantic page. This option only applies to the main executable and has 143no effect on the sealing of associated data, including resources. 144.It Fl r, -requirements Ar requirements 145During signing, indicates that internal requirements should be embedded in the 146code path(s) as specified. See "specifying requirements" below. 147Defaults will be applied to requirement types that are not explicitly specified; 148if you want to defeat such a default, specify "never" for that type. 149.br 150During display, indicates where to write the code's internal requirements. Use -r- 151to write them to standard output. 152.It Fl R, -test-requirement Ar requirement 153During verification, indicates that the path(s) given should be verified against 154the code requirement specified. If this option is omitted, the code is verified 155only for internal integrity and against its own designated requirement. 156.It Fl s, -sign Ar identity 157Sign the code at the path(s) given using this identity. See SIGNING IDENTITIES below. 158.It Fl v, -verbose 159Sets (with a numeric value) or increments the verbosity level of output. Without 160the verbose option, no output is produced upon success, in the classic UNIX style. 161If no other options request a different action, the first -v encountered will be 162interpreted as --verify instead (and does not increase verbosity). 163.It Fl v, -verify 164Requests verification of code signatures. 165If other actions (sign, display, etc.) are also requested, -v is interpreted 166to mean --verbose. 167.It Fl -continue 168Instructs 169.Nm 170to continue processing path arguments even if processing one fails. 171If this option is given, exit due to operational errors is deferred until 172all path arguments have been considered. The exit code will then indicate 173the most severe failure (or, with equal severity, the first such failure encountered). 174.It Fl -dryrun 175During signing, performs almost all signing operations, but does not actually 176write the result anywhere. Cryptographic signatures are still generated, 177actually using the given signing identity and triggering any access control 178checks normally, though the resulting signature is then discarded. 179.It Fl -entitlements Ar path 180When signing, take the file at the given 181.Ar path 182and embed its contents in the signature as entitlement data. If the data at 183.Ar path 184does not already begin with a suitable binary ("blob") header, one is attached automatically. 185.br 186When displaying a signature, extract any entitlement data from the signature 187and write it to the 188.Ar path 189given. Use "-" to write to standard output. 190By default, the binary "blob" header is returned intact; prefix the path with a colon ":" 191to automatically strip it off. 192If the signature has no entitlement data, 193nothing is written (this is not an error). 194.It Fl -extract-certificates Ar prefix 195When displaying a signature, extract the certificates in the embedded certificate chain 196and write them to individual files. The 197.Ar prefix 198argument is appended with numbers 0, 1, ... to form the filenames, which can be relative 199or absolute. Certificate 0 is the leaf (signing) certificate, and as many files are written 200as there are certificates in the signature. The files are in ASN.1 (DER) form. 201If 202.Ar prefix 203is omitted, the default prefix is "codesign" in the current directory. 204.It Fl -file-list Ar path 205When signing or displaying a signature, 206.Nm 207writes to the given path a list of 208files that may have been modified as part of the signing process. This is useful 209for installer or patcher programs that need to know what was changed or what files 210are needed to make up the "signature" of a program. The file given is appended-to, 211with one line per absolute path written. An argument of "-" (single dash) denotes standard 212output. 213Note that the list may be 214somewhat pessimistic - all files not listed are guaranteed to be unchanged by the 215signing process, but some of the listed files may not actually have changed. 216Also note that changes may have been made to extended attributes of these 217files. 218.It Fl -ignore-resources 219During static validation, do not validate the contents of the code's resources. 220In effect, this will pass validation on code whose resources have been corrupted 221(or inappropriately signed). On large programs, it will also substantially speed 222up static validation, since all the resources will not be read into memory. 223Obviously, the outcome of such a validation should be considered on its merits. 224.It Fl -keychain Ar filename 225During signing, only search for the signing identity in the keychain file 226specified. This can be used to break any matching ties if you have multiple 227similarly-named identities in several keychains on the user's search list. 228Note that the standard keychain search path is still consulted while constructing 229the certificate chain being embedded in the signature. 230.br 231Note that 232.Ar filename 233will not be searched to resolve the signing identity's certificate chain unless it 234is also on the user's keychain search list. 235.It Fl -prefix Ar string 236If no explicit unique identifier is specified (using the -i option), and if 237the implicitly generated identifier does not contain any dot (.) characters, 238then the given string is prefixed to the identifier before use. If the implicit 239identifier contains a dot, it is used as-is. Typically, 240this is used to deal with command tools without Info.plists, whose default 241identifier is simply the command's filename; the conventional prefix used 242is com.domain. (note that the final dot needs to be explicit). 243.It Fl -preserve-metadata=list 244When re-signing code that is already signed, reuse some information from the old signature. 245If new data is specified explicitly, it is preferred. 246You still need to specify the -f (--force) option to enable overwriting signatures at all. 247If this option is absent, any old signature has no effect on the signing process. 248.br 249This option takes a comma-separated list of names, which you may reasonably abbreviate: 250.Bl -tag -width requirements 251.It identifier 252Preserve the signing identifier (--identifier) instead of generating a default identifier. 253.It entitlements 254Preserve the entitlement data (--entitlements). 255.It requirements 256Preserve the internal requirements (--requirements option), including any explicit Designated 257Requirement. Note that all internal requirements are preserved or regenerated as a whole; you 258cannot pick and choose individual elements with this option. 259.El 260For historical reasons, this option can be given without a value, which preserves all 261of these values as presently known. This use is deprecated and will eventually be removed; 262always specify an explicit list of preserved items. 263.It Fl -timestamp Ar [ =URL ] 264During signing, requests that a \fItimestamp authority server\fR 265be contacted to authenticate the time of signing. The server contacted is given by the \fIURL\fR value. 266If this option is given without a value, a default server provided by Apple is used. 267Note that this server may not support signatures made with identities not furnished by Apple. 268If the timestamp authority service cannot be contacted over the Internet, or it malfunctions 269or refuses service, the signing operation will \fBfail\fR. 270.br 271If this option is not given at all, a system-specific default behavior is invoked. 272This may result in some but not all code signatures being timestamped. 273.br 274The special value \fInone\fR explicitly disables the use of timestamp services. 275.El 276.Pp 277.Sh OPERATION 278.\" Signing 279.\" ============================================================================= 280In the first synopsis form, 281.Nm 282attempts to sign the code objects at the 283.Ar path(s) 284given, using the 285.Ar identity 286provided. Internal 287.Ar requirements 288and 289.Ar entitlements 290are embedded if requested. Internal requirements not specified may be assigned suitable 291default values. Defaulting applies separately to each type of internal requirement. 292If an 293.Ar identifier 294is explicitly given, it is sealed into all 295.Ar path(s) . 296Otherwise, each path derives its 297.Ar identifier 298independently from its Info.plist or pathname. 299Code nested within bundle directories 300must already be signed or the signing operation will \fIfail\fP, unless the 301.Fl -deep 302option is given, in which case any unsigned nested code will be recursively signed 303before proceeding, using the same signing options and parameters. If the 304.Fl -force 305option is given, any existing top-level signature is replaced, subject to any 306.Fl -preserve-metadata 307options also present. Combining the 308.Fl -force 309and 310.Fl -deep 311options results in forcible replacement of all signatures within the target bundle. 312.Pp 313.\" Verification 314.\" ============================================================================= 315In the second synopsis form, 316.Nm 317verifies the code signatures on all the 318.Ar path(s) 319given. The verification confirms that the code at those 320.Ar path(s) 321is signed, that the signature is valid, and that all sealed components are 322unaltered. If a 323.Ar requirement 324is given, each 325.Ar path 326is also checked against this requirement (but see DIAGNOSTICS below). 327If verbose verification is requested, the program is also checked against its own 328designated requirement, which should never fail for a properly signed program. 329.Pp 330If a 331.Ar path 332begins with a decimal digit, it is interpreted as the process id of a running 333process in the system, and dynamic validation is performed on that process instead. 334This checks the code's dynamic status and just enough static data to close the 335nominal security envelope. Add at least one level of verbosity to also perform 336a full static check. 337.Pp 338.\" Display/dump 339.\" ============================================================================= 340In the third synopsis form, 341.Nm 342displays the contents of the signatures on the 343.Ar path(s) 344given. More information is displayed as the verbosity level increases. 345This form may not completely verify the signatures 346on the 347.Ar path(s) ; 348though it may perform some verification steps in the process of obtaining information 349about the 350.Ar path(s) . 351If the 352.Ar -r path 353option is given, internal requirements will be extracted from the 354.Ar path(s) 355and written to 356.Ar path ; 357specify a dash "-" to write to standard output. If the code does not contain 358an explicit designated requirement, the implied one will be retrieved and written 359out as a source comment. 360If the 361.Ar --entitlements path 362option is given, embedded entitlement data will be extracted likewise and written to 363the file specified. 364.Pp 365.\" Hosting chain 366.\" ============================================================================= 367In the fourth synopsis form, 368.Nm 369constructs the hosting path for each 370.Ar pid 371given and writes it, one host per line, to standard output. The hosting path is the 372chain of code signing hosts starting with the most specific code known to be running, 373and ending with the root of trust (the kernel). If the 374.Ar --verbose 375option is given, the dynamic validity status of each host is also displayed, separated 376from the path by a tab character. 377Note that hosting chains can at times be constructed for invalid or even unsigned code, 378and the output of this form of the 379.Nm 380command should not be taken as a statement of formal code validity. Only 381.Nm 382.Ar --verify 383can do that; and in fact, formal verification constructs the hosting chain as part of 384its operation (but does not display it). 385.Sh SIGNING IDENTITIES 386To be used for code signing, a digital identity must be stored in a keychain that 387is on the calling user's keychain search list. 388All keychain sources are supported if properly configured. In particular, it is 389possible to sign code with an identity stored on a supported smart card. 390If your signing identity is stored in a different form, you need to make it available 391in keychain form to sign code with it. 392.br 393If the 394.Ar --keychain 395argument is used, 396.Ar identity 397is only looked-for in the 398specific keychain given. This is meant to help disambiguate references to identities. 399Even in that case, the full keychain search list is still 400consulted for additional certificates needed to complete the signature. 401.Pp 402The 403.Ar identity 404is first considered as the full name of a \fBkeychain identity preference\fR. 405If such a preference exists, it directly names the identity used. 406Otherwise, the identity is located by searching 407all keychains for a certificate whose subject \fBcommon name\fR (only) contains the 408.Ar identity 409string given. If there are multiple matches, the operation fails and no signing 410is performed; however, an exact match is preferred over a partial match. 411These comparisons are case sensitive. 412Multiple instances of the exactly same certificate in multiple keychains are tolerated 413as harmless. 414.Pp 415If 416.Ar identity 417consists of exactly forty hexadecimal digits, it is instead 418interpreted as the SHA-1 hash of the certificate part of the desired identity. 419In this case, the identity's subject name is not considered. 420.Pp 421Both \fBidentity preferences\fR and certificate hashes can be used to identify 422a particular signing identity regardless of name. Identity preferences are global 423settings \fIfor each user\fR and provide a layer of indirection. Certificate hashes 424are very explicit and local. These choices, combined with what is placed into Xcode 425project and target build variables and/or script settings, allows for very flexible 426designation of signing identities. 427.Pp 428If 429.Ar identity 430is the single letter "-" (dash), \fBad-hoc signing\fR is performed. 431Ad-hoc signing does not use an identity at all, and identifies exactly one instance 432of code. Significant restrictions apply to the use of ad-hoc signed code; consult 433documentation before using this. 434.Pp 435.Nm 436will attempt to embed the entire certificate chain documenting the signing identity 437in the code signature it generates, including any intermediate certificates and 438the anchor certificate. It looks for those in the keychain search list of the user 439performing the signing operation. If it cannot generate the entire certificate chain, 440signing may still succeed, but verification may fail if the verifying code does not 441have an independent source for the missing certificates (from \fIits\fR keychains). 442.Sh SPECIFYING REQUIREMENTS 443The 444.Ar requirement(s) 445arguments (-r and -R) can be given in various forms. A plain text argument is taken 446to be a path to a file containing the requirement(s). 447.Nm 448will accept both binary files containing properly compiled requirements code, and source files 449that are automatically compiled before use. 450An argument of "-" requests that the requirement(s) are read from standard input. 451Finally, an argument that begins with an equal sign "=" is taken as a literal 452requirements source text, and is compiled accordingly for use. 453.Sh OPTION FLAGS 454When signing, a set of option flags can be specified to change the behavior 455of the system when using the signed code. The following flags are recognized 456by 457.Nm ; 458other flags may exist at the API level. Note that you can specify any valid 459flags by giving a (single) numeric value instead of a list of option names. 460.Bl -tag -width expires 461.It kill 462Forces the signed code's kill flag to be set when the code begins execution. 463Code with the kill flag set will die when it becomes dynamically invalid. It is 464therefore safe to assume that code marked this way, once validated, will have continue 465to have a valid identity while alive. 466.It hard 467Forces the signed code's hard flag to be set when the code begins execution. 468The hard flag is a hint to the system that the code prefers to be denied 469access to resources if gaining such access would invalidate its identity. 470.It host 471Marks the code as capable of hosting guest code. You must set this option 472if you want the code to act as a code signing host, controlling subsidiary 473("guest") code. This flag is set automatically if you specify an internal 474guest requirement. 475.It expires 476Forces any validation of the code to consider expiration of the certificates 477involved. Code signatures generated with this flag will fail to verify once any of 478the certificates in the chain has expired, regardless of the intentions of the 479verifier. Note that this flag does not affect any other checks that may cause 480signature validation to fail, including checks for certificate revocation. 481.It library 482Forces the signed code's library validation flag to be set when the code begins execution. 483The code will only be able to link against system libraries and frameworks, or libraries, frameworks, 484and plug-in bundles with the same team identifier embedded in the code directory. 485Team identifiers are automatically recorded in signatures when signing with suitable Apple-issued signing certificates. 486Note that the flag is not supported for i386 binaries, and only applies to the main executable. 487The flag has no effect when set on frameworks and libraries. 488.El 489.Pp 490Note that code can set the hard and kill flags on itself at any time. The signing 491options only affect their initial state. Once set by any means, these flags 492cannot be cleared for the lifetime of the code. Therefore, specifying such flags 493as signing options guarantees that they will be set whenever the signed code runs. 494.Pp 495If the code being signed has an Info.plist that contains a key named CSFlags, 496the value of that key is taken as the default value for the options. The value 497of CSFlags can be a string in the same form as the --options option, or an 498integer number specifying the absolute numeric value. Note however that while you 499can abbreviate flag names on the command lines, you must spell them out in the Info.plist. 500.\".Sh FILES 501.\".Bl -tag -width /Library/Keychains/System.keychain -compact 502.\".It Pa /Library/Keychains/System.keychain 503.Sh EXAMPLES 504To sign application Terminal.app with a signing identity named "authority": 505.Dl codesign -s authority Terminal.app 506.Pp 507To sign the command-line tool "helper" with the same identity, overwriting 508any existing signature, using the signing identifier "com.mycorp.helper", 509and embedding a custom designated requirement 510.Dl codesign -f -s authority --prefix=com.mycorp. -r="designated => anchor /tmp/foo" helper 511.Pp 512To verify the signature on Terminal.app and produce some verbose output: 513.Dl codesign --verify --verbose Terminal.app 514.Pp 515To verify the dynamic validity of process 666: 516.Dl codesign --verify 666 517.Pp 518To display all information about Terminal.app's code signature: 519.Dl codesign --display --verbose=4 Terminal.app 520.Pp 521To extract the internal requirements from Terminal.app to standard output: 522.Dl codesign --display -r- Terminal.app 523.Sh DIAGNOSTICS 524.Nm 525exits 0 if all operations succeed. This indicates that all codes were 526signed, or all codes verified properly as requested. If a signing or verification 527operation fails, the exit code is 1. Exit code 2 indicates invalid arguments 528or parameters. Exit code 3 indicates that during verification, all path(s) were 529properly signed but at least one of them failed to satisfy the requirement specified 530with the 531.Ar -R 532option. 533.Pp 534For verification, all path arguments are always investigated before the program exits. 535For all other operations, the program exits upon the first error encountered, 536and any further path arguments are ignored, unless the --continue option was 537specified, in which case 538.Nm 539will defer the failure exit until after it has attempted to process all path 540arguments in turn. 541.Sh SIGNING ATOMICITY 542When a signing operation fails for a particular code, the code may already have been modified 543in certain ways by adding requisite signature data. Such information will not 544change the operation of the code, and the code will not be considered signed even with 545these pieces in place. You may repeat the signing operation without difficulty. 546Note however that a previous valid signature may have been effectively destroyed 547if you specified the -f option. 548.br 549If you require atomicity of signing stricter than provided by 550.Nm , 551you need to make an explicit copy of your code and sign that. 552.Sh ENVIRONMENT 553If the CODESIGN_ALLOCATE environment variable is set, it identifies a substitute codesign_allocate 554tool used to allocate space for code signatures in Mach-O binaries. This is used by Xcode SDK 555distributions to provide architectural support for non-native platforms such as iPhones. 556The system will not accept such substitutes unless they are specially signed (by Apple). 557.Sh FILES 558.Bl -tag -width "/var/db/DetachedSignatures" -compact 559.It Pa /var/db/DetachedSignatures 560System-wide database of detached code signatures for unsigned code. 561.El 562.Sh SEE ALSO 563.Xr csreq 1 , 564.Xr xcodebuild 1 , 565.Xr codesign_allocate 1 566.Sh HISTORY 567The 568.Nm 569command first appeared in Mac OS 10.5.0 (Leopard). 570.Sh BUGS 571Some options only apply to particular operations, and 572.Nm 573ignores them (without complaining) 574if you specify them for an operation for which they have no meaning. 575.Pp 576The --preserve-metadata option used to take no value, and varied across releases in what exactly 577it preserved. The ensuing confusion is still with you if you need to make backward-compatible 578scripts. 579.Pp 580The dual meaning of the 581.Ar -v 582option, indicating either verbosity or verification, confuses some people. If you find it confusing, 583use the unambiguous long forms 584.Ar --verbose 585and 586.Ar --verify 587instead. 588.Sh NOTES 589The Xcode build system invokes 590.Nm 591automatically if the CODE_SIGN_IDENTITY build variable is set. 592You can express any combination of 593.Nm 594options with additional build variables there. 595.Pp 596.Nm 597is fundamentally a shell around the code signing APIs, and performs nothing of the underlying work. 598Replacing it with older or newer versions is unlikely to have a useful effect. 599.Pp 600.Nm 601has several operations and options that are purposely left undocumented in this manual page because they 602are either experimental (and subject to change at any time), or unadvised to the unwary. 603The interminably curious are referred to the published source code. 604