Struct apple_codesign::SigningSettings

pub struct SigningSettings<'key> { /* private fields */ }

Represents code signing settings.

This type holds settings related to a single logical signing operation. Some settings (such as the signing key-pair are global). Other settings (such as the entitlements or designated requirement) can be applied on a more granular, scoped basis. The scoping of these lower-level settings is controlled via SettingsScope. If a setting is specified with a scope, it only applies to that scope. See that type’s documentation for more.

An instance of this type is bound to a signing operation. When the signing operation traverses into nested primitives (e.g. when traversing into the individual Mach-O binaries in a fat/universal binary or when traversing into nested bundles or non-main binaries within a bundle), a new instance of this type is transparently constructed by merging global settings with settings for the target scope. This allows granular control over which signing settings apply to which entity and enables a signing operation over a complex primitive to be configured/performed via a single SigningSettings and signing operation.

Implementations

impl<'key> SigningSettings<'key>

pub fn digest_type(&self) -> &DigestType

Obtain the digest type to use.

pub fn set_digest_type(&mut self, digest_type: DigestType)

Set the content digest to use.

The default is SHA-256. Changing this to SHA-1 can weaken security of digital signatures and may prevent the binary from running in environments that enforce more modern signatures.

pub fn signing_key(&self) -> Option<(&'key dyn Sign, &CapturedX509Certificate)>

Obtain the signing key to use.

pub fn set_signing_key(
    &mut self,
    private: &'key dyn Sign,
    public: CapturedX509Certificate
)

Set the signing key-pair for producing a cryptographic signature over code.

If this is not called, signing will lack a cryptographic signature and will only contain digests of content. This is known as “ad-hoc” mode. Binaries lacking a cryptographic signature or signed without a key-pair issued/signed by Apple may not run in all environments.

pub fn certificate_chain(&self) -> &[CapturedX509Certificate]

Obtain the certificate chain.

pub fn chain_apple_certificates(
    &mut self
) -> Option<Vec<CapturedX509Certificate>>

Attempt to chain Apple CA certificates from a loaded Apple signed signing key.

If you are calling set_signing_key(), you probably want to call this immediately afterwards, as it will automatically register Apple CA certificates if you are using an Apple signed code signing certificate.

pub fn chain_certificate(&mut self, cert: CapturedX509Certificate)

Add a parsed certificate to the signing certificate chain.

When producing a cryptographic signature (see SigningSettings::set_signing_key), information about the signing key-pair is included in the signature. The signing key’s public certificate is always included. This function can be used to define additional X.509 public certificates to include. Typically, the signing chain of the signing key-pair up until the root Certificate Authority (CA) is added so clients have access to the full certificate chain for validation purposes.

This setting has no effect if SigningSettings::set_signing_key is not called.

pub fn chain_certificate_der(
    &mut self,
    data: impl AsRef<[u8]>
) -> Result<(), AppleCodesignError>

Add a DER encoded X.509 public certificate to the signing certificate chain.

This is like Self::chain_certificate except the certificate data is provided in its binary, DER encoded form.

pub fn chain_certificate_pem(
    &mut self,
    data: impl AsRef<[u8]>
) -> Result<(), AppleCodesignError>

Add a PEM encoded X.509 public certificate to the signing certificate chain.

This is like Self::chain_certificate except the certificate is specified as PEM encoded data. This is a human readable string like -----BEGIN CERTIFICATE----- and is a common method for encoding certificate data. (PEM is effectively base64 encoded DER data.)

Only a single certificate is read from the PEM data.

pub fn time_stamp_url(&self) -> Option<&Url>

Obtain the Time-Stamp Protocol server URL.

pub fn set_time_stamp_url(
    &mut self,
    url: impl IntoUrl
) -> Result<(), AppleCodesignError>

Set the Time-Stamp Protocol server URL to use to generate a Time-Stamp Token.

When set and a signing key-pair is defined, the server will be contacted during signing and a Time-Stamp Token will be embedded in the cryptographic signature. This Time-Stamp Token is a cryptographic proof that someone in possession of the signing key-pair produced the cryptographic signature at a given time. It facilitates validation of the signing time via an independent (presumably trusted) entity.

pub fn team_id(&self) -> Option<&str>

Obtain the team identifier for signed binaries.

pub fn set_team_id(&mut self, value: impl ToString)

Set the team identifier for signed binaries.

pub fn set_team_id_from_signing_certificate(&mut self) -> Option<&str>

Attempt to set the team ID from the signing certificate.

Apple signing certificates have the team ID embedded within the certificate. By calling this method, the team ID embedded within the certificate will be propagated to the code signature.

Callers will typically want to call this after registering the signing certificate with Self::set_signing_key() but before specifying an explicit team ID via Self::set_team_id().

Calling this will replace a registered team IDs if the signing certificate contains a team ID. If no signing certificate is registered or it doesn’t contain a team ID, no changes will be made.

Returns Some if a team ID was set from the signing certificate or None otherwise.

pub fn path_exclusion_patterns(&self) -> &[Pattern]

Return relative paths that should be excluded from signing.

Values are glob pattern matches as defined the by glob crate.

pub fn add_path_exclusion(&mut self, v: &str) -> Result<(), AppleCodesignError>

Add a path to the exclusions list.

pub fn binary_identifier(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<&str>

Obtain the binary identifier string for a given scope.

pub fn set_binary_identifier(
    &mut self,
    scope: SettingsScope,
    value: impl ToString
)

Set the binary identifier string for a binary at a path.

This only has an effect when signing an individual Mach-O file (use the None path) or the non-main executable in a bundle: when signing the main executable in a bundle, the binary’s identifier is retrieved from the mandatory CFBundleIdentifier value in the bundle’s Info.plist file.

The binary identifier should be a DNS-like name and should uniquely identify the binary. e.g. com.example.my_program

pub fn entitlements_plist(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<&Value>

Obtain the entitlements plist as a plist::Value.

The value should be a plist::Value::Dictionary variant.

pub fn entitlements_xml(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Result<Option<String>, AppleCodesignError>

Obtain the entitlements XML string for a given scope.

pub fn import_settings_from_macho(
    &mut self,
    macho_data: &[u8]
) -> Result<(), AppleCodesignError>

Import existing state from Mach-O data.

This will synchronize the signing settings with the state in the Mach-O file.

If existing settings are explicitly set, they will be honored. Otherwise the state from the Mach-O is imported into the settings.

pub fn set_entitlements_xml(
    &mut self,
    scope: SettingsScope,
    value: impl ToString
) -> Result<(), AppleCodesignError>

Set the entitlements to sign via an XML string.

The value should be an XML plist. The value is parsed and stored as a native plist value.

pub fn designated_requirement(
    &self,
    scope: impl AsRef<SettingsScope>
) -> &DesignatedRequirementMode

Obtain the designated requirements for a given scope.

pub fn set_designated_requirement_expression(
    &mut self,
    scope: SettingsScope,
    expr: &CodeRequirementExpression<'_>
) -> Result<(), AppleCodesignError>

Set the designated requirement for a Mach-O binary given a CodeRequirementExpression.

The designated requirement (also known as “code requirements”) specifies run-time requirements for the binary. e.g. you can stipulate that the binary must be signed by a certificate issued/signed/chained to Apple. The designated requirement is embedded in Mach-O binaries and signed.

pub fn set_designated_requirement_bytes(
    &mut self,
    scope: SettingsScope,
    data: impl AsRef<[u8]>
) -> Result<(), AppleCodesignError>

Set the designated requirement expression for a Mach-O binary given serialized bytes.

This is like SigningSettings::set_designated_requirement_expression except the designated requirement expression is given as serialized bytes. The bytes passed are the value that would be produced by compiling a code requirement expression via csreq -b.

pub fn set_auto_designated_requirement(&mut self, scope: SettingsScope)

Set the designated requirement mode to auto, which will attempt to derive requirements automatically.

This setting recognizes when code signing is being performed with Apple issued code signing certificates and automatically applies appropriate settings for the certificate being used and the entity being signed.

Not all combinations may be supported. If you get an error, you will need to provide your own explicit requirement expression.

pub fn code_signature_flags(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<CodeSignatureFlags>

Obtain the code signature flags for a given scope.

pub fn set_code_signature_flags(
    &mut self,
    scope: SettingsScope,
    flags: CodeSignatureFlags
)

Set code signature flags for signed Mach-O binaries.

The incoming flags will replace any already-defined flags.

pub fn add_code_signature_flags(
    &mut self,
    scope: SettingsScope,
    flags: CodeSignatureFlags
) -> CodeSignatureFlags

Add code signature flags.

The incoming flags will be ORd with any existing flags for the path specified. The new flags will be returned.

pub fn remove_code_signature_flags(
    &mut self,
    scope: SettingsScope,
    flags: CodeSignatureFlags
) -> CodeSignatureFlags

Remove code signature flags.

The incoming flags will be removed from any existing flags for the path specified. The new flags will be returned.

pub fn executable_segment_flags(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<ExecutableSegmentFlags>

Obtain the executable segment flags for a given scope.

pub fn set_executable_segment_flags(
    &mut self,
    scope: SettingsScope,
    flags: ExecutableSegmentFlags
)

Set executable segment flags for Mach-O binaries.

The incoming flags will replace any already defined flags for the path.

pub fn info_plist_data(&self, scope: impl AsRef<SettingsScope>) -> Option<&[u8]>

Obtain the Info.plist data registered to a given scope.

pub fn runtime_version(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<&Version>

Obtain the runtime version for a given scope.

The runtime version represents an OS version.

pub fn set_runtime_version(&mut self, scope: SettingsScope, version: Version)

Set the runtime version to use in the code directory for a given scope.

The runtime version corresponds to an OS version. The runtime version is usually derived from the SDK version used to build the binary.

pub fn set_info_plist_data(&mut self, scope: SettingsScope, data: Vec<u8>)

Define the Info.plist content.

Signatures can reference the digest of an external Info.plist file in the bundle the binary is located in.

This function registers the raw content of that file is so that the content can be digested and the digest can be included in the code directory.

The value passed here should be the raw content of the Info.plist XML file.

When signing bundles, this function is called automatically with the Info.plist from the bundle. This function exists for cases where you are signing individual Mach-O binaries and the Info.plist cannot be automatically discovered.

pub fn code_resources_data(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<&[u8]>

Obtain the CodeResources XML file data registered to a given scope.

pub fn set_code_resources_data(&mut self, scope: SettingsScope, data: Vec<u8>)

Define the CodeResources XML file content for a given scope.

Bundles may contain a CodeResources XML file which defines additional resource files and binaries outside the bundle’s main executable. The code directory of the main executable contains a digest of this file to establish a chain of trust of the content of this XML file.

This function defines the content of this external file so that the content can be digested and that digest included in the code directory of the binary being signed.

When signing bundles, this function is called automatically with the content of the CodeResources XML file, if present. This function exists for cases where you are signing individual Mach-O binaries and the CodeResources XML file cannot be automatically discovered.

pub fn extra_digests(
    &self,
    scope: impl AsRef<SettingsScope>
) -> Option<&BTreeSet<DigestType>>

Obtain extra digests to include in signatures.

pub fn add_extra_digest(
    &mut self,
    scope: SettingsScope,
    digest_type: DigestType
)

Register an addition content digest to use in signatures.

Extra digests supplement the primary registered digest when the signer supports it. Calling this likely results in an additional code directory being included in embedded signatures.

A common use case for this is to have the primary digest contain a legacy digest type (namely SHA-1) but include stronger digests as well. This enables signatures to have compatibility with older operating systems but still be modern.

pub fn all_digests(&self, scope: SettingsScope) -> Vec<DigestType>

Obtain all configured digests for a scope.

pub fn as_nested_bundle_settings(&self, bundle_path: &str) -> Self

Convert this instance to settings appropriate for a nested bundle.

pub fn as_bundle_macho_settings(&self, path: &str) -> Self

Convert this instance to settings appropriate for a Mach-O binary in a bundle.

pub fn as_nested_macho_settings(&self, index: usize, cpu_type: CpuType) -> Self

Convert this instance to settings appropriate for a nested Mach-O binary.

It is assumed the main scope of these settings is already targeted for a Mach-O binary. Any scoped settings for the Mach-O binary index and CPU type will be applied. CPU type settings take precedence over index scoped settings.

Trait Implementations

impl<'key> Clone for SigningSettings<'key>

fn clone(&self) -> SigningSettings<'key>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'key> Default for SigningSettings<'key>

fn default() -> SigningSettings<'key>

Returns the “default value” for a type.