codesign

Display, Verify, Sign code signatures, inquire into the dynamic status of signed code

codesign --display [-verbosity] [path|pid …]
codesign --verify [-R requirement] [-verbosity] [path|pid …]
codesign --sign identity [-i identifier] [-r requirements] [-fv] [path …]
codesign --host [-verbosity] [pid …]

--verbose Sets or increments verbosity . Default:No output on success.
codesign --display  -r xy $PPID
Executable=/usr/bin/login
% cat xy
designated => identifier "com.apple.login" and 
                          anchor apple


 codesign --display --verbose $PPID
Executable=/usr/bin/login
Identifier=com.apple.login
Format=Mach-O thin (arm64e)
CodeDirectory v=20400 size=776 flags=0x0(none) 
              hashes=14+7 location=embedded
Platform identifier=15
Signature size=4442
Signed Time=Feb 10, 2024 at 03:42:04
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none






codesign --display --verbose --verbose $PPID
Executable=/usr/bin/login
Identifier=com.apple.login
Format=Mach-O thin (arm64e)
CodeDirectory v=20400 size=776 flags=0x0(none) 
              hashes=14+7 location=embedded
Platform identifier=15














Signature size=4442
Authority=Software Signing
Authority=Apple Code Signing Certification Authority
Authority=Apple Root CA
Signed Time=Feb 10, 2024 at 03:42:04
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none

ls -lg `which login`
-r-sr-xr-x  1 root  139312 Feb 28 23:05 /usr/bin/login*

 codesign --display --verbose --verbose --verbose $PPID 
Executable=/usr/bin/login
Identifier=com.apple.login
Format=Mach-O thin (arm64e)
CodeDirectory v=20400 size=776 flags=0x0(none) 
              hashes=14+7 location=embedded
Platform identifier=15
Hash type=sha256 size=32
CandidateCDHash sha256=0e…4e
CandidateCDHashFull sha256=0e…f7
Hash choices=sha256
CMSDigest=0e&helliop;f7
CMSDigestType=2
CDHash=0e4c9421c8c505eda1f06b8f8c601b908e15f44e
Signature size=4442
Authority=Software Signing
Authority=Apple Code Signing Certification Authority
Authority=Apple Root CA
Signed Time=Feb 10, 2024 at 03:42:04
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none



% codesign --display --verbose=4  $PPID
Executable=/usr/bin/login
Identifier=com.apple.login
Format=Mach-O thin (arm64e)
CodeDirectory v=20400 size=776 flags=0x0(none) 
              hashes=14+7 location=embedded
Platform identifier=15
VersionPlatform=1 In addition to verbose=3
VersionMin=918528
VersionSDK=918528
Hash type=sha256 size=32
CandidateCDHash sha256=0e…4e
CandidateCDHashFull sha256=0e…f7
Hash choices=sha256
CMSDigest=0e…f7
CMSDigestType=2
Executable Segment base=0
Executable Segment limit=16384
Executable Segment flags=0x1
Page size=4096i
CDHash=0e4c9421c8c505eda1f06b8f8c601b908e15f44e
Signature size=4442
Authority=Software Signing
Authority=Apple Code Signing Certification Authority
Authority=Apple Root CA
Signed Time=Feb 10, 2024 at 03:42:04
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none
--continue Continue processing path arguments if a failure occurs.
Exit due to operational errors is deferred until all path arguments have been considered.
The exit code will indicate the most severe failure.
-d file
--display
Display information about the signature .
-r, --file-list, --extract-certificates and --entitlements can be used to retrieve additional information.
 codesign --display ~/bin/ftp
Executable=/Volumes/DATADG/dgxxx/bin/ftp
Identifier=com.apple.ftp
Format=Mach-O thin (x86_64)
CodeDirectory v=20100 size=1310 flags=0x0(none) hashes=37+2 location=embedded
Platform identifier=2
Signature size=4105
Info.plist=not bound
TeamIdentifier=not set
Sealed Resources=none 
-r requirements
--requirements
Output destination of the code's internal requirements. Use -r- for standard output.
codesign  --display -r- ~/bin/ftp
Executable=/Volumes/DATA/userrman/bin/ftp
designated => identifier "com.apple.ftp" and anchor apple
--file-list path When displaying a signature, outputs a list of files that may have been modified
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 is appended-to, with one line per absolute path .
"-" denotes standard output.
Files not listed are unchanged.
Some of the files listed may not have changed. Changes may have been made to extended attributes of these files.
--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.
--entitlements file When displaying extract any entitlement data from the signature and write it to file. Use "-" for standard output.
Default: the "blob" header is returned intact; prefix file with a colon ":" to strip off the header.
If the signature has no entitlement data, nothing is written.
-a architecture
--architecture
Select the Mach-O architecture by name (e.g. i386) or by number with an optional sub-architecture preceeded by a comma.
Only for Mach-O binary code otherwise ignored .
If the path uses the Mach-O format and contains no code of the given architecture, the command will fail. Default : report on the native architecture of the host system.
--deep When displaying a signature, a list of directly nested code is 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.

-h PID
--hosting
Constructs and outputs the hosting chain of a running program.
--Verbose displays the individual dynamic validity status of each element of the hosting chain.

--validate-constraint path check the supplied constraint plist
--verify Verify the code signatures.
-r requirements
--requirements
-a architecture
--architecture
When verifying select the Mach-O architecture by name (e.g. i386) or by number with an optional sub-architecture preceeded by a comma.
Only for Mach-O binary code otherwise ignored .
If the path uses the Mach-O format and contains no code of the given architecture, the command will fail. For verification default is --all-architectures
--ignore-resources During static validation, do not validate the contents of the code's resources. This will pass validation on code whose resources have been corrupted (or inappropriately signed). Substantially speeds up static validation,
--prefix string If no explicit unique identifier is specified (using --identifier) and if the implicitly generated identifier does not contain any dots (.) string is prefixed to the identifier before use.
If the implicit identifier contains a dot, it is used as-is.
This is used to deal with command tools without Info.plists, whose default identifier is the command's filename.
The conventional prefix used is .TDL.domain (The final dot needs to be explicit).
--strict options When validating code, apply additional restrictions beyond the defaults.
symlinks Check that symbolic links inside the code bundle point to sealed files inside its bundle.
Broken symbolic links are rejected, as are links to places outside the bundle and to places that are not sealed by the signature.
sideband Check that no resource forks, Finder attributes, or similar sideband data is present in the signed code.
Options are a comma-separated list. Use --strict or --strict=all to be as strict as possible.
Not all checks make sense in all circumstances.
--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
-R
--test-requirement requirement
During verification the path(s) should be verified against the code requirement specified.
If omitted, the code is verified only for internal integrity and against its own designated requirement.
-D
--detached file
When verifying, designates a file containing a detached signature to be used for veriication.
--check-notarization When verifying the code at the path(s) given, force an online notarization check to see if a notarization ticket is available.
--deep 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.
--sign identity Sign the code at the path(s) given using this identity. See SIGNING IDENTITIES .
--file-list path When signing displaying a signature, outputs a list of files that may have been modified
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 is appended-to, with one line per absolute path .
"-" denotes standard output.
Files not listed are unchanged.
Some of the files listed may not have changed. Changes may have been made to extended attributes of these files.
--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.
-o
--options flag,…
During signing, specifies a set of option flags to be embedded in the code signature.
list of names (with no spaces). A numeric value can be used to directly specify the option mask (CodeDirectory flag word). See OPTION FLAGS .
-r requirements
--requirements
During signing, indicates that internal requirements should be embedded in the code path(s) as specified.
See "specifying requirements" .
Defaults will be applied to requirement types that are not explicitly specified; To defeat the default, specify "never" for that type.
-a architecture
--architecture
Only for Mach-O binary code otherwise ignored .
If the path uses the Mach-O format and contains no code of the given architecture, the command will fail. When signing, codesign will always sign all architectures contained in a universal Mach-O file.
--preserve-metadata=list When re-signing code preserve some information from the old signature.
If new data is specified , it is preferred.
This option takes a comma-separated list of names, which may be abbreviated
identifier signing identifier (--identifier).
entitlements entitlement data (--entitlements).
requirements internal requirements (--requirements ), including explicit Designated Requirement. All internal requirements are preserved or regenerated as a whole
--force enables overwriting signatures .
flags option flags (-o), see the OPTION FLAGS section
runtime [v] hardened runtime version (-o runtime flag, --runtime-version ) instead of overriding or deriving the version.
If this option is absent, old signature has no effect on the signing process.
If the linker-signed flag is present on the previous binary, this option is ignored.
-D
--detached file
When signing, designates that a detached signature should be written to file.
Embedded signature in the code is ignored.

The code being signed is not modified and need not be writable.

-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.
--dryrun During signing, performs most signing operations, but does not write the result .
Cryptographic signatures are generated, using the given signing identity and triggering any access control checks, the resulting signature is discarded.
-P bytes
--pagesize
Define the granularity of signing. bytes must be a power of two.
Chunks of bytes are separately signed and can be independently verified .
bytes of zero to have the entire code signed and verified as a single chunk.
Only applies to the main executable and has no effect on the sealing of associated data, including resources.
--keychain filename During signing, only search for the signing identity in the keychain file specified, used to break matching ties with multiple similarly-named identities in several keychains on the user's search list.
Standard keychain search path is still consulted while constructing the certificate chain being embedded in the signature.
filename will not be searched to resolve the signing identity's certificate chain unless it is also on the user's keychain search list.
--timestamp [=URL] During signing, a timestamp authority server be contacted.
Without URL a default server provided by Apple is used.
May not support signatures made with identities not furnished by Apple.
If the timestamp authority service cannot be contacted, the signing operation will fail.
If this option is not given, a system-specific behavior is invoked. This may result in only some code signatures being timestamped.
none disables the use of timestamp services.
--runtime-version version During signing, when the runtime OPTION FLAG is set, explicitly specify the hardened runtime version stored in the code signature.
If omitted and the runtime OPTION FLAG is set, the hardened runtime version is omitted for non-Mach-O files and derived from the SDK version of Mach-O files.
--detached-database When signing, a detached signature is generated as with --detached , but the resulting signature is written into a system database, from where it is made available when apparently unsigned code is validated.
Writing to the system database requires elevated privileges .
-i identifier
--identifier
During signing, specify the unique identifier string that is embedded in code signatures.
If omitted, the identifier is derived from the Info.plist or the filename of the executable , possibly modified by the --prefix .

Do not to sign different programs with the same identifier.

--entitlements file When signing, embed file in the signature as entitlement data.
If the data does not begin with a "blob" header, one is attached.

--bundle-version version-string When handling versioned bundles such as frameworks, explicitly specify the version to operate on which must be one of the names in the "Versions" directory of the bundle.
If not specified, codesign uses the bundle's default version.
Most frameworks delivered with the system have only one version.
--remove-signature Removes the current code signature from the path(s) given.

OPERATION

codesign --display [-v] [path|pid]

Display the signatures.
Performs some verification steps in the process of obtaining information.
Does not verify the signatures

With -r path internal requirements will be extracted from the path(s) and written to path;
Use 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.

With --entitlements path embedded entitlement data will be extracted and written to the file.

codesign -sign identity [-i identifier] [-r requirements] [-fv] [path]

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 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 --deep is given, in which case any unsigned nested code will be recursively signed before proceeding, using the same signing options and parameters.
With --force existing top-level signature is replaced, subject to --preserve-metadata also present.
Combining --force and --deep results in forcible replacement of all signatures within the target bundle.

codesign i--verify [-R requirement] [-v] [path|pid …]

Verify the code signatures on 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 ).
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 the process id of a running process and dynamic validation is performed . This checks the code's dynamic status and just enough static data to close the nominal security envelope.
Include at least one level of verbosity to perform a full static check.

codesign --hosting [-v] [pid] codesign constructs the hosting path for each pid and writes it to stdout.
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).
With --verbose the dynamic validity status of each host is displayed, separated from the path by a tab.
Hosting chains can at times be constructed for invalid or even unsigned code and the output of this form should not be taken as a statement of formal code validity. Only codesign --verify does that.

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

If identity is only a "-" (dash) ad-hoc signing is performed.
identifies exactly one instance of code. Significant restrictions apply to the use of ad-hoc signed code;

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

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 accepts both binary files containing properly compiled requirements code and source files that are compiled before use. An argument of "-" requests that the requirement(s) are read from standard input. 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.
kill sets code's kill flag 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. Specifying kill as signing options guarantees it will be set when the code runs.
hard sets hard flag to be set when the code begins execution.
A hint to the system that the code prefers to be denied access to resources if gaining such access would invalidate its identity. Specifying hard as signing options guarantees it will be set whenever the signed code runs.
host Marks the code as capable of hosting guest code. to act as a code signing host, controlling subsidiary ("guest") code. This flag is set with an internal guest requirement.
expires Forces any validation of the code to consider expiration of the certificates involved.
fail to verify once any of the certificates in the chain has expired Does not affect other checks that may cause signature validation to fail, including checks for certificate revocation.
library sets library validation flag 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 recorded in signatures when signing with suitable Apple-issued signing certificates.
Not supported for i386 binaries and only applies to the main executable. No effect on frameworks and libraries.
runtime 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.
linker-signed Linker signatures are similar to adhoc signatures, except:
  • can be replaced without using --force
  • are never preserved regardless of the use of --preserve-metadata
  • will usually not contain any embedded code requirements including a designated requirement.

Code can set the hard and kill flags on itself at any time. The signing options affect initial state.
Once set they cannot be cleared for the lifetime of the code.

If the code has an Info.plist that contains the key CSFlags, the value is taken as the default value.
The value can be a string in the same form --options , or an integer number specifying the absolute numeric value. No annreviations are permitted.

EXAMPLES

codesign -d -v `which sftp           codesign -d -v `which ftp`  
Executable=/usr/bin/sftp                Executable=/Volumes/DATADG/dgxxx/bin/ftp
Identifier=com.apple.sftp               Identifier=com.apple.ftp
Format=Mach-O universal (x86_64 arm64e) Format=Mach-O thin (x86_64)
CodeDirectory v=20400 size=1415         CodeDirectory v=20100 size=1310    
            flags=0x0(none)             flags=0x0(none) 
            hashes=39+2                 hashes=37+2 
            location=embedded           location=embedded  
Platform identifier=15                  Platform identifier=2
Signature size=4442                     Signature size=4105
Signed Time=Feb 10, 2024 at 03:50:36
Info.plist entries=17                   Info.plist=not bound
TeamIdentifier=not set                  TeamIdentifier=not set
Sealed Resources=none                   Sealed Resources=none
Internal requirements count=1 size=64   Internal requirements count=1 size=64


% sftp xx                               % ftp xx
usage: sftp [-46AaCfNpqrv] …            zsh: killed     ftp


sign Terminal.app with a signing identity "authority": codesign --sign authority Terminal.app

sign the command-line "helper" with the identity "authority", overwriting existing signatures, 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

Enable the hardened runtime on Terminal.app and sign with the signing identity named "authority": codesign --sign authority --options runtime Terminal.app

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

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

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

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

Display the entitlements of a binary or bundle: codesign --display --entitlements :- /sbin/launchd codesign --display --entitlements :- Terminal.app

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

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 parame- ters. 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 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 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

$CODESIGN_ALLOCATE 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 plat- forms 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 are ignored for an operation for which they have no meaning.

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 Prefixing a number with "+" will force codesign to interpret the number as a PID. For example: codesign --verify 666 would become: codesign --verify +666

NOTES

The Xcode build system invokes codesign automatically if the CODE_SIGN_IDENTITY build variable is set. You can express any combi- nation 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 pub- lished source code.