Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

CODESIGN(1)               BSD General Commands Manual              CODESIGN(1)

NAME
     codesign -- Create and manipulate code signatures

SYNOPSIS
     codesign -s identity [-i identifier] [-r requirements] [-fv] [path ...]
     codesign -v [-R requirement] [-v] [path|pid ...]
     codesign -d [-v] [path|pid ...]
     codesign -h [-v] [pid ...]

DESCRIPTION
     The codesign command is used to create, check, and display code signatures, as well as inquire into the
     dynamic status of signed code in the system.

     codesign requires exactly one operation option to determine what action is to be performed, as well as
     any number of other options to modify its behavior. It can act on any number of objects per invocation,
     but performs the same operation on all of them.

     codesign accepts single-character (classic) options, as well as GNU-style long options of the form
     --name and --name=value. Common options have both forms; less frequent and specialized options have
     only long form.  Note that the form --name value (without equal sign) will not work as expected on
     options with optional values.

OPTIONS
     The options are as follows:

     --all-architectures
             When verifying a code signature on code that has a universal ("fat") Mach-O binary, separately
             verify each architecture contained. This is the default unless overridden with the -a (--archi-tecture) (--architecture)
             tecture) option.

     -a, --architecture architecture
             When verifying or displaying signatures, explicitly select the Mach-O architecture given. The
             architecture can be specified either by name (e.g. i386) or by number; if by number, a sub-architecture subarchitecture
             architecture may be appended separated by a comma.  This option applies only to Mach-O binary
             code and is ignored for other types.  If the path uses the Mach-O format and contains no code
             of the given architecture, the command will fail.  The default for verification is --all-archi-tectures, --all-architectures,
             tectures, to verify all architectures present.  The default for display is to report on the
             native architecture of the host system.  When signing, codesign will always sign all architec-tures architectures
             tures contained in a universal Mach-O file.

     --bundle-version version-string
             When handling versioned bundles such as frameworks, explicitly specify the version to operate
             on. This must be one of the names in the "Versions" directory of the bundle.  If not specified,
             codesign uses the bundle's default version.  Note that most frameworks delivered with the sys-tem system
             tem have only one version, and thus this option is irrelevant for them.  There is currently no
             facility for operating on all versions of a bundle at once.

     -d, --display
             Display information about the code at the path(s) given. Increasing levels of verbosity produce
             more output.  The format is designed to be moderately easy to parse by simple scripts while
             still making sense to human eyes.  In addition, the -r, --file-list, --extract-certificates,
             and --entitlements options can be used to retrieve additional information.

     -D, --detached filename
             When signing, designates that a detached signature should be written to the specified file. The
             code being signed is not modified and need not be writable.  When verifying, designates a file
             containing a detached signature to be used for verification. Any embedded signature in the code
             is ignored.

     --deep  When signing a bundle, specifies that nested code content such as helpers, frameworks, and
             plug-ins, should be recursively signed in turn. Beware that all signing options you specify
             will apply, in turn, to such nested content.
             When verifying a bundle, specifies that any nested code content will be recursively verified as
             to its full content. By default, verification of nested content is limited to a shallow inves-tigation investigation
             tigation that may not detect changes to the nested code.
             When displaying a signature, specifies that a list of directly nested code should be written to
             the display output. This lists only code directly nested within the subject; anything nested
             indirectly will require recursive application of the codesign command.

     --detached-database
             When signing, specifies that a detached signature should be generated as with the --detached
             option, but that the resulting signature should be written into a system database, from where
             it is made automatically available whenever apparently unsigned code is validated on the sys-tem. system.
             tem.
             Writing to this system database requires elevated process privileges that are not available to
             ordinary users.

     -f, --force
             When signing, causes codesign to replace any existing signature on the path(s) given. Without
             this option, existing signatures will not be replaced, and the signing operation fails.

     -h, --hosting
             Constructs and prints the hosting chain of a running program. The pid arguments must denote
             running code (pids etc.) With verbose options, this also displays the individual dynamic valid-ity validity
             ity status of each element of the hosting chain.

     -i, --identifier identifier
             During signing, explicitly specify the unique identifier string that is embedded in code signa-tures. signatures.
             tures. If this option is omitted, the identifier is derived from either the Info.plist (if
             present), or the filename of the executable being signed, possibly modified by the --prefix
             option.  It is a very bad idea to sign different programs with the same identifier.

     -o, --options flag,...
             During signing, specifies a set of option flags to be embedded in the code signature. The value
             takes the form of a comma-separated list of names (with no spaces). Alternatively, a numeric
             value can be used to directly specify the option mask (CodeDirectory flag word). See OPTION
             FLAGS below.

     -P, --pagesize pagesize
             Indicates the granularity of code signing. Pagesize must be a power of two.  Chunks of pagesize
             bytes are separately signed and can thus be independently verified as needed.  As a special
             case, a pagesize of zero indicates that the entire code should be signed and verified as a sin-gle, single,
             gle, possibly gigantic page. This option only applies to the main executable and has no effect
             on the sealing of associated data, including resources.

     -r, --requirements requirements
             During signing, indicates that internal requirements should be embedded in the code path(s) as
             specified. See "specifying requirements" below.  Defaults will be applied to requirement types
             that are not explicitly specified; if you want to defeat such a default, specify "never" for
             that type.
             During display, indicates where to write the code's internal requirements. Use -r- to write
             them to standard output.

     -R, --test-requirement requirement
             During verification, indicates that the path(s) given should be verified against the code
             requirement specified. If this option is omitted, the code is verified only for internal
             integrity and against its own designated requirement.

     -s, --sign identity
             Sign the code at the path(s) given using this identity. See SIGNING IDENTITIES below.

     -v, --verbose
             Sets (with a numeric value) or increments the verbosity level of output. Without the verbose
             option, no output is produced upon success, in the classic UNIX style.  If no other options
             request a different action, the first -v encountered will be interpreted as --verify instead
             (and does not increase verbosity).

     -v, --verify
             Requests verification of code signatures.  If other actions (sign, display, etc.) are also
             requested, -v is interpreted to mean --verbose.

     --continue
             Instructs codesign to continue processing path arguments even if processing one fails.  If this
             option is given, exit due to operational errors is deferred until all path arguments have been
             considered. The exit code will then indicate the most severe failure (or, with equal severity,
             the first such failure encountered).

     --dryrun
             During signing, performs almost all signing operations, but does not actually write the result
             anywhere. Cryptographic signatures are still generated, actually using the given signing iden-tity identity
             tity and triggering any access control checks normally, though the resulting signature is then
             discarded.

     --entitlements path
             When signing, take the file at the given path and embed its contents in the signature as enti-tlement entitlement
             tlement data. If the data at path does not already begin with a suitable binary ("blob")
             header, one is attached automatically.
             When displaying a signature, extract any entitlement data from the signature and write it to
             the path given. Use "-" to write to standard output.  By default, the binary "blob" header is
             returned intact; prefix the path with a colon ":" to automatically strip it off.  If the signa-ture signature
             ture has no entitlement data, nothing is written (this is not an error).

     --extract-certificates prefix
             When displaying a signature, extract the certificates in the embedded certificate chain and
             write them to individual files. The prefix argument is appended with numbers 0, 1, ... to form
             the filenames, which can be relative or absolute. Certificate 0 is the leaf (signing) certifi-cate, certificate,
             cate, and as many files are written as there are certificates in the signature. The files are
             in ASN.1 (DER) form.  If prefix is omitted, the default prefix is "codesign" in the current
             directory.

     --file-list path
             When signing or displaying a signature, codesign writes to the given path a list of files that
             may have been modified as part of the signing process. This is useful for installer or patcher
             programs that need to know what was changed or what files are needed to make up the "signature"
             of a program. The file given is appended-to, with one line per absolute path written. An argu-ment argument
             ment of "-" (single dash) denotes standard output.  Note that the list may be somewhat pes-simistic pessimistic
             simistic - all files not listed are guaranteed to be unchanged by the signing process, but some
             of the listed files may not actually have changed.  Also note that changes may have been made
             to extended attributes of these files.

     --ignore-resources
             During static validation, do not validate the contents of the code's resources.  In effect,
             this will pass validation on code whose resources have been corrupted (or inappropriately
             signed). On large programs, it will also substantially speed up static validation, since all
             the resources will not be read into memory.  Obviously, the outcome of such a validation should
             be considered on its merits.

     --keychain filename
             During signing, only search for the signing identity in the keychain file specified. This can
             be used to break any matching ties if you have multiple similarly-named identities in several
             keychains on the user's search list.  Note that the standard keychain search path is still con-sulted consulted
             sulted while constructing the certificate chain being embedded in the signature.
             Note that filename will not be searched to resolve the signing identity's certificate chain
             unless it is also on the user's keychain search list.

     --prefix string
             If no explicit unique identifier is specified (using the -i option), and if the implicitly gen-erated generated
             erated identifier does not contain any dot (.) characters, then the given string is prefixed to
             the identifier before use. If the implicit identifier contains a dot, it is used as-is. Typi-cally, Typically,
             cally, this is used to deal with command tools without Info.plists, whose default identifier is
             simply the command's filename; the conventional prefix used is com.domain. (note that the final
             dot needs to be explicit).

     --preserve-metadata=list
             When re-signing code that is already signed, reuse some information from the old signature.  If
             new data is specified explicitly, it is preferred.  You still need to specify the -f (--force)
             option to enable overwriting signatures at all.  If this option is absent, any old signature
             has no effect on the signing process.
             This option takes a comma-separated list of names, which you may reasonably abbreviate:

             identifier      Preserve the signing identifier (--identifier) instead of generating a default
                             identifier.

             entitlements    Preserve the entitlement data (--entitlements).

             resource-rules  Preserve and reuse the resource rules (--resource-rules).

             requirements    Preserve the internal requirements (--requirements option), including any
                             explicit Designated Requirement. Note that all internal requirements are pre-served preserved
                             served or regenerated as a whole; you cannot pick and choose individual ele-ments elements
                             ments with this option.
             For historical reasons, this option can be given without a value, which preserves all of these
             values as presently known. This use is deprecated and will eventually be removed; always spec-ify specify
             ify an explicit list of preserved items.

     --resource-rules filename
             During signing, this option overrides the default rules for identifying and collecting bundle
             resources and nested code to be sealed into the signature. The argument is the path to a prop-erty property
             erty list (plist) file containing scanning and qualification instructions. See the code signing
             documentation for details.

     --timestamp [=URL]
             During signing, requests that a timestamp authority server be contacted to authenticate the
             time of signing. The server contacted is given by the URL value.  If this option is given with-out without
             out a value, a default server provided by Apple is used.  Note that this server may not support
             signatures made with identities not furnished by Apple.  If the timestamp authority service
             cannot be contacted over the Internet, or it malfunctions or refuses service, the signing oper-ation operation
             ation will fail.
             If this option is not given at all, a system-specific default behavior is invoked.  This may
             result in some but not all code signatures being timestamped.
             The special value none explicitly disables the use of timestamp services.

OPERATION
     In the first synopsis form, codesign attempts to sign the code objects at the path(s) given, using the
     identity provided. Internal requirements and entitlements are embedded if requested. Internal require-ments requirements
     ments not specified may be assigned suitable default values. Defaulting applies separately to each type
     of internal requirement.  If an identifier is explicitly given, it is sealed into all path(s).  Other-wise, Otherwise,
     wise, each path derives its identifier independently from its Info.plist or pathname.  Code nested
     within bundle directories (as identified from the applicable Resource Rules) must already be signed or
     the signing operation will fail, unless the --deep option is given, in which case any unsigned nested
     code will be recursively signed before proceeding, using the same signing options and parameters. If
     the --force option is given, any existing top-level signature is replaced, subject to any
     --preserve-metadata options also present. Combining the --force and --deep options results in forcible
     replacement of all signatures within the target bundle, as long as the resource rules identify them.

     In the second synopsis form, codesign verifies the code signatures on all the path(s) given. The veri-fication verification
     fication confirms that the code at those path(s) is signed, that the signature is valid, and that all
     sealed components are unaltered. If a requirement is given, each path is also checked against this
     requirement (but see DIAGNOSTICS below).  If verbose verification is requested, the program is also
     checked against its own designated requirement, which should never fail for a properly signed program.

     If a path begins with a decimal digit, it is interpreted as the process id of a running process in the
     system, and dynamic validation is performed on that process instead.  This checks the code's dynamic
     status and just enough static data to close the nominal security envelope. Add at least one level of
     verbosity to also perform a full static check.

     In the third synopsis form, codesign displays the contents of the signatures on the path(s) given. More
     information is displayed as the verbosity level increases.  This form may not completely verify the
     signatures on the path(s); though it may perform some verification steps in the process of obtaining
     information about the path(s).  If the -r path option is given, internal requirements will be extracted
     from the path(s) and written to path; specify a dash "-" to write to standard output. If the code does
     not contain an explicit designated requirement, the implied one will be retrieved and written out as a
     source comment.  If the --entitlements path option is given, embedded entitlement data will be
     extracted likewise and written to the file specified.

     In the fourth synopsis form, codesign constructs the hosting path for each pid given and writes it, one
     host per line, to standard output. The hosting path is the chain of code signing hosts starting with
     the most specific code known to be running, and ending with the root of trust (the kernel). If the
     --verbose option is given, the dynamic validity status of each host is also displayed, separated from
     the path by a tab character.  Note that hosting chains can at times be constructed for invalid or even
     unsigned code, and the output of this form of the codesign command should not be taken as a statement
     of formal code validity. Only codesign --verify can do that; and in fact, formal verification con-structs constructs
     structs the hosting chain as part of its operation (but does not display it).

SIGNING IDENTITIES
     To be used for code signing, a digital identity must be stored in a keychain that is on the calling
     user's keychain search list.  All keychain sources are supported if properly configured. In particular,
     it is possible to sign code with an identity stored on a supported smart card.  If your signing iden-tity identity
     tity is stored in a different form, you need to make it available in keychain form to sign code with
     it.
     If the --keychain argument is used, identity is only looked-for in the specific keychain given. This is
     meant to help disambiguate references to identities.  Even in that case, the full keychain search list
     is still consulted for additional certificates needed to complete the signature.

     The identity is first considered as the full name of a keychain identity preference.  If such a prefer-ence preference
     ence exists, it directly names the identity used.  Otherwise, the identity is located by searching all
     keychains for a certificate whose subject common name (only) contains the identity string given. If
     there are multiple matches, the operation fails and no signing is performed; however, an exact match is
     preferred over a partial match.  These comparisons are case sensitive.  Multiple instances of the
     exactly same certificate in multiple keychains are tolerated as harmless.

     If identity consists of exactly forty hexadecimal digits, it is instead interpreted as the SHA-1 hash
     of the certificate part of the desired identity.  In this case, the identity's subject name is not con-sidered. considered.
     sidered.

     Both identity preferences and certificate hashes can be used to identify a particular signing identity
     regardless of name. Identity preferences are global settings for each user and provide a layer of indi-rection. indirection.
     rection. Certificate hashes are very explicit and local. These choices, combined with what is placed
     into Xcode project and target build variables and/or script settings, allows for very flexible designa-tion designation
     tion of signing identities.

     If identity is the single letter "-" (dash), ad-hoc signing is performed.  Ad-hoc signing does not use
     an identity at all, and identifies exactly one instance of code. Significant restrictions apply to the
     use of ad-hoc signed code; consult documentation before using this.

     codesign will attempt to embed the entire certificate chain documenting the signing identity in the
     code signature it generates, including any intermediate certificates and the anchor certificate. It
     looks for those in the keychain search list of the user performing the signing operation. If it cannot
     generate the entire certificate chain, signing may still succeed, but verification may fail if the ver-ifying verifying
     ifying code does not have an independent source for the missing certificates (from its keychains).

SPECIFYING REQUIREMENTS
     The requirement(s) arguments (-r and -R) can be given in various forms. A plain text argument is taken
     to be a path to a file containing the requirement(s).  codesign will accept both binary files contain-ing containing
     ing properly compiled requirements code, and source files that are automatically compiled before use.
     An argument of "-" requests that the requirement(s) are read from standard input.  Finally, an argument
     that begins with an equal sign "=" is taken as a literal requirements source text, and is compiled
     accordingly for use.

OPTION FLAGS
     When signing, a set of option flags can be specified to change the behavior of the system when using
     the signed code. The following flags are recognized by codesign; other flags may exist at the API
     level. Note that you can specify any valid flags by giving a (single) numeric value instead of a list
     of option names.

     kill     Forces the signed code's kill flag to be set when the code begins execution.  Code with the
              kill flag set will die when it becomes dynamically invalid. It is therefore safe to assume
              that code marked this way, once validated, will have continue to have a valid identity while
              alive.

     hard     Forces the signed code's hard flag to be set when the code begins execution.  The hard flag is
              a hint to the system that the code prefers to be denied access to resources if gaining such
              access would invalidate its identity.

     host     Marks the code as capable of hosting guest code. You must set this option if you want the code
              to act as a code signing host, controlling subsidiary ("guest") code. This flag is set auto-matically automatically
              matically if you specify an internal guest requirement.

     expires  Forces any validation of the code to consider expiration of the certificates involved. Code
              signatures generated with this flag will fail to verify once any of the certificates in the
              chain has expired, regardless of the intentions of the verifier. Note that this flag does not
              affect any other checks that may cause signature validation to fail, including checks for cer-tificate certificate
              tificate revocation.

     Note that code can set the hard and kill flags on itself at any time. The signing options only affect
     their initial state. Once set by any means, these flags cannot be cleared for the lifetime of the code.
     Therefore, specifying such flags as signing options guarantees that they will be set whenever the
     signed code runs.

     If the code being signed has an Info.plist that contains a key named CSFlags, the value of that key is
     taken as the default value for the options. The value of CSFlags can be a string in the same form as
     the --options option, or an integer number specifying the absolute numeric value. Note however that
     while you can abbreviate flag names on the command lines, you must spell them out in the Info.plist.

EXAMPLES
     To sign application Terminal.app with a signing identity named "authority":
           codesign -s authority Terminal.app

     To sign the command-line tool "helper" with the same identity, overwriting any existing signature,
     using the signing identifier "com.mycorp.helper", and embedding a custom designated requirement
           codesign -f -s authority --prefix=com.mycorp. -r="designated => anchor /tmp/foo" helper

     To verify the signature on Terminal.app and produce some verbose output:
           codesign --verify --verbose Terminal.app

     To verify the dynamic validity of process 666:
           codesign --verify 666

     To display all information about Terminal.app's code signature:
           codesign --display --verbose=4 Terminal.app

     To extract the internal requirements from Terminal.app to standard output:
           codesign --display -r- Terminal.app

DIAGNOSTICS
     codesign exits 0 if all operations succeed. This indicates that all codes were signed, or all codes
     verified properly as requested. If a signing or verification operation fails, the exit code is 1. Exit
     code 2 indicates invalid arguments or parameters. Exit code 3 indicates that during verification, all
     path(s) were properly signed but at least one of them failed to satisfy the requirement specified with
     the -R option.

     For verification, all path arguments are always investigated before the program exits.  For all other
     operations, the program exits upon the first error encountered, and any further path arguments are
     ignored, unless the --continue option was specified, in which case codesign will defer the failure exit
     until after it has attempted to process all path arguments in turn.

SIGNING ATOMICITY
     When a signing operation fails for a particular code, the code may already have been modified in cer-tain certain
     tain ways by adding requisite signature data. Such information will not change the operation of the
     code, and the code will not be considered signed even with these pieces in place. You may repeat the
     signing operation without difficulty.  Note however that a previous valid signature may have been
     effectively destroyed if you specified the -f option.
     If you require atomicity of signing stricter than provided by codesign, you need to make an explicit
     copy of your code and sign that.

ENVIRONMENT
     If the CODESIGN_ALLOCATE environment variable is set, it identifies a substitute codesign_allocate tool
     used to allocate space for code signatures in Mach-O binaries. This is used by Xcode SDK distributions
     to provide architectural support for non-native platforms such as iPhones.  The system will not accept
     such substitutes unless they are specially signed (by Apple).

FILES
     /var/db/DetachedSignatures  System-wide database of detached code signatures for unsigned code.

SEE ALSO
     csreq(1), xcodebuild(1), codesign_allocate(1)

HISTORY
     The codesign command first appeared in Mac OS 10.5.0 (Leopard).

BUGS
     Some options only apply to particular operations, and codesign ignores them (without complaining) if
     you specify them for an operation for which they have no meaning.

     The --preserve-metadata option used to take no value, and varied across releases in what exactly it
     preserved. The ensuing confusion is still with you if you need to make backward-compatible scripts.

     The dual meaning of the -v option, indicating either verbosity or verification, confuses some people.
     If you find it confusing, use the unambiguous long forms --verbose and --verify instead.

NOTES
     The Xcode build system invokes codesign automatically if the CODE_SIGN_IDENTITY build variable is set.
     You can express any combination of codesign options with additional build variables there.

     codesign is fundamentally a shell around the code signing APIs, and performs nothing of the underlying
     work.  Replacing it with older or newer versions is unlikely to have a useful effect.

     codesign has several operations and options that are purposely left undocumented in this manual page
     because they are either experimental (and subject to change at any time), or unadvised to the unwary.
     The interminably curious are referred to the published source code.

BSD                               May 7, 2011                              BSD