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 |
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 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 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.
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.
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.
Code can set the
If the code has an
sign the command-line "helper" with the identity "authority", overwriting existing signatures, using the signing identifier
Enable the hardened runtime on
verify the signature on Terminal.app and produce some verbose output:
verify the dynamic validity of process 666:
display all information about Terminal.app's code signature:
extract the internal requirements from Terminal.app to standard output:
Display the entitlements of a binary or bundle:
display the entitlements of process 666:
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
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 --preserve-metadata
also present.
Combining --force and --deep
results in forcible replacement of all signatures within the target bundle.
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.
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.
identifies exactly one instance of code. Significant restrictions apply to the use of ad-hoc signed code;
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:
--force
--preserve-metadata
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. 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
com.mycorp.helper
and embedding a custom designated requirement:
codesign -f --sign authority --prefix=com.mycorp. -r="designated => anchor /tmp/foo" helper
Terminal.app
and sign with the signing identity named "authority":
codesign --sign authority --options runtime Terminal.app
codesign --verify --verbose Terminal.app
codesign --verify +666
codesign --display --verbose=4 Terminal.app
codesign --display -r- Terminal.app
codesign --display --entitlements :- /sbin/launchd
codesign --display --entitlements :- Terminal.app
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.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.