axiom-code-signing-ref

コード署名 API リファレンス

iOS/macOS のコード署名に関する包括的な CLI および API リファレンスです。証明書の管理、プロビジョニングプロファイルの検査、エンタイトルメントの抽出、Keychain 操作、codesign の検証、fastlane match、Xcode のビルド設定を扱います。

クイックリファレンス

# 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

---

証明書リファレンス

証明書の種類

種類	用途	有効期間	アカウントあたりの最大数
Apple Development	登録済みデバイスでのデバッグビルド	1 年	無制限（開発者ごと）
Apple Distribution	App Store および TestFlight への提出	1 年	アカウントあたり 3 件
iOS Distribution（レガシー）	App Store への提出（Xcode 11 より前）	1 年	アカウントあたり 3 件
iOS Development（レガシー）	デバッグビルド（Xcode 11 より前）	1 年	無制限
Developer ID Application	App Store 以外での macOS 配布	5 年	アカウントあたり 5 件
Developer ID Installer	macOS パッケージの署名	5 年	アカウントあたり 5 件
Apple Push Services	APNs の .p12 証明書認証（レガシー）	1 年	App ID あたり 1 件

CSR の生成

# Generate Certificate Signing Request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout CertificateSigningRequest.key \
  -out CertificateSigningRequest.certSigningRequest \
  -subj "/[email protected]/CN=Developer Name/C=US"

または、Keychain Access を使用します：Certificate Assistant → Request a Certificate From a Certificate Authority。

証明書の検査

# 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: [email protected] (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

証明書のインストール

# 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)

---

プロビジョニングプロファイルのリファレンス

プロファイルの種類

種類	含まれる内容	用途
Development	開発用証明書 + デバイス UDID + App ID + エンタイトルメント	登録済みデバイスでのデバッグビルド
Ad Hoc	配布用証明書 + デバイス UDID + App ID + エンタイトルメント	TestFlight を使わずに特定のデバイスでテスト
App Store	配布用証明書 + App ID + エンタイトルメント（デバイスリストなし）	App Store および TestFlight への提出
Enterprise	エンタープライズ証明書 + App ID + エンタイトルメント（デバイスリストなし）	社内配布（Enterprise プログラムのみ）

プロファイルの内容

プロビジョニングプロファイル（.mobileprovision）は、署名済み plist で、次の内容が含まれています。

├── 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 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"

プロファイルのインストール先

# 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/

---

エンタイトルメントのリファレンス

一般的なエンタイトルメント

エンタイトルメント	キー	値
App ID	application-identifier	TEAMID.com.example.app
プッシュ通知	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	コンテナ ID
HealthKit	com.apple.developer.healthkit	true
Apple Pay	com.apple.developer.in-app-payments	マーチャント ID
Network Extensions	com.apple.developer.networking.networkextension	種類の配列
Siri	com.apple.developer.siri	true
Sign in with Apple	com.apple.developer.applesignin	["Default"]

エンタイトルメントの .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>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>

抽出と比較

# 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 コマンドリファレンス

security コマンド

# --- 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 コマンド

# --- 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 コマンド

注：macOS には OpenSSL ではなく LibreSSL が付属しています。標準の macOS では、一部の openssl pkcs12 コマンドが「MAC verification failed」で失敗することがあります。必要に応じて brew install openssl で OpenSSL をインストールし、フルパス（/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 ビルド設定リファレンス

設定	キー	値
コード署名方式	CODE_SIGN_STYLE	Automatic ／ Manual
署名 ID	CODE_SIGN_IDENTITY	Apple Development ／ Apple Distribution ／ iPhone Distribution
開発チーム	DEVELOPMENT_TEAM	チーム ID（英数字 10 文字）
プロビジョニングプロファイル	PROVISIONING_PROFILE_SPECIFIER	プロファイル名または UUID
プロビジョニングプロファイル（レガシー）	PROVISIONING_PROFILE	プロファイル UUID（非推奨。SPECIFIER を使用）
その他のコード署名フラグ	OTHER_CODE_SIGN_FLAGS	--timestamp ／ --options runtime
コード署名エンタイトルメント	CODE_SIGN_ENTITLEMENTS	.entitlements ファイルへのパス
Hardened Runtime を有効化	ENABLE_HARDENED_RUNTIME	YES ／ NO（macOS）

xcodebuild の署名オーバーライド

# 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>

エクスポート方式の値：app-store、ad-hoc、enterprise、development、developer-id。

---

fastlane match リファレンス

セットアップ

# 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("[email protected]")
team_id("YOURTEAMID")

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

使用方法

# 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

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="[email protected]"
FASTLANE_TEAM_ID="YOURTEAMID"

CI Fastfile の例

# 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

---

CI 用キーチェーン管理

CI キーチェーンの完全なセットアップスクリプト

#!/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 キーチェーンのクリーンアップスクリプト

#!/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 の例

- 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 は署名を自動的に管理します：

• 証明書は Apple が管理するため、手動で証明書を管理する必要はありません
• プロビジョニングプロファイルは Developer Portal から取得されます
• Xcode → クラウドワークフロー設定で署名を構成します
• 必要に応じて、カスタムキーチェーン操作に ci_post_clone.sh を使用します

---

APNs 認証：.p8 と .p12

項目	.p8（トークンベース）	.p12（証明書ベース）
有効期間	有効期限なし（無効にするには失効させます）	1 年（毎年更新が必要です）
適用範囲	チーム内のすべてのアプリ	単一の App ID
チームごとの最大数	2 個のキー	App ID ごとに 1 個の証明書
セットアップの複雑さ	低い（すべてのアプリで 1 個のキーを使用）	高い（アプリごとに証明書が必要）
サーバー実装	JWT トークンの生成が必要	TLS クライアント証明書
推奨	はい（Apple の現在の推奨方式）	レガシー（引き続きサポートされています）

.p8 キーの使用方法

# 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 証明書の使用方法

# 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

---

エラーコードリファレンス

security コマンドのエラー

エラー	コード	原因
errSecInternalComponent	-2070	キーチェーンがロックされているか、set-key-partition-list が呼び出されていません
errSecItemNotFound	-25300	検索対象のキーチェーンに証明書／キーがありません
errSecDuplicateItem	-25299	証明書はすでにキーチェーンに存在します
errSecAuthFailed	-25293	キーチェーンのパスワードが間違っています
errSecInteractionNotAllowed	-25308	キーチェーンがロックされており、UI を利用できません（ロック解除されていない CI）
errSecMissingEntitlement	-34018	アプリにキーチェーンアクセスに必要なエンタイトルメントがありません

codesign のエラー

エラー	原因	修正方法
No signing certificate found	キーチェーンに有効な ID がありません	証明書をインポートするか、有効期限を確認します
ambiguous (matches ...)	一致する ID が複数あります	完全な ID 名または SHA-1 ハッシュを指定します
not valid for use in ...	証明書の種類が一致しません（開発用と配布用）	正しい種類の証明書を使用します
a sealed resource is missing or invalid	署名後にリソースが変更されました	すべての変更後に再署名します
invalid signature (code or signature have been modified)	署名後にバイナリが改ざんされました	再署名するか、再ビルドします

ITMS（App Store アップロード）エラー

コード	エラー	原因	対処方法
ITMS-90035	無効な署名	証明書の種類が誤っているか、有効期限が切れています	有効な Apple Distribution 証明書で署名します
ITMS-90161	無効なプロビジョニングプロファイル	プロファイルがアプリと一致していません	Developer Portal でプロファイルを再生成します
ITMS-90046	無効なコード署名エンタイトルメント	エンタイトルメントがプロファイルに含まれていません	ポータルで機能を追加し、プロファイルを再生成します
ITMS-90056	プッシュ通知エンタイトルメントがありません	プロファイルに aps-environment が含まれていません	プッシュ通知機能を有効にします
ITMS-90174	プロビジョニングプロファイルがありません	プロファイルが埋め込まれていません	正しい署名設定でアーカイブします
ITMS-90283	無効なプロビジョニングプロファイル	プロファイルの有効期限が切れています	新しいプロファイルをダウンロードします
ITMS-90426	無効な Swift サポート	Swift ライブラリが正しく署名されていません	（手動ではなく）Xcode のオーガナイザーを使って書き出します
ITMS-90474	バンドル識別子がありません	バンドル ID がプロファイルと一致していません	Xcode、ポータル、プロファイルの間でバンドル ID を一致させます
ITMS-90478	無効な Team ID	Team ID が一致していません	DEVELOPMENT_TEAM ビルド設定を確認します
ITMS-90717	無効な App Store 配布証明書	App Store 用に開発証明書を使用しています	Apple Distribution 証明書に切り替えます

リソース

WWDC: 2021-10204, 2022-110353

ドキュメント: /security, /bundleresources/entitlements, /xcode/distributing-your-app

スキル: axiom-code-signing, axiom-code-signing-diag