Crate apple_codesign

Expand description

Binary code signing for Apple platforms.

This crate implements application code signing for Apple operating systems (like macOS and iOS). A goal of this crate is to serve as a stand-in replacement for Apple’s codesign (and similar tools) without a dependency on an Apple hardware device or operating system: you should be able to sign and release Apple binaries from Linux, Windows, or other non-Apple environments if you want to.

Apple code signing is complex and there are likely several areas where this crate and Apple’s implementations don’t align. It is highly recommended to validate output against what Apple’s official tools produce.

§Features and Capabilities

This crate can:

Find code signature data embedded in Mach-O binaries (both single and multi-arch/fat/universal binaries). (See MachOBinary struct.)
Deeply parse code signature data into Rust structs. (See EmbeddedSignature, BlobData, and e.g. CodeDirectoryBlob.
Parse and verify the RFC 5652 Cryptographic Message Syntax (CMS) signature data. This includes using a Time-Stamp Protocol (TSP) / RFC 3161 server for including a signed time-stamp token for that signature. (Functionality provided by the cryptographic-message-syntax crate, developed in the same repository as this crate.)
Generate new embedded signature data, including cryptographically signing that data using any signing key and X.509 certificate chain you provide. (See MachOSigner and BundleSigner.)
Writing a new Mach-O file containing new signature data. (See MachOSigner.)
Parse CodeResources XML plist files defining information on nested/signed resources within bundles. This includes parsing and applying the filtering rules defining in these files.
Sign bundles. Nested bundles will automatically be signed. Additional Mach-O binaries outside the main executable will also be signed. Non Mach-O/code files will be digested. A CodeResources XML file will be produced.
Submit notarization requests to Apple and query notarization status. (Bundles, DMGs, and .pkg installers are all supported.)
Retrieve notarization tickets from Apple and staple. All formats supporting notarization can be stapled.

There are a number of missing features and capabilities from this crate that we hope are eventually implemented:

No parsing of the Code Signing Requirements DSL. We support parsing the binary requirements to Rust structs, serializing back to binary, and rendering to the human friendly DSL. You will need to use the csreq tool to compile an expression to binary and then give that binary blob to this crate. Alternatively, you can write Rust code to construct a code requirements expression and serialize that to binary.
No turnkey support for signing keys. We want to make it easier for obtaining signing keys (and their X.509 certificate chain) for use with this crate. It should be possible to easily integrate with the OS’s key store or hardware based stores (such as Yubikeys). We also don’t look for necessary X.509 certificate extensions that Apple’s verification likely mandates, which we should do and enforce.
Some more advanced bundles or .pkg files may not sign, notarize, or staple correctly. Problems here are considered bugs and should be reported.

There is missing features and functionality that will likely never be implemented:

Binary verification compliant with Apple’s operating systems. We are capable of verifying the digests of code and other embedded signature data. We can also verify that a cryptographic signature came from the annotated public key in that signature. We can also write heuristics to look for certain common problems with signatures. But we can’t and likely never will implement all the rules Apple uses to verify a binary for execution because we perceive there to be little value in doing this. This crate could be used to build such functionality elsewhere, however.

§End-User Documentation

The end-user documentation is maintained as a Sphinx docs tree in the docs directory. The latest version of the documentation is published at https://gregoryszorc.com/docs/apple-codesign/main/.

§Getting Started

The UnifiedSigner type is a good place to start to see how the high level API for signing is implemented.

To learn about the low-level data structures in embedded code signatures, read specification. Or look at the code in embedded_signature and embedded_signature_builder.

MachOSigner is the type responsible for signing Mach-O files.

BundleSigner is the type responsible for signing bundles.

dmg::DmgSigner signs DMG files.

The EmbeddedSignature represents a parsed Apple code signature and provides API for data retrieval.

§Accessing Apple Code Signing Certificates

This crate doesn’t yet support integrating with the macOS keychain to obtain or use the code signing certificate private key. However, it does support importing the certificate key from a .p12 file exported from the Keychain Access application. It also supports exporting the x509 certificate chain for a given certificate by speaking directly to the macOS keychain APIs.

See the keychain-export-certificate-chain CLI command for exporting a code signing certificate’s x509 chain as PEM.

Re-exports§

pub use code_requirement::*;
pub use embedded_signature::*;
pub use embedded_signature_builder::*;
pub use notarization::*;

Modules§

cli
code_requirement: Code requirement language primitives.
cryptography: Common cryptography primitives.
dmg: DMG file handling.
embedded_signature: Common embedded signature data structures (superblobs, magic values, etc).
embedded_signature_builder: Provides primitives for constructing embeddable signature data structures.
entitlements: Code entitlements handling.
environment_constraints: Launch constraints and library constraints.
macho_builder: Mach-O writing.
notarization: Apple notarization functionality.
plist_der: Plist DER encoding.
remote_signing: Remote signing support.
specification: Apple code signing technical specifications
stapling: Attach Apple notarization tickets to signed entities.
ticket_lookup: Support for retrieving notarization tickets and stapling artifacts.

Structs§

BlobDescription
BuildVersionCommand: Content of an LC_BUILD_VERSION load command.
BundleSigner: A primitive for signing an Apple bundle.
BundleSigningContext: Holds state and helper methods to facilitate signing a bundle.
BundleSigningInfo: Holds metadata describing the result of a bundle signing operation.
CertificateInfo
CmsSignature: High-level representation of a CMS signature.
CmsSigner
CodeDirectory
CodeDirectoryBlob: Represents a code directory blob entry.
CodeResources: Represents a _CodeSignature/CodeResources XML plist.
CodeResourcesBuilder: Interface for constructing a CodeResources instance.
CodeResourcesRule: Represents an abstract rule in a CodeResources XML plist.
CodeSignature: High level representation of a code signature.
CodeSignatureFlags: Code signature flags.
DmgEntity
ExecutableSegmentFlags: Flags that influence behavior of executable segment.
FileEntity
MachFile: Represents a semi-parsed Mach[-O] binary.
MachOBinary: A Mach-O binary.
MachOEntity
MachOSignatureData: Describes signature data embedded within a Mach-O binary.
MachOSigner: Mach-O binary signer.
MachoTarget: Targeting settings for a Mach-O binary.
Scatter
SignedMachOInfo: Metadata about a signed Mach-O file or bundle.
SigningSettings: Represents code signing settings.
SingleBundleSigner: A primitive for signing a single Apple bundle.
UnifiedSigner: An entity for performing signing that is able to handle all supported target types.
UniversalBinaryBuilder: Interface for constructing a universal Mach-O binary.
VerificationContext: Context for a verification issue.
VerificationProblem
XarFile
XarSignature
XarTableOfContents

Enums§

AppleCodesignError: Unified error type for Apple code signing.
CertificateAuthorityExtension: Denotes specific certificate extensions on Apple certificate authority certificates.
CertificateProfile: Describes combinations of certificate extensions for Apple code signing certificates.
CodeDirectoryVersion: Version of Code Directory data structure.
CodeSignatureFile
CodeSigningCertificateExtension: Describes one of the many X.509 certificate extensions found on Apple code signing certificates.
DesignatedRequirementMode: Describes how to derive designated requirements during signing.
ExecutionPolicy: Defines well-known execution policies for signed code.
ExtendedKeyUsagePurpose: Describes the type of code signing that a certificate is authorized to perform.
FilesFlavor: Which files section we are operating on and how to digest.
KnownCertificate: Defines all known Apple certificates.
PathType: Describes the type of entity at a path.
Platform: Represents PLATFORM_ mach-o constants.
ScopedSetting: Describes the type of a scoped setting.
SettingsScope: Denotes the scope for a setting.
SignatureEntity
SignatureReader: Entity for reading Apple code signature data.
VerificationProblemType: Describes a problem with verification.

Constants§

OID_USER_ID: UserID.

Traits§

AppleCertificate: Extends functionality of CapturedX509Certificate with Apple specific certificate knowledge.
AppleCertificateBuilder: Extensions to X509CertificateBuilder specializing in Apple certificate behavior.

Functions§

copy_bundle: Copy a bundle’s contents to a destination directory.
create_self_signed_code_signing_certificate: Create a new self-signed X.509 certificate suitable for signing code.
derive_designated_requirements: Derive a designated requirements expression given a code signing certificate.
developer_id_signed_expression: Derive a code requirements expression for a Developer ID issued certificate.
non_apple_signed_expression: Derive the requirements expression for non Apple signed certificates.
normalized_resources_path: Convert a relative filesystem path to its CodeResources normalized form.
parse_version_nibbles: Parses and integer with nibbles xxxx.yy.zz into a semver::Version.
path_identifier
path_is_macho: Whether the specified filesystem path is a Mach-O binary.
path_is_xar: Test whether a given path is likely a XAR file.
path_is_zip: Test whether a given path is likely a ZIP file.
semver_to_macho_target_version: Convert a semver::Version to a u32 with nibble encoding used by Mach-O.
verify_macho: Verifies a parsed Mach-O binary.
verify_macho_data: Verifies unparsed Mach-O data.
worldwide_developer_relations_signed_expression: Derive the requirements expression for a cert signed by the Worldwide Developer Relations CA.
write_macho_file: Write Mach-O file content to an output file.

Type Aliases§

Result: Result type for this library.