How to Use YubiKey for Mac Code Signing?

Code signing is a critical step in securing and distributing macOS applications. It assures users that your software comes from a verified source and hasn’t been tampered with. In the Apple ecosystem, Gatekeeper and notarization further enforce the trustworthiness of apps.

However, code signing certificates and private keys are high-value assets. If compromised, they could be misused to distribute malicious software under your identity. That’s where hardware security modules (HSMs) like YubiKey come into play. This guide walks you through the process of using a YubiKey to securely sign code on macOS.

Understanding the Need for Secure Code Signing

The Risk of Key Compromise

Private keys stored on disk are vulnerable to malware, accidental leaks, or insider threats. If an attacker gains access to your key, they can sign malicious code, bypassing Apple’s defenses.

Apple’s Security Requirements

macOS enforces strict app verification through Gatekeeper and notarization. Code must be signed and optionally notarized to run smoothly on user systems. Apple also checks for revoked or suspicious certificates.

Benefits of YubiKey for Code Signing

YubiKey stores private keys in tamper-resistant hardware. Keys never leave the device, drastically reducing the risk of theft. This makes it a trusted option for securing sensitive credentials like code signing certificates.

What is YubiKey and How It Works

YubiKey is a hardware security token from Yubico that supports a variety of authentication and encryption protocols. For code signing, we leverage its PIV (Personal Identity Verification) smart card mode, which allows the device to act like a secure key container.

Supported Algorithms

• RSA 2048 / 3072 / 4096
• ECC P-256 / P-384

Smart Card Mode

macOS can communicate with YubiKey as a smart card using tools like OpenSC. This enables code signing utilities to access the certificate stored on the YubiKey without directly exposing the private key.

The Basic Requirements

Hardware

• YubiKey 5 Series or other models supporting PIV and RSA/ECC keys.

Software

• YubiKey Manager (ykman): For configuring the device.
• yubico-piv-tool: For key generation and certificate management.
• OpenSC: Middleware enabling Keychain integration.
• Xcode Command Line Tools: Includes the codesign and security

Apple Developer Account

You’ll need a valid Developer ID certificate from Apple to sign macOS apps.

Configuring YubiKey for macOS Code Signing

Setting Up PIV Applet

1. Plug in your YubiKey.
2. Set or change the Management Key and PIN using ykman or yubico-piv-tool.

ykman piv access change-pin

ykman piv access change-management-key

Generating or Importing a Key Pair

Option 1: Generate Key on YubiKey (Recommended)

yubico-piv-tool -s 9a -A RSA2048 -a generate -o pubkey.pem

Option 2: Import Existing Key

If you must use a pre-generated key:

yubico-piv-tool -s 9a -a import-key -i private-key.pem

Creating and Submitting a CSR

yubico-piv-tool -s 9a -a request-certificate -S "/CN=Your Name/OU=Developer/O=YourOrg/C=US" -i pubkey.pem -o cert.csr

Submit this CSR to Apple or your certificate authority (CA). Once issued, import the certificate:

yubico-piv-tool -s 9a -a import-certificate -i dev_id_cert.pem

Integrating YubiKey with macOS Code Signing

Keychain Access

Install and configure OpenSC so macOS recognizes YubiKey as a smart card:

brew install opensc

Ensure the smart card is visible in Keychain Access under “My Certificates.”

Signing Code

Use codesign to sign your app:

codesign --sign "Common Name from Certificate" --deep --force /path/to/your.app

macOS will prompt for the YubiKey PIN when the signing operation occurs.

Verifying the Signature

codesign --verify --verbose /path/to/your.app

spctl --assess --type execute --verbose /path/to/your.app

Notarization with YubiKey

Signing Before Notarization

Ensure your app is signed with the Developer ID certificate stored on your YubiKey.

Submitting to Notary Service

xcrun notarytool submit /path/to/your.app --apple-id your@apple.com --team-id TEAMID --password app-specific-password

Stapling the Ticket

xcrun stapler staple /path/to/your.app

Security Best Practices

• Use PIN Protection: Set a strong PIN and limit retry attempts.
• Keep Firmware Updated: Check for YubiKey updates.
• Create a Backup Key: In case of loss or failure.
• Restrict Access: Use only on secure, trusted systems.
• Monitor Usage: Audit signing operations to detect anomalies.