macos-keychain

macos-keychain

目的

このスキルは、security CLI を使用して macOS Keychain を管理するためのツールを提供します。API キー、パスワード、証明書、コード署名用データなどの秘密情報を安全に保存し、Secure Enclave と連携してセキュリティを強化できます。

使用するタイミング

アプリケーションで API キーなどの機密データをスクリプト内に保存または取得する必要がある場合、アプリの署名用証明書を管理する場合、または Secure Enclave を介してハードウェアで保護される秘密情報を扱う場合に、このスキルを使用します。自動化、CI/CD パイプライン、または macOS 固有のセキュリティを必要とするアプリで活用します。

主な機能

• Keychain サービスを使用して汎用パスワードを保存、取得します。
• アプリのコード署名や接続の検証に使用する証明書と ID を管理します。
• ハードウェア保護が必要な鍵を保存するために Secure Enclave と連携します。
• きめ細かなアクセス制御を設定して、Keychain の項目を追加、削除、検索します。
• 暗号化によって API キーを保存し、ユーザーまたはアプリごとにデータを分離します。

使用パターン

スクリプトから security コマンドを実行する場合は、必ずサブプロセス経由で、security を先頭に指定し、操作に応じたフラグを使用します。プログラムからアクセスする場合は、Swift／Objective-C の Security フレームワークを使用します。Keychain アクセスの確認ダイアログに注意し、ユーザーによる操作に対応してください。秘密情報をハードコードしないよう、動的な入力には $KEYCHAIN_ITEM_NAME などの環境変数を使用します。

主なコマンド／API

ほとんどの操作には security CLI を使用します。アプリでは、SecItemAdd や SecItemCopyMatching などの Security フレームワーク API を活用します。

• 汎用パスワードを追加する：
  security add-generic-password -a username -s service -w password -T ""
  サービスのパスワードを保存します。サービス名の文字列には $SERVICE_NAME を使用します。

• 汎用パスワードを検索する：
  security find-generic-password -a username -s service -w
  パスワードを出力します。Bash では、次のように変数に渡すことができます：pass=$(security find-generic-password -s myapp -w)。

• 項目を削除する：
  security delete-generic-password -a username -s service
  項目を削除します。フラグのヘルプは -h で確認できます。

• 証明書を追加する：
  security add-certificate -k login.keychain cert.pem
  PEM 証明書を読み込みます。-k でキーチェーンを指定します。

• Secure Enclave 用の鍵を生成する：
  security create-key -t secp256r1 -a -p
  鍵ペアを作成します。アプリからは SecKeyGeneratePair を使用します。

• Swift での API 使用例（Security フレームワーク）：
  let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword]
let status = SecItemCopyMatching(query as CFDictionary, nil)
  汎用パスワード項目を検索します。

• 証明書を書き出す：
  security export -k login.keychain -t identities -o cert.p12 -P passphrase
  P12 形式で書き出します。コード署名に使用します。

設定形式：Keychain 項目では、辞書形式のクエリを使用します（API では [String: Any] など）。キーには、ユーザー名に使用する kSecAttrAccount などがあります。CLI の出力はプレーンテキストまたは plist です。構造化データは plutil で解析します。

統合に関する注意

スクリプトからサブプロセスを使って security コマンドを呼び出します（例：Python では subprocess.run(['security', 'add-generic-password', ...])）。アプリでは Security.h をインポートして SecItemAdd などの関数を使用し、エンタイトルメントに "keychain-access-groups" が含まれていることを確認します。コマンドには $API_KEY などの環境変数を渡して秘密情報を指定します。鍵をコード内に保存せず、実行時に Keychain から取得してください。アプリ間でアクセスする場合は、エンタイトルメントに同じアクセスグループを設定します。

エラー処理

コマンドの終了コードを確認します。たとえば Bash では、if [ $? -ne 0 ]; then echo "Error: Keychain operation failed"; fi を使用します。CLI では、"SecKeychainItem not found" などのメッセージを標準エラー出力から解析します。Swift API では OSStatus エラーを処理します（例：SecItemAdd が errSecDuplicateItem を返した場合は、記録して再試行します）。Objective-C では、フレームワーク呼び出しに try-catch を使用します。よくある問題には、アクセス拒否（UI でユーザーに確認する）や項目が見つからない場合（デフォルト値を返す）があります。秘密情報が漏えいしないよう、出力は必ずサニタイズしてください。

具体的な使用例

1. API キーを Keychain に保存する：
   Bash スクリプトで、次のように使用します：security add-generic-password -a myapp-user -s myapi -w $API_KEY -T ""
   次に、取得します：apiKey=$(security find-generic-password -a myapp-user -s myapi -w)
   スクリプト内に平文で記述しないよう、環境変数の $API_KEY を使用します。

2. コード署名用の証明書を管理する：
   証明書をインポートします：security add-certificate -k login.keychain mycert.pem
   検証します：security find-certificate -c "My Cert Name"
   ビルドスクリプトで、署名用にエクスポートします：security export -k login.keychain -t identities -o signing.p12.

グラフ上の関係

• 関連項目：macos-filesystem（証明書ファイルの処理）、security-tools（より広範なセキュリティ操作）、encryption-services（Secure Enclave との連携）。
• クラスター：macos（直接）、secrets-management（タグ経由）。
• タグのつながり：keychain（中核）、secrets（vault ツールと重複）、security（認証スキルと関連）。