Manual Pages for UNIX Darwin command on man codesign

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

NAME

ccooddeessiiggnn - Create and manipulate code signatures

SYNOPSIS

ccooddeessiiggnn -s identity [-i identifier] [-r requirements] [-ffvv] [path ...]

ccooddeessiiggnn -v [-R requirement] [-vv] [path|pid ...]

ccooddeessiiggnn -d [-vv] [path|pid ...]

ccooddeessiiggnn -h [-vv] [pid ...]

DESCRIPTION

The ccooddeessiiggnn command is used to create, check, and display code signa-

tures, as well as inquire into the dynamic status of signed code in the system.

ccooddeessiiggnn 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. OOPPTTIIOONNSS The options are as follows:

-dd,, --ddiissppllaayy

Display information about the code at the path(s) given. Increas-

ing 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 and

-file-list options can be used to retrieve additional informa-

tion.

-DD,, --ddeettaacchheedd filename

When signing, designates that a detached signature should be

written to the specified file. The code being signed is not modi-

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

-ff,, --ffoorrccee

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

-ii,, --iiddeennttiiffiieerr 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, possi-

bly modified by the -prefix option.

-oo,, --ooppttiioonnss flag,...

During signing, specifies a set of option flag 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.

-PP,, --ppaaggeessiizzee 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.

-rr,, --rreeqquuiirreemmeennttss requirements

During signing, indicates that internal requirements should be embedded in the code path(s) as specified. See "specifying requirements" below. During display, indicates where to write the code's internal

requirements. Use -r- to write them to standard output.

-RR,, --tteesstt-rreeqquuiirreemmeenntt 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.

-ss,, --ssiiggnn identity

Sign the code at the path(s) given using this identity. See SIGN-

ING IDENTITIES below.

-vv,, --vveerrbboossee -[[nn]]

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

-vv,, --vveerriiffyy

Requests verification of code signatures. If other actions

(sign, display, etc.) are also requested, -v is interpreted to

mean -verbose.

--ccoonnttiinnuuee

Instructs ccooddeessiiggnn to continue processing path arguments even if

processing one fails. If this option is given, exit due to oper-

ational 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 encoun-

tered).

--ddrryyrruunn

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.

--ffiillee-lliisstt path

When signing or displaying a signature, ccooddeessiiggnn 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 pro-

grams 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 modification may have been made to extended attributes of these files.

--iiggnnoorree-rreessoouurrcceess

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.

--kkeeyycchhaaiinn filename

During signing, only search for the signing identity in the key-

chain file specified. This can be used to break any matching ties

if you have multiple similarly-named identities in several key-

chains on the user's search list. Note that the standard key-

chain search path is still consulted while constructing the cer-

tificate chain being embedded in the signature.

--pprreeffiixx string

If no explicit unique identifier is specified (using the -i

option), and if the implicitly generated identifier does not con-

tain 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 com-

mand tools without Info.plists, whose default identifier is sim-

ply the command's filename; the conventional prefix used is com.domain. (note that the final dot needs to be explicit).

--rreessoouurrccee-rruulleess==ffiilleennaammee

During signing, this option overrides the default rules for col-

lecting bundle resources to be sealed into the signature. The argument is the path to a property list (plist) file containing resource scanning instructions. OOPPEERRAATTIIOONN In the first synopsis form, ccooddeessiiggnn attempts to sign the code objects at the path(s) given, using the identity provided. Internal requirements are

embedded if requested; if no -r option is given, there are no internal

requirements. 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. The pagesize can be used to control the granularity of the code hash table. Usually, only specific sizes are acceptable to the verifying agents; this option should be used only in special cases. In the second synopsis form, ccooddeessiiggnn 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 com-

ponents are unaltered. If a requirement is given, each path is also checked against this requirement (but see DIAGNOSTICS below). 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 per-

formed on that process instead. This includes verifying the process's source on disk, but also extends to that particular process's dynamic validity state.

In the third synopsis form, ccooddeessiiggnn displays the contents of the signa-

tures on the path(s) given. More information is displayed as the ver-

bosity level increases. This form may not completely verify the signa-

tures 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. In the fourth synopsis form, ccooddeessiiggnn 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 ccooddeessiiggnn command should not be taken as a statement of formal code validity. Only ccooddeessiiggnn

-verify can do that.

SSIIGGNNIINNGG IIDDEENNTTIITTIIEESS

To be used for code signing, a digital identity must be stored in a key-

chain that is on the calling user's keychain search list. The identity is located by searching all such keychains for a certificate whose subject contains the identity string given. If there are multiple matches, the invocation fails and no signing is performed.

If the -keychain argument is used, the identity is only looked-for in

the specific keychain given. Even in that case, the keychain search list is still consulted for additional certificates needed to complete the signature. ccooddeessiiggnn 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. 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 import it into a keychain to use it with this program. SSPPEECCIIFFYYIINNGG RREEQQUUIIRREEMMEENNTTSS

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). ccooddeessiiggnn will accept both binary files containing prop-

erly 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. OOPPTTIIOONN FFLLAAGGSS

When signing, a set of option flags can be specified to change the behav-

ior of the system when using the signed code. The following flags are recognized by ccooddeessiiggnn; 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 loses its identity. It is therefore safe to assume that code marked this way will 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 automati-

cally set if the code's internal requirement (-r option) con-

tains a 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 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. 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. EEXXAAMMPPLLEESS

To sign application Terminal.app with a signing identity named "author-

ity":

codesign -s authority Terminal.app

To sign the command-line tool "helper" with the same identity, overwrit-

ing 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 -vv Terminal.app

To verify the dynamic validity of process 666:

codesign -v 666

To display all information about Terminal.app's code signature:

codesign -dvvvv Terminal.app

To extract the internal requirements from Terminal.app to standard out-

put:

codesign -d -r- Terminal.app

DIAGNOSTICS ccooddeessiiggnn 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 veri-

fication, 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 ccooddeessiiggnn will

defer the failure exit until after it has attempted to process all path arguments in turn. SSIIGGNNIINNGG AATTOOMMIICCIITTYY 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 spec-

ified the -f option.

If you require atomicity of signing stricter than provided by ccooddeessiiggnn , you need to make an explicit copy of your code and sign that.