macos-keychain

What this skill does

# macos-keychain

## Purpose
This skill provides tools for managing macOS Keychain via the `security` CLI, handling secure storage of secrets like API keys, passwords, certificates, and codesigning, while interacting with the Secure Enclave for enhanced security.

## When to Use
Use this skill when your application needs to store or retrieve sensitive data on macOS, such as API keys in scripts, manage certificates for app signing, or handle hardware-backed secrets via Secure Enclave. Apply it in automation, CI/CD pipelines, or apps requiring macOS-specific security.

## Key Capabilities
- Store and retrieve generic passwords using Keychain services.
- Manage certificates and identities for codesigning apps or verifying connections.
- Interact with Secure Enclave for storing keys that require hardware protection.
- Add, delete, or search items in Keychain with fine-grained access controls.
- Handle API key storage with encryption, ensuring data is isolated per user or app.

## Usage Patterns
Always run `security` commands via subprocess in scripts, prefixing with `security` and using flags for operations. For programmatic access, use the Security framework in Swift/Objective-C. Check for Keychain access prompts and handle user interactions. Use environment variables like `$KEYCHAIN_ITEM_NAME` for dynamic inputs to avoid hardcoding secrets.

## Common Commands/API
Use the `security` CLI for most tasks; for apps, leverage Security framework APIs like SecItemAdd and SecItemCopyMatching.

- Add a generic password:  
  `security add-generic-password -a username -s service -w password -T ""`  
  This stores a password for a service; use `$SERVICE_NAME` for the service string.

- Find a generic password:  
  `security find-generic-password -a username -s service -w`  
  Output the password; pipe to a variable, e.g., in Bash: `pass=$(security find-generic-password -s myapp -w)`.

- Delete an item:  
  `security delete-generic-password -a username -s service`  
  Removes the entry; confirm with `-h` for help on flags.

- Add a certificate:  
  `security add-certificate -k login.keychain cert.pem`  
  Imports a PEM certificate; specify keychain with `-k`.

- For Secure Enclave, generate a key:  
  `security create-key -t secp256r1 -a -p`  
  Creates a key pair; use in apps via SecKeyGeneratePair.

- API example in Swift (Security framework):  
  `let query: [String: Any] = [kSecClass as String: kSecClassGenericPassword]`  
  `let status = SecItemCopyMatching(query as CFDictionary, nil)`  
  This queries for a generic password item.

- Export a certificate:  
  `security export -k login.keychain -t identities -o cert.p12 -P passphrase`  
  Exports to P12 format; use for codesigning.

Config formats: Keychain items use a dictionary-based query (e.g., in APIs, as [String: Any]), with keys like kSecAttrAccount for usernames. CLI outputs are plain text or plist; parse with `plutil` for structured data.

## Integration Notes
Integrate by calling `security` commands from scripts using subprocess (e.g., in Python: `subprocess.run(['security', 'add-generic-password', ...])`). For apps, import Security.h and use functions like SecItemAdd; ensure entitlements include "keychain-access-groups". Use env vars for secrets, like `$API_KEY` passed to commands. Avoid storing keys in code; fetch from Keychain at runtime. For cross-app access, set the same access group in entitlements.

## Error Handling
Check command exit codes; e.g., in Bash, use `if [ $? -ne 0 ]; then echo "Error: Keychain operation failed"; fi`. For CLI, parse stderr for messages like "SecKeychainItem not found". In Swift APIs, handle OSStatus errors (e.g., if SecItemAdd returns errSecDuplicateItem, log and retry). Use try-catch in Objective-C for framework calls. Common issues: permission denied (prompt user via UI) or item not found (return default value). Always sanitize outputs to prevent exposure of secrets.

## Concrete Usage Examples
1. Store an API key in Keychain:  
   In a Bash script, use: `security add-generic-password -a myapp-user -s myapi -w $API_KEY -T ""`  
   Then retrieve it: `apiKey=$(security find-generic-password -a myapp-user -s myapi -w)`  
   Use `$API_KEY` from env vars to avoid plaintext in scripts.

2. Manage a certificate for codesigning:  
   Import a cert: `security add-certificate -k login.keychain mycert.pem`  
   Verify: `security find-certificate -c "My Cert Name"`  
   In a build script, export for signing: `security export -k login.keychain -t identities -o signing.p12`.

## Graph Relationships
- Related to: macos-filesystem (for certificate file handling), security-tools (for broader security operations), encryption-services (via Secure Enclave integration).
- Clusters: macos (direct), secrets-management (via tags).
- Tags connections: keychain (core), secrets (overlaps with vault tools), security (links to authentication skills).