Skip to main content

Apple commands, certificate types, and troubleshooting

There are two commands to sign all types of recognized Apple binaries. You will need to identify the Apple certificate's Distinguished Name (DN) or the SHA-1 fingerprint to execute these commands.

When “Apple certificate identifier” is used as a placeholder in a command, you can use either the subject DN or SHA-1 fingerprint of the Apple certificate.

Nota

If you have more than one certificate with the same DN, use the SHA-1 fingerprint instead of the DN to run the following commands.

How do I locate the subject DN? The certificate’s DN is listed in the "labl" field under the "Private key" section, after running the export command.

The certificate’s DN is referred to as “Apple Identity” for codesign and “Apple Developer ID” for productsign commands below.

How do I locate the certificate’s SHA-1 fingerprint? The SHA-1 fingerprint is listed in the "Sha1" field under "certificate" section, after running the export command.

codesign

The codesign command is used to sign .app and .dmg extensions.

Codesign command

Codesign command codesign [--entitlements entitlements.xml] [--deep] [--force] [--verify] [--verbose] --sign "<Apple certificate identifier>" --options runtime "<Path to .app or .dmg file>"

Codesign using Distinguished Name (DN)

To sign using the Apple certificate's DN:

codesign -v -s "<Apple certificate DN>" --force "<Path to .app or .dmg file>"

Command sample:

codesign -v -s "Apple Development: DigiCert Inc (85W9468PYV)" --force example.app

Sample response using DN:

example.app: signed app bundle with Mach-O universal (x86_64 arm64) [DigiCert]

Codesign using SHA-1 fingerprint

To sign using SHA-1 fingerprint of the Apple certificate:

codesign -v -s "<SHA-1 fingerprint of Apple certificate>" --force "<Path to .app or .dmg file>"

Command sample:

codesign -v -s "88da70819d87865ae21996cb889d9e60abff7c9d" --force example.app

Command output:

example.app: replacing existing signature  
example.app: signed app bundle with Mach-O universal (x86_64 arm64) [DigiCert]

productsign

Use the productsign command to sign .pkg and .dmg file extensions, which indicate Apple application installers and release binary distributables via Apple Mac app store, respectively.

Nota

Use your system login password if you receive a private key permission pop-up when attempting to sign for the first time.

productsign command

productsign –sign “<Apple certificate identifier>” <Path to .pkg file> <Path to store signed file>

Productsign using Distinguished Name (DN)

To sign using the Apple certificate's DN:

productsign --sign "<Apple certificate DN>" <Path to .pkg file> <Path to store signed file>

Command sample:

productsign --sign "Developer ID Installer: DigiCert Inc (DHPK4B64QS)" UNSIGNED_PKG.pkg SIGNED_PKG.pkg

Sample response using DN:

productsign: using timestamp authority for signature
productsign: signing product with identity "Developer ID Installer: DigiCert Inc (DHPK4B64QS)" from keychain (null)
productsign: adding certificate "Developer ID Certification Authority"
productsign: adding certificate "Apple Root CA"
productsign: Wrote signed product archive to SIGNED_PKG.pkg

Productsign using SHA-1 fingerprint

To sign using SHA-1 fingerprint of the Apple certificate:

digicert@DC-C02TK34HGTDY Downloads % productsign --sign "<SHA-1 fingerprint of Apple certificate>" <Path to .pkg file> <Path to store signed file>

Command sample:

digicert@DC-C02TK34HGTDY Downloads % productsign --sign "1e50029693922d2f7efcf75488189c49ed3bf0bb" UNSIGNED_PKG.pkg SIGNED_PKG.pkg

Command output:

productsign: using timestamp authority for signature  
productsign: signing product with identity "Developer ID Installer: DigiCert Inc (DHPK4B64QS)" from keychain (null)  
productsign: adding certificate "Developer ID Certification Authority"  
productsign: adding certificate "Apple Root CA"  
productsign: Wrote signed product archive to SIGNED_PKG.pkg

Apple certificate types and associated commands

Select the Apple certificate type based on the type of files you wish to sign with. The certificate type helps to identify a certificate in your developer account and account preferences.

The signing will fail if you order the incorrect certificate type from Apple and use a signing command that is unassociated with the certificate type.

tabla 1. Apple certificate types and commands

Type

Purpose

Associated command

Mac Installer Distribution

Sign and submit a Mac Installer Package, containing your signed app, to the Mac App Store.

Compatible with productsign command.

Developer ID Application

Sign a macOS app before distributing it outside the Mac App Store.

Compatible with codesign command.

Developer ID Installer

Sign and distribute a Mac Installer Package, containing your signed app, outside the Mac App Store.

Compatible with productsign command.

APNs Auth Key

Generate server-side tokens as an alternative to certificates for your notification requests.

Not applicable

Apple Push Services

Establish connectivity between your notification service and APNs to deliver remote notifications to your app.

Not applicable

Apple Development

For iOS, tvOS, or watchOS apps, run the app on devices and use app services during development. For macOS apps, use app services during development and testing. Note: Available in Xcode 11.0 and later. For earlier Xcode versions, use an iOS Development or Mac Development certificate.

Not applicable

Apple Distribution

For iOS, tvOS, or watchOS apps, run the app on designated devices for testing or submit it to the App Store. For macOS apps, sign an app before distributing it through the Mac App Store. Note: Available in Xcode 11.0 and later. For earlier Xcode versions, use an iOS Distribution or Mac App Distribution certificate.

Not applicable

Apple Pay

Decrypt app transaction data sent by Apple to a merchant/developer.

Not applicable

Merchant Identity

Authenticate you to Apple Pay Servers.

Not applicable

Pass Type ID

Sign and send updates to passes in Wallet.

Not applicable

VoIP Services

Establish connectivity between your notification server and APNs to alert background VoIP apps of incoming activity.

Not applicable

WatchKit Services

Establish connectivity between your notification server and APNs to update ClockKit complication data.

Not applicable

Website Push ID

Sign and send updates for Websites. Note: In your keychain, the certificate name contains a hint to the type, and includes the team name and Team ID. The development certificate name includes your name and Member ID.

Not applicable


Apple signing errors and solutions

The following errors may occur during Apple signing.

No identity found

Error message:

88 da 70 81 9d 87 86 5a e2 19 96 cb 88 9d 9e 60 ab ff 7c 9d: no identity found

Description:

This error is caused if the spaces were not removed when using the SHA-1 fingerprint in the signing command.

Solution:

Remove the spaces in the SHA-1 fingerprint in the signing command.

Could not find appropriate signing identity

Error message:

Could not find appropriate signing identity for "Developer ID Installer: Example Inc (DHPK4B64QS)

Description:

This error occurs when you use the productsign command and reference an incompatible certificate.

Solution:

Use a compatible certificate (Mac Installer Distribution or Developer ID Installer) in the productsign command.

This identity cannot be used for signing code

Error message:

Developer ID Installer: Example Inc (DHPK4B64QS): this identity cannot be used for signing code

Description:

This error occurs when you use the codesign command and reference an incompatible certificate.

Solution:

Use a compatible certificate (Developer ID Application) in the codesign command.

TokenExtension not connected

The pluginkit command should show the Secure Software Manager TokenExtension driver after starting the Digicert SSM Signing Clients.app. If it does not:

  1. Delete the Digicert SSM Signing Clients.app.

    1. Reinstall Digicert SSM Signing Clients.app.

    2. Restart your MacOS and retry the pluginkit command .

  2. Remove the TokenExtension driver manually using:

    pluginkit -r “/Applications/Digicert SSM Signing Clients.app/Contents/PlugIns/TokenExtension.appx”

  3. Logs are written with Apple logging framework.

    1. To check the logs for DigiCert SSM Signing Clients:

      log stream | grep Digicert SSM Signing Clients

    2. To check the logs of the token:

      log stream | grep TokenExtension

  4. Run man commands for more details about codesign and productsign.

    1. To see more details about codesign, run:

      man codesign

    2. To see more details about productsign, run:

      man productsign

  5. Make sure the Host, API key, client certificate password, and proxy settings are correct. Look for logs to check for error messages received from server.

Failed to sign hash

Error message:

Logs:

2023-11-16 08:39:08.441813+0000 0x1149     Default     0x4d03               557    0    TokenExtension: (Security) [com.apple.securityd:security_exception] CSSM Exception: -25264 MAC verification failed during PKCS12 import (wrong password?)
2023-11-16 08:39:08.441908+0000 0x1149     Default     0x4d03               557    0    TokenExtension: (SSMAPIClient) Info: SecPKCS12Import status -25264

SMCTL:

User is not multi-factor authenticated. Missing Client Authentication Certificate. As per compliance rules, user needs to be authenticated using multi-factor for performing sign operation.

Description:

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.

Solution:

Use the OpenSSL -legacy flag available on OpenSSL version 3.x to convert your DigiCert ONE client authentication certificate to cert.pem and then convert it into a PKCS#12 certificate which is readable with LibreSSL and therefore compatible with Apple Keychain.

  1. Confirm which OpenSSL version you're using:

    OpenSSL version

    Nota

    If the output is LibreSSL, continue with the steps below on the machine with OpenSSL 3.x installed.

  2. Convert the certificate from .p12 to .pem:

    openssl pkcs12 -in cert.p12 -out cert.pem

  3. Create a new .cert file:

    1. Copy the contents of the .pem file from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.

    2. Paste the contents into a plain text editor or IDE.

    3. Save the file as certname.crt.

  4. Create a new .key:

    1. Copy the contents of the .pem file from -----BEGIN ENCRYPTED PRIVATE KEY----- to -----END ENCRYPTED PRIVATE KEY-----.

    2. Paste the contents into a plain text editor or IDE.

    3. Save the file as encrypted.key.

  5. Decrypt the encrypted .key file:

    openssl rsa -in encrypted.key -out decryptedKey.key

  6. Run the following command to create a certificate file compatible with Ventura and Sonoma OS:

    1. Link the decrypted private key (decryptedKey.key) and its associated X.509 certificate (certname.crt), and export them as a PKCS#12 file (newcert.pfx):

      openssl pkcs12 -inkey decryptedKey.key -in certname.crt -export -legacy -out  newcert.pfx

    2. Save newcert.pfx in the environment variables of the CTK.

    3. Save newcert.pfx password in the environment variables of the CTK.

For these changes to apply and start signing, you must:

  1. Remove the existing token:

    /Applications/DigiCert SSM Signing Clients.app/Contents/MacOS/DigiCert\ SSM\ Signing\ Clients smctl token remove-token

  2. Add a new token:

    /Applications/DigiCert SSM Signing Clients.app/Contents/MacOS/DigiCert\ SSM\ Signing\ Clients smctl token add-token

  3. Move the required keys to the new token:

    /Applications/DigiCert SSM Signing Clients.app/Contents/MacOS/DigiCert\ SSM\ Signing\ Clients smctl keypair add-keys <keypair ID>

Nota

For more information about how to complete these steps, refer to CryptoTokenKit (CTK).

Failed to save configuration to keychain: -25308\

Error message:

Failed to save configuration into Keychain. configurationError(message: "Failed to save configuration to keychain: -25308")
Failed to set environment Veraibles. configurationError(message: "Failed to save configuration into Keychain. configurationError(message: \"Failed to save configuration to keychain: -25308\")")

Description:

This error is occurs when your environment variables cannot be saved to Keychain because one or more variables are incorrect.

Solution:

Use the following macOS "security" command to unlock Keychain and provide the correct variables:

% security unlock-keychain -p <password> ~/Library/Keychains/login.keychain

Atención

This macOS command stores your password in plaintext in your history file (.zsh_history), it is therefore important that you manually erase this line from your history file so that your plaintext password cannot be accessed by others.

Unlocking the Keychain increases your system's vulnerability until it is locked again. Any command typed in the terminal window will be saved in a history file.

Related articles

En esta sección: