axiom-code-signing-ref

Code Signing API Reference

Comprehensive CLI and API reference for iOS/macOS code signing: certificate management, provisioning profile inspection, entitlement extraction, Keychain operations, codesign verification, fastlane match, and Xcode build settings.

Quick Reference

# Diagnostic flow — run these 3 commands first for any signing issue
security find-identity -v -p codesigning          # List valid signing identities
security cms -D -i path/to/embedded.mobileprovision  # Decode provisioning profile
codesign -d --entitlements - MyApp.app             # Extract entitlements from binary

---

Certificate Reference

Certificate Types

Type	Purpose	Validity	Max Per Account
Apple Development	Debug builds on registered devices	1 year	Unlimited (per developer)
Apple Distribution	App Store + TestFlight submission	1 year	3 per account
iOS Distribution (legacy)	App Store submission (pre-Xcode 11)	1 year	3 per account
iOS Development (legacy)	Debug builds (pre-Xcode 11)	1 year	Unlimited
Developer ID Application	macOS distribution outside App Store	5 years	5 per account
Developer ID Installer	macOS package signing	5 years	5 per account
Apple Push Services	APNs .p12 certificate auth (legacy)	1 year	1 per App ID

CSR Generation

# Generate Certificate Signing Request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout CertificateSigningRequest.key \
  -out CertificateSigningRequest.certSigningRequest \
  -subj "/emailAddress=dev@example.com/CN=Developer Name/C=US"

Or use Keychain Access: Certificate Assistant → Request a Certificate From a Certificate Authority.

Certificate Inspection

# View certificate details (from .cer file)
openssl x509 -in certificate.cer -inform DER -text -noout

# View certificate from .p12
openssl pkcs12 -in certificate.p12 -nokeys -clcerts | openssl x509 -text -noout

# List certificates in Keychain with SHA-1 hashes
security find-identity -v -p codesigning

# Example output:
#   1) ABC123... "Apple Development: dev@example.com (TEAMID)"
#   2) DEF456... "Apple Distribution: Company Name (TEAMID)"
#      2 valid identities found

# Find specific certificate by name
security find-certificate -c "Apple Distribution" login.keychain-db -p

# Check certificate expiration (pipe PEM output to openssl)
security find-certificate -c "Apple Distribution" login.keychain-db -p | openssl x509 -noout -enddate

Certificate Installation

# Import .p12 into Keychain (interactive — prompts for password)
security import certificate.p12 -k ~/Library/Keychains/login.keychain-db -P "$P12_PASSWORD" -T /usr/bin/codesign

# Import .cer into Keychain
security import certificate.cer -k ~/Library/Keychains/login.keychain-db

# For CI: import into temporary keychain (see CI section below)

---

Provisioning Profile Reference

Profile Types

Type	Contains	Use Case
Development	Dev cert + device UDIDs + App ID + entitlements	Debug builds on registered devices
Ad Hoc	Distribution cert + device UDIDs + App ID + entitlements	Testing on specific devices without TestFlight
App Store	Distribution cert + App ID + entitlements (no device list)	App Store + TestFlight submission
Enterprise	Enterprise cert + App ID + entitlements (no device list)	In-house distribution (Enterprise program only)

Profile Contents

A provisioning profile (.mobileprovision) is a signed plist containing:

├── AppIDName           — App ID name
├── ApplicationIdentifierPrefix  — Team ID
├── CreationDate        — When profile was created
├── DeveloperCertificates  — Embedded signing certificates (DER-encoded)
├── Entitlements        — Granted entitlements
│   ├── application-identifier
│   ├── aps-environment (development|production)
│   ├── com.apple.developer.associated-domains
│   ├── keychain-access-groups
│   └── ...
├── ExpirationDate      — When profile expires (1 year)
├── Name                — Profile name in Apple Developer Portal
├── ProvisionedDevices  — UDIDs (Development/Ad Hoc only)
├── TeamIdentifier      — Team ID array
├── TeamName            — Team display name
├── TimeToLive          — Days until expiration
├── UUID                — Unique profile identifier
└── Version             — Profile version (1)

Decode Provisioning Profile

# Decode and display full contents
security cms -D -i path/to/embedded.mobileprovision

# Extract specific fields
security cms -D -i embedded.mobileprovision | plutil -extract Entitlements xml1 -o - -

# Check aps-environment (push notifications)
security cms -D -i embedded.mobileprovision | grep -A1 "aps-environment"

# Check expiration
security cms -D -i embedded.mobileprovision | grep -A1 "ExpirationDate"

# List provisioned devices (Development/Ad Hoc only)
security cms -D -i embedded.mobileprovision | grep -A100 "ProvisionedDevices"

# Check team ID
security cms -D -i embedded.mobileprovision | grep -A1 "TeamIdentifier"

Profile Installation Paths

# Installed profiles (Xcode manages these)
~/Library/MobileDevice/Provisioning Profiles/

# List installed profiles
ls ~/Library/MobileDevice/Provisioning\ Profiles/

# Decode a specific installed profile
security cms -D -i ~/Library/MobileDevice/Provisioning\ Profiles/<UUID>.mobileprovision

# Find profile embedded in app bundle
find ~/Library/Developer/Xcode/DerivedData -name "embedded.mobileprovision" -newer . 2>/dev/null | head -5

# Install a profile manually (copy to managed directory)
cp MyProfile.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/

---

Entitlements Reference

Common Entitlements

Entitlement	Key	Values
App ID	application-identifier	TEAMID.com.example.app
Push Notifications	aps-environment	development / production
App Groups	com.apple.security.application-groups	["group.com.example.shared"]
Keychain Sharing	keychain-access-groups	["TEAMID.com.example.keychain"]
Associated Domains	com.apple.developer.associated-domains	["applinks:example.com"]
iCloud	com.apple.developer.icloud-container-identifiers	Container IDs
HealthKit	com.apple.developer.healthkit	true
Apple Pay	com.apple.developer.in-app-payments	Merchant IDs
Network Extensions	com.apple.developer.networking.networkextension	Array of types
Siri	com.apple.developer.siri	true
Sign in with Apple	com.apple.developer.applesignin	["Default"]

Entitlement .plist Format

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>aps-environment</key>
    <string>development</string>
    <key>com.apple.security.application-groups</key>
    <array>
        <string>group.com.example.shared</string>
    </array>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>applinks:example.com</string>
    </array>
</dict>
</plist>

Extraction and Comparison

# Extract entitlements from signed app binary
codesign -d --entitlements - /path/to/MyApp.app

# Extract to file for comparison
codesign -d --entitlements entitlements.plist /path/to/MyApp.app

# Compare entitlements between app and provisioning profile
diff <(codesign -d --entitlements - MyApp.app 2>/dev/null) \
     <(security cms -D -i embedded.mobileprovision | plutil -extract Entitlements xml1 -o - -)

# Extract entitlements from .ipa
unzip -o MyApp.ipa -d /tmp/ipa_contents
codesign -d --entitlements - /tmp/ipa_contents/Payload/*.app

# Verify entitlements match between build and profile
codesign -d --entitlements - --xml MyApp.app  # XML format

---

CLI Command Reference

security Commands

# --- Identity & Certificate ---

# List valid code signing identities
security find-identity -v -p codesigning
# -v: valid only, -p codesigning: code signing policy

# Find certificate by common name
security find-certificate -c "Apple Distribution" login.keychain-db -p
# -c: common name substring, -p: output PEM, keychain is positional arg

# Find certificate by SHA-1 hash
security find-certificate -Z -a login.keychain-db | grep -B5 "ABC123"

# --- Import/Export ---

# Import .p12 (with password, allow codesign access)
security import certificate.p12 -k login.keychain-db -P "$PASSWORD" -T /usr/bin/codesign -T /usr/bin/security

# Import .cer
security import certificate.cer -k login.keychain-db

# Export certificate to .p12
security export -t identities -f pkcs12 -k login.keychain-db -P "$PASSWORD" -o exported.p12

# --- Provisioning Profile Decode ---

# Decode provisioning profile (CMS/PKCS7 signed plist)
security cms -D -i embedded.mobileprovision

# --- Keychain Management ---

# Create temporary keychain (for CI)
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain

# Set as default keychain
security default-keychain -s build.keychain

# Add to search list (required for codesign to find certs)
security list-keychains -d user -s build.keychain login.keychain-db

# Unlock keychain (required in CI before signing)
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain

# Set keychain lock timeout (0 = never lock during session)
security set-keychain-settings -t 3600 -l build.keychain
# -t: timeout in seconds, -l: lock on sleep

# Allow codesign to access keys without UI prompt (critical for CI)
security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" build.keychain

# Delete keychain (CI cleanup)
security delete-keychain build.keychain

codesign Commands

# --- Signing ---

# Sign with specific identity
codesign -s "Apple Distribution: Company Name (TEAMID)" MyApp.app
# -s: signing identity (name or SHA-1 hash)

# Sign with entitlements file
codesign -s "Apple Distribution" --entitlements entitlements.plist MyApp.app

# Force re-sign (overwrite existing signature)
codesign -f -s "Apple Distribution" MyApp.app

# Sign with timestamp (required for notarization)
codesign -s "Developer ID Application" --timestamp MyApp.app

# Deep sign (sign all nested code — frameworks, extensions)
codesign --deep -s "Apple Distribution" MyApp.app
# Warning: --deep is unreliable for complex apps. Sign each component individually.

# --- Verification ---

# Verify signature is valid
codesign --verify --verbose=4 MyApp.app

# Verify deep (check nested code)
codesign --verify --deep --strict MyApp.app

# Display signing information
codesign -dv MyApp.app
# Shows: Identifier, Format, TeamIdentifier, Signing Authority chain

# Display verbose signing info
codesign -dvvv MyApp.app

# Extract entitlements from signed binary
codesign -d --entitlements - MyApp.app
codesign -d --entitlements - --xml MyApp.app  # XML format

openssl Commands

Note: macOS ships with LibreSSL, not OpenSSL. Some openssl pkcs12 commands may fail with "MAC verification failed" on stock macOS. Install OpenSSL via brew install openssl if needed, then use the full path (/opt/homebrew/opt/openssl/bin/openssl).

# --- Certificate Inspection ---

# View .cer details
openssl x509 -in certificate.cer -inform DER -text -noout

# View .pem details
openssl x509 -in certificate.pem -text -noout

# Check certificate expiration
openssl x509 -in certificate.cer -inform DER -noout -enddate

# Extract public key
openssl x509 -in certificate.cer -inform DER -pubkey -noout

# --- PKCS12 (.p12) ---

# Extract certificate from .p12
openssl pkcs12 -in certificate.p12 -nokeys -clcerts -out cert.pem

# Extract private key from .p12
openssl pkcs12 -in certificate.p12 -nocerts -nodes -out key.pem

# Create .p12 from cert + key
openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.p12

# Verify .p12 contents
openssl pkcs12 -info -in certificate.p12 -nokeys

---

Xcode Build Settings Reference

Setting	Key	Values
Code Signing Style	CODE_SIGN_STYLE	Automatic / Manual
Signing Identity	CODE_SIGN_IDENTITY	Apple Development / Apple Distribution / iPhone Distribution
Development Team	DEVELOPMENT_TEAM	Team ID (10-char alphanumeric)
Provisioning Profile	PROVISIONING_PROFILE_SPECIFIER	Profile name or UUID
Provisioning Profile (legacy)	PROVISIONING_PROFILE	Profile UUID (deprecated, use SPECIFIER)
Other Code Signing Flags	OTHER_CODE_SIGN_FLAGS	--timestamp / --options runtime
Code Sign Entitlements	CODE_SIGN_ENTITLEMENTS	Path to .entitlements file
Enable Hardened Runtime	ENABLE_HARDENED_RUNTIME	YES / NO (macOS)

xcodebuild Signing Overrides

# Automatic signing
xcodebuild -scheme MyApp -configuration Release \
  CODE_SIGN_STYLE=Automatic \
  DEVELOPMENT_TEAM=YOURTEAMID

# Manual signing
xcodebuild -scheme MyApp -configuration Release \
  CODE_SIGN_STYLE=Manual \
  CODE_SIGN_IDENTITY="Apple Distribution: Company Name (TEAMID)" \
  PROVISIONING_PROFILE_SPECIFIER="MyApp App Store Profile"

# Archive for distribution
xcodebuild archive -scheme MyApp \
  -archivePath build/MyApp.xcarchive \
  CODE_SIGN_STYLE=Manual \
  CODE_SIGN_IDENTITY="Apple Distribution" \
  PROVISIONING_PROFILE_SPECIFIER="MyApp App Store"

# Export .ipa from archive
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath build/ipa

ExportOptions.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>teamID</key>
    <string>YOURTEAMID</string>
    <key>signingStyle</key>
    <string>manual</string>
    <key>signingCertificate</key>
    <string>Apple Distribution</string>
    <key>provisioningProfiles</key>
    <dict>
        <key>com.example.myapp</key>
        <string>MyApp App Store Profile</string>
    </dict>
    <key>uploadSymbols</key>
    <true/>
</dict>
</plist>

Export method values: app-store, ad-hoc, enterprise, development, developer-id.

---

fastlane match Reference

Setup

# Initialize match (interactive — choose storage type)
fastlane match init
# Options: git, google_cloud, s3, azure_blob

# Generate certificates + profiles for all types
fastlane match development
fastlane match appstore
fastlane match adhoc

Matchfile

# fastlane/Matchfile
git_url("https://github.com/your-org/certificates.git")
storage_mode("git")

type("appstore")  # Default type

app_identifier(["com.example.app", "com.example.app.widget"])
username("dev@example.com")
team_id("YOURTEAMID")

# For multiple targets with different profiles
# for_lane(:beta) do
#   type("adhoc")
# end

Usage

# Generate or fetch development certs + profiles
fastlane match development

# Generate or fetch App Store certs + profiles
fastlane match appstore

# CI: read-only mode (never create, only fetch)
fastlane match appstore --readonly

# Force regenerate (revokes existing)
fastlane match nuke distribution  # Revoke all distribution certs
fastlane match appstore           # Generate fresh
# Also: nuke development, nuke enterprise

Environment Variables for CI

MATCH_GIT_URL="https://github.com/your-org/certificates.git"
MATCH_PASSWORD="encryption_password"       # Encrypts the repo
MATCH_KEYCHAIN_NAME="fastlane_tmp"
MATCH_KEYCHAIN_PASSWORD="keychain_password"
MATCH_READONLY="true"                      # CI should never create certs
FASTLANE_USER="dev@example.com"
FASTLANE_TEAM_ID="YOURTEAMID"

CI Fastfile Example

# fastlane/Fastfile
lane :release do
  setup_ci  # Creates temporary keychain

  match(
    type: "appstore",
    readonly: true,  # Critical: never create certs in CI
    keychain_name: "fastlane_tmp",
    keychain_password: ""
  )

  build_app(
    scheme: "MyApp",
    export_method: "app-store"
  )

  upload_to_app_store(skip_metadata: true, skip_screenshots: true)
end

---

Keychain Management for CI

Complete CI Keychain Setup Script

#!/bin/bash
set -euo pipefail

KEYCHAIN_NAME="ci-build.keychain-db"
KEYCHAIN_PASSWORD="ci-temporary-password"

# 1. Create temporary keychain
security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"

# 2. Add to search list (MUST include login.keychain-db or it disappears)
security list-keychains -d user -s "$KEYCHAIN_NAME" login.keychain-db

# 3. Unlock keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"

# 4. Prevent keychain from locking during build
security set-keychain-settings -t 3600 -l "$KEYCHAIN_NAME"

# 5. Import signing certificate
security import "$P12_PATH" -k "$KEYCHAIN_NAME" -P "$P12_PASSWORD" \
  -T /usr/bin/codesign -T /usr/bin/security

# 6. Allow codesign access without UI prompt (CRITICAL)
# Without this, CI gets errSecInternalComponent
security set-key-partition-list -S apple-tool:,apple: -s \
  -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_NAME"

echo "Keychain ready for code signing"

CI Keychain Cleanup Script

#!/bin/bash
# Run in CI post-build (always, even on failure)

KEYCHAIN_NAME="ci-build.keychain-db"

# Delete temporary keychain
security delete-keychain "$KEYCHAIN_NAME" 2>/dev/null || true

# Restore default keychain search list
security list-keychains -d user -s login.keychain-db

GitHub Actions Example

- name: Install signing certificate
  env:
    P12_BASE64: ${{ secrets.P12_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
    PROVISION_PROFILE_BASE64: ${{ secrets.PROVISION_PROFILE_BASE64 }}
  run: |
    # Decode certificate
    echo "$P12_BASE64" | base64 --decode > certificate.p12

    # Decode provisioning profile
    echo "$PROVISION_PROFILE_BASE64" | base64 --decode > profile.mobileprovision

    # Create and configure keychain
    security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
    security list-keychains -d user -s build.keychain login.keychain-db
    security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
    security set-keychain-settings -t 3600 -l build.keychain
    security import certificate.p12 -k build.keychain -P "$P12_PASSWORD" \
      -T /usr/bin/codesign -T /usr/bin/security
    security set-key-partition-list -S apple-tool:,apple: -s \
      -k "$KEYCHAIN_PASSWORD" build.keychain

    # Install provisioning profile
    mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
    cp profile.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/

- name: Cleanup keychain
  if: always()
  run: security delete-keychain build.keychain 2>/dev/null || true

Xcode Cloud

Xcode Cloud manages signing automatically:

• Certificates are managed by Apple — no manual cert management needed
• Provisioning profiles are fetched from Developer Portal
• Configure signing in Xcode → cloud workflow settings
• Use ci_post_clone.sh for custom keychain operations if needed

---

APNs Authentication: .p8 vs .p12

Aspect	.p8 (Token-Based)	.p12 (Certificate-Based)
Validity	Never expires (revoke to invalidate)	1 year (must renew annually)
Scope	All apps in team	Single App ID
Max per team	2 keys	1 cert per App ID
Setup complexity	Lower (one key for all apps)	Higher (per-app certificate)
Server implementation	JWT token generation required	TLS client certificate
Recommended	Yes (Apple's current recommendation)	Legacy (still supported)

.p8 Key Usage

# Generate JWT for APNs (simplified — use a library in production)
# Header: {"alg": "ES256", "kid": "KEY_ID"}
# Payload: {"iss": "TEAM_ID", "iat": TIMESTAMP}
# Sign with .p8 private key

# JWT is valid for 1 hour — cache and refresh before expiry

.p12 Certificate Usage

# Send push with certificate authentication
curl -v \
  --cert-type P12 --cert apns-cert.p12:password \
  --header "apns-topic: com.example.app" \
  --header "apns-push-type: alert" \
  --data '{"aps":{"alert":"Hello"}}' \
  --http2 https://api.sandbox.push.apple.com/3/device/$TOKEN
# Production: https://api.push.apple.com/3/device/$TOKEN

---

Error Codes Reference

security Command Errors

Error	Code	Cause
errSecInternalComponent	-2070	Keychain locked or set-key-partition-list not called
errSecItemNotFound	-25300	Certificate/key not in searched keychains
errSecDuplicateItem	-25299	Certificate already exists in keychain
errSecAuthFailed	-25293	Wrong keychain password
errSecInteractionNotAllowed	-25308	Keychain locked, no UI available (CI without unlock)
errSecMissingEntitlement	-34018	App missing required entitlement for keychain access

codesign Errors

Error	Cause	Fix
No signing certificate found	No valid identity in keychain	Import cert or check expiration
ambiguous (matches ...)	Multiple matching identities	Specify full identity name or SHA-1 hash
not valid for use in ...	Cert type mismatch (dev vs dist)	Use correct certificate type
a sealed resource is missing or invalid	Modified resources after signing	Re-sign after all modifications
invalid signature (code or signature have been modified)	Binary tampered post-signing	Re-sign or rebuild

ITMS (App Store Upload) Errors

Code	Error	Cause	Fix
ITMS-90035	Invalid Signature	Wrong certificate type or expired cert	Sign with valid Apple Distribution cert
ITMS-90161	Invalid Provisioning Profile	Profile doesn't match app	Regenerate profile in Developer Portal
ITMS-90046	Invalid Code Signing Entitlements	Entitlements not in profile	Add capability in portal, regenerate profile
ITMS-90056	Missing Push Notification Entitlement	aps-environment not in profile	Enable Push Notifications capability
ITMS-90174	Missing Provisioning Profile	No profile embedded	Archive with correct signing settings
ITMS-90283	Invalid Provisioning Profile	Profile expired	Download fresh profile
ITMS-90426	Invalid Swift Support	Swift libraries not signed correctly	Use Xcode's organizer to export (not manual)
ITMS-90474	Missing Bundle Identifier	Bundle ID doesn't match profile	Align bundle ID across Xcode, portal, and profile
ITMS-90478	Invalid Team ID	Team ID mismatch	Verify DEVELOPMENT_TEAM build setting
ITMS-90717	Invalid App Store Distribution Certificate	Using Development cert for App Store	Switch to Apple Distribution certificate

Resources

WWDC: 2021-10204, 2022-110353

Docs: /security, /bundleresources/entitlements, /xcode/distributing-your-app

Skills: axiom-code-signing, axiom-code-signing-diag