Crate tugger_apple_codesign[][src]

Expand description

Binary code signing for Apple platforms.

This crate provides a pure Rust implementation of binary code signing for Apple operating systems (like macOS and iOS). A goal of this crate is to facilitate reimplementing functionality from Apple’s codesign and other similar tools without a dependency on an Apple machine or operating system: you should be able to sign Apple binaries from Linux or Windows if you wanted to.

This crate is in its early stages of development and there are many rough edges. Use at your own risk. Always validate signed binaries with Apple’s codesign tool to ensure correctness.

Features and Capabilities

This crate can:

  • Find code signature data embedded in Mach-O binaries (both single and multi-arch/fat/universal binaries). (See AppleSignable trait and its methods.)
  • 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.

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

  • Only embedded signatures are supported. (No support for detached signatures.)
  • 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.
  • Notarization support. The notarization ticket appears to be part of the embedded signature data. We don’t support parsing this blob. It should be possible to coerce this crate into emitting a notarization blob in the signature data. But this isn’t currently implemented as part of our high-level signing primitives.

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.

Getting Started

This crate is still in early phases of development. Until things are more mature, a good place to start with the source code is main.rs to get a feel for what CLI commands do.

The MachOSigner type is your gateway to how code signing is performed.

The AppleSignable trait extends the goblin::mach::MachO type with code signing functionality.

The EmbeddedSignature type describes existing code signatures on Mach-O binaries.

If you’d like to learn about the technical underpinnings of code signing on Apple platforms, see specification.

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::*;

Modules

Code requirement language primitives.

Apple code signing technical specifications

Structs

Represents a single blob as defined by a SuperBlob index entry.

Represents a generic blob wrapper.

A primitive for signing an Apple bundle.

Represents a code directory blob entry.

Represents a _CodeSignature/CodeResources XML plist.

Interface for constructing a CodeResources instance.

Represents an abstract rule in a CodeResources XML plist.

Code signature flags.

A detached signature.

Represents embedded signature data in a Mach-O binary.

Represents an embedded signature.

An old embedded signature.

Represents an Entitlements blob.

Flags that influence behavior of executable segment.

Describes signature data embedded within a Mach-O binary.

Mach-O binary signer.

Represents an unknown blob type.

Represents the parsed content of a blob entry.

Represents a Requirement blob.

Represents a Requirement set blob.

Metadata about a signed Mach-O file or bundle.

Represents code signing settings.

A primitive for signing a single Apple bundle.

Context for a verification issue.

Enums

Unified error type for Apple code signing.

Represents a single, parsed Blob entry/slot.

Denotes specific certificate extensions on Apple certificate authority certificates.

Describes combinations of certificate extensions for Apple code signing certificates.

Version of Code Directory data structure.

Describes one of the many X.509 certificate extensions found on Apple code signing certificates.

Defines header magic for various payloads.

Defines a typed slot within code signing data.

Describes how to derive designated requirements during signing.

Represents a digest type from a CS_HASHTYPE_* constants.

Defines well-known execution policies for signed code.

Describes the type of code signing that a certificate is authorized to perform.

Defines all known Apple certificates.

Denotes type of code requirements.

Denotes the scope for a setting.

Describes a problem with verification.

Constants

UserID.

Traits

Extends functionality of CapturedX509Certificate with Apple specific certificate knowledge.

Extensions to X509CertificateBuilder specializing in Apple certificate behavior.

Provides common features for a parsed blob type.

Used to process individual files within a bundle.

Functions

Compute code hashes for a Mach-O binary.

Compute paged hashes.

Obtain the XML plist containing code directory hashes.

Create a new self-signed X.509 certificate suitable for signing code.

Create the binary content for a SuperBlob.

Derive a designated requirements expression given a code signing certificate.

Attempt to extract a reference to raw signature data in a Mach-O binary.

Parse PFX data into a key pair.

Verifies a parsed Mach-O binary.

Verifies unparsed Mach-O data.

Verifies a binary in a given path.