CODESIGN(1)                  General Commands Manual                 CODESIGN(1)

     codesign – Create and manipulate code signatures

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

     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.

     The options are as follows:

             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
             (--architecture) 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
             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-architectures, 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
             architectures 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 system 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.

             When verifying the code at the path(s) given, force an online
             notarization check to see if a notarization ticket is available.

     -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
             investigation 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

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

             When signing, convert the supplied entitlements XML data to DER and
             embed the entitlements as both XML and DER in the signature.
             Embedding DER entitlements is default behavior as of macOS 12.0
             when signing for all platforms. This argument was introduced in
             macOS 10.14 (Mojave).

     -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 validity status
             of each element of the hosting chain.

     -i, --identifier identifier
             During signing, explicitly specify the unique identifier string
             that is embedded in code signatures. 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 single, possibly gigantic page. This option only
             applies to the main executable and has no effect on the sealing of
             associated data, including resources.

             Removes the current code signature from the path(s) given.

     -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

             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

             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 identity 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 entitlement 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 in an abstract
             representation. If needed --xml or --der may be passed in to output
             the entitlements in a desired format, if you pass in both then DER
             will be printed. Use "-" as the path to write to standard output.
             If the signature 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) certificate, 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 argument
             of "-" (single dash) denotes standard output.  Note that the list
             may be somewhat pessimistic - 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.

             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 consulted 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 generated 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. Typically, 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).

             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.
             Note: if the linker-signed flag is present on the previous binary,
             then this option is ignored.
             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).

             requirements  Preserve the internal requirements (--requirements
                           option), including any explicit Designated
                           Requirement. Note that all internal requirements are
                           preserved or regenerated as a whole; you cannot pick
                           and choose individual elements with this option.

             flags         Preserve the option flags (-o), see the OPTION FLAGS
                           section below.

             runtime       Preserve the hardened runtime version (-o runtime
                           flag, --runtime-version option) instead of overriding
                           or deriving the version.
             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 specify an
             explicit list of preserved items.

     --strict options
             When validating code, apply additional restrictions beyond the

             symlinks  Check that symbolic links inside the code bundle point to
                       sealed files inside its bundle.  This means that broken
                       symbolic links are rejected, as are links to places
                       outside the bundle and to places that are not, for
                       whatever reason, sealed by the signature.

             sideband  Check that no resource forks, Finder attributes, or
                       similar sideband data is present in the signed code.
                       This is now automatically enforced by signing operations.
             Options can be specified as a comma-separated list. Use plain
             --strict or --strict=all to be as strict as possible. Note that
             --strict=all may include more checking types over time.
             Not all strictness check make sense in all circumstances, which is
             why these behaviors are not the defualt.

     --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 without 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 operation 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

     --runtime-version version
             During signing, when the runtime OPTION FLAG is set, explicitly
             specify the hardened runtime version stored in the code signature.
             If this option is omitted, but the runtime OPTION FLAG is set then
             the hardened runtime version is omitted for non-Mach-O files and
             derived from the SDK version of Mach-O files.

     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 requirements 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).  Otherwise, each path derives its identifier
     independently from its Info.plist or pathname.  Code nested within bundle
     directories 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.

     In the second synopsis form, codesign verifies the code signatures on all
     the path(s) given. The verification 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 constructs the hosting chain as part
     of its operation (but does not display it).

     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 identity 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 preference 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 considered.

     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 indirection.
     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 designation of signing

     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 verifying code does not have an
     independent source for the missing certificates (from its keychains).

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

     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
              automatically 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 certificate

     library  Forces the signed code's library validation flag to be set when
              the code begins execution.  The code will only be able to link
              against system libraries and frameworks, or libraries, frameworks,
              and plug-in bundles with the same team identifier embedded in the
              code directory.  Team identifiers are automatically recorded in
              signatures when signing with suitable Apple-issued signing
              certificates.  Note that the flag is not supported for i386
              binaries, and only applies to the main executable.  The flag has
              no effect when set on frameworks and libraries.

     runtime  On macOS versions >= 10.14.0, opts signed processes into a
              hardened runtime environment which includes runtime code signing
              enforcement, library validation, hard, kill, and debugging
              restrictions.  These restrictions can be selectively relaxed via
              entitlements. Note: macOS versions older than 10.14.0 ignore the
              presence of this flag in the code signature.

              Identifies a signature as signed by the linker. Linker signatures
              are very similar to adhoc signatures, except:

              •   linker signatures can be replaced without using the --force

              •   linker signatures are never preserved regardless of the use of
                  the --preserve-metadata option.

              •   linker signatures will usually not contain any embedded code
                  requirements including a designated requirement.

     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.

     To sign application with a signing identity named "authority":
           codesign --sign authority

     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 --sign authority --prefix=com.mycorp. -r="designated =>
           anchor /tmp/foo" helper

     To enable the hardened runtime on and sign with the signing
     identity named "authority":
           codesign --sign authority --options runtime

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

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

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

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

     To display the entitlements of a binary or bundle:
           codesign --display --entitlements - /sbin/launchd
           codesign --display --entitlements - --der

     To display the entitlements of process 666:
           codesign --display --entitlements - +666

     To display the XML entitlements of process 1337:
           codesign --display --entitlements - --xml +1337

     A common source of confusion when using codesign arises from the ordering
     of command line options. If codesign is not behaving as expected, consult
     this manual and check the ordering of your arguments. As a general rule
     codesign follows a verb noun rule. For example --sign should be placed
     before --options in the invocation. This is because you are performing a
     "sign" action with a given set of options.

     If these are inverted and --options is provided before --sign in the
     invocation, the value of --options is ignored silently.

     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

     When a signing operation fails for a particular code, the code may already
     have been modified in certain 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
     If you require atomicity of signing stricter than provided by codesign, you
     need to make an explicit copy of your code and sign that.

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

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

     csreq(1), xcodebuild(1), codesign_allocate(1)

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

     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.

     The --verify option can take either a file or a pid. If your file path
     starts with a number you should prefix it with "./" to force codesign to
     interpret the argument as a path. For example:
           codesign --verify 666
     would become:
           codesign --verify ./666

     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.

macOS 12.1                         May 7, 2011                        macOS 12.1