Skip to main content

Sign Apple binaries with SMCTL using CryptoTokenKit

DigiCert​​®​​ Software Trust Manager CryptoTokenKit (CTK) stores your keys remotely in DigiCert​​®​​ Software Trust Manager when you sign. The CTK integrates with codesign and product sign (signing tools provided as part of the MacOS) while maintaining key protection, permission-based access and reporting all signing activities.

Follow these instructions to sign Apple binaries with productsign and codesign using Software Trust Manager command line interface (SMCTL) while your keys are stored in Software Trust Manager. Alternatively, you can sign your Apple files directly with codesign and productsign while your keys are stored in our CryptotokenKit.

How does SMCTL simplify signing?

Below are the differences in sign commands:

SMCTL

codesign and productsign

Provide the Software Trust Managerkeypair alias associated with your Apple certificate.

Keypair alias example: Applesign

Provide the ID associated with your Apple certificate.

Apple ID example: DHPK4B64QS

Your keys are automatically added to the token when you sign.

You manually have to add a new token and add the keys you want to sign with.

Prerequisites

Configure client tools

Download and configure these client tools:

重要

Compatibility issue

OpenSSL 3.x changed their default algorithm. This new algorithm is not compatible with macOS SSL libraries starting from Ventura OS. This issue affects Apple Keychain's ability to read DigiCert ONE client authentication certificates (cert.12) because it relies on LibreSSL. See solution.

Apple certificates

The following Apple certificates are required to sign these files with CodeSign and ProductSign.

Apple certificate

Signing tool

Files

Developer ID Application

codesign

.app

.dmg

Developer ID Installer

productsign

.pkg

Dryrun signature

To verify if it is possible to sign a file with a specific Apple certificate:

smctl-mac-x64 sign --keypair-alias <keypair alias associated with Apple certificate> --dryrun=true --input <path to file you want to sign>

Command sample:

smctl-mac-x64 sign -k apple_codesign –dryrun=true --input /Users/Name/Downloads/Example.app 

Sign with SMCTL

注意

Use the keypair alias associated with the relevant Apple certificate.

To sign with codesign or productsign using SMCTL and the Cryptokenkit:

smctl-mac-x64 sign --tool <codesign or productsign> --keypair alias <keypair alias> --input <path to unsigned file> --verbose

Command sample:

smctl-mac-x64 sign --tool codesign --keypair alias AppleCodeSign --input /Users/john.doe/downloads/example.app --verbose

Verify signature with SMCTL

To verify that your file was signed:

smctl-mac-x64 sign verify --verbose --input <path to signed file>

Command sample:

smctl-mac-x64 sign verify --verbose=true --input /Users/John.Doe/Downloads/test.pkg

SMCTL flags for codesign and productsign

These flags may be useful when using codesign and productsign related commands.

1. Flags for Apple signing

Shortcut

Flag

Description

--all-metadata

Capture all signature metadata. Default is to capture all metadata.

--checksum-after-signing

Capture the checksum in the signature metadata after signing the file. Leave blank to capture by default.

--checksum-before-signing

Capture the checksum in the signature metadata before signing the file. Leave blank to capture by default.

--digicert-ctk-app-path string

Provide the path to DigiCert SSM Signing Clients.app (CryptoTokenKit).

注意

This flag only applies to Apple codesign and productsign commands.

--digicert-ctk-cli-path string

Provide the path to DigiCert SSM Signing Clients.app (CryptoTokenKit) CLI.

注意

This flag only applies to Apple codesign and productsign commands.

-d

--digalg string

Specify the digest algorithm to use for signing (default based on the tool used for signing). 

Format:

--digalg="<value>"

--digest-algorithm

Capture the digest algorithm in the signature metadata. Leave blank to capture by default.

--entitlements-file-path

Specify the entitlements file path.

注意

This flag only applies to Apple codesign commands.

--file-location

Capture the file location in the signature metadata. Leave blank to capture by default.

--file-name

Capture the file name in the signature metadata. Leave blank to capture by default.

--force

Replace existing signatures (default value 'true').

注意

This flag only applies to Apple codesign commands.

--deep

Sign all internal frameworks and plugins (default value 'true').

注意

This flag only applies to Apple codesign commands.

--dryrun

Verify if the file can be signed without actually signing it (default value 'false').

注意

This flag only applies to Apple codesign commands.

--identity string

Specify the apple developer or installer certificate that you will use to sign with. This information can be found using security export-smartcard.

注意

This flag only applies to Apple codesign commands, after the key is added to the token.

-i

--input string

Provide the path to the file or folder to be signed. If you specify a folder, all files inside the folder will be signed.

Format:

--input="<path to file or folder>"

-k

--keypair-alias string

Keypair alias to be used for signing. 

Format:

--keypair-alias="<Software Trust Manager keypair aloas>"

--output-file

Signed package file (should be different than input file)

注意

This flag is compulsory for Apple productsign.

--preserve-metadata

Preserve the metadata.

注意

This flag only applies to Apple codesign commands.

-s

--sigalg string

Signature algorithm to use (default based on the tool used for signing). 

Format:

--sigalg="<value>"

--signing-tool

Capture the signing tool in the signature metadata. Leave blank to capture by default.

--timestamp

Enable or disable timestamp. Default is enabled.

--timestamp-flag

Capture the timestamp in the signature metadata. Leave blank to capture by default.

-t

--tool string

Specify the tool to use for signing (leave it blank to sign with the default signing tool based on the file extension).

Format:

--tool="<codesign or productsign>"

--tsa-url

Capture the timestamp (TSA) URL in the signature metadata. Leave blank to capture by default.

-v

--verbose

Verbose logging for signing.

-h

--help

Help for signing.


Command examples

Description: Codesign a .app file using the keypair alias of the Apple certificate.

Command:

smctl-mac-x64 sign --keypair-alias <keypair alias associated with Apple certificate> --input <path to.app or .dmg_file_to_be_signed>

Command sample:

smctl-mac-x64 sign -k apple_codesign --verbose=true --input /Users/Name/Downloads/Example.app

Description: Verify if the file can be signed using codesign without signing.

Command:

smctl-mac-x64 sign --keypair-alias <keypair alias associated with Apple certificate> --verbose=true --dryrun=true --input <path to .app or .dmg file>

Command sample:

smctl-mac-x64 sign -k apple_codesign --verbose=true –dryrun=true --input /Users/Name/Downloads/Example.app 

Description: Verify if .app file was signed.

Command:

smctl-mac-x64 sign verify --input <path to signed .app or .dmg file>

Command sample

smctl-mac-x64 sign verify --input /Users/Name/Downloads/Example.app

Description: Sign .pkg file using productsign.

Command:

smctl-mac-x64 sign  --keypair-alias < keypair_alias of apple certificate > --verbose  --input <path .pkg file to be signed>

Command sample:

smctl-mac-x64 sign -k apple_installer_productsign --verbose=true --input /Users/Name/Downloads/test.pkg 

Description: Verify if .pkg file was signed.

Command:

smctl-mac-x64 sign verify --verbose --input <path to signed .pkg file>

Command sample

smctl-mac-x64 sign verify --verbose=true --input /Users/Name/Downloads/test.pkg