secret/PROVISIONING_GUIDE.md

Provisioning Profile Setup for macOS Biometric Authentication

Prerequisites

1. Apple Developer Account (paid membership required)
2. macOS development machine
3. Xcode installed (for code signing tools)

Step 1: Log into Apple Developer Portal

1. Go to developer.apple.com
2. Sign in with your Apple Developer account
3. Navigate to "Certificates, Identifiers & Profiles"

Step 2: Create App ID

1. Click "Identifiers" in the sidebar
2. Click the "+" button to create a new identifier
3. Select "App IDs" and click "Continue"
4. Choose "App" (not App Clip) and click "Continue"
5. Fill in the details:
   • Description: Secret Manager macOS App
   • Bundle ID: Select "Explicit" and enter berlin.sneak.pkg.secret
6. In the "Capabilities" section, enable:
   • Keychain Sharing (this is essential for keychain access)
   • Leave other capabilities unchecked unless specifically needed
7. Click "Continue" and then "Register"

Step 3: Create/Verify Development Certificate

1. Click "Certificates" in the sidebar
2. Click the "+" button if you need a new certificate
3. Under "Development", select "Mac Development"
4. Follow the instructions to generate a Certificate Signing Request (CSR):
   • Open Keychain Access on your Mac
   • Go to Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority
   • Enter your email address and name
   • Select "Saved to disk" and "Let me specify key pair information"
   • Click "Continue" and save the CSR file
5. Upload the CSR file and download the certificate
6. Double-click the downloaded certificate to install it in Keychain Access

Step 4: Register Development Device

1. Click "Devices" in the sidebar
2. Click the "+" button to register a new device
3. Select "macOS" as the platform
4. Get your Mac's hardware UUID:

   system_profiler SPHardwareDataType | grep "Hardware UUID"
   

5. Enter:
   • Device Name: Your Mac's name (e.g., "John's MacBook Pro")
   • Device ID (UUID): The hardware UUID from step 4
6. Click "Continue" and then "Register"

Step 5: Create Development Provisioning Profile

1. Click "Profiles" in the sidebar
2. Click the "+" button to create a new profile
3. Under "Development", select "Mac App Development"
4. Click "Continue"
5. Select your App ID: berlin.sneak.pkg.secret
6. Click "Continue"
7. Select your development certificate
8. Click "Continue"
9. Select your registered Mac device
10. Click "Continue"
11. Enter a profile name: Secret Manager macOS Development
12. Click "Generate"
13. Download the provisioning profile

Step 6: Install Provisioning Profile

1. Double-click the downloaded .provisionprofile file to install it
2. Or manually copy it to: ~/Library/MobileDevice/Provisioning Profiles/

Step 7: Code Signing Setup

Option A: Manual Code Signing

Add these flags when building your Go binary:

# Build the binary
go build -o secret cmd/secret/main.go

# Sign the binary
codesign --sign "Apple Development: YOUR_NAME (TEAM_ID)" \
         --entitlements entitlements.plist \
         --options runtime \
         --force \
         ./secret

Option B: Using Makefile

Update your Makefile to include code signing:

DEVELOPER_ID = "Apple Development: YOUR_NAME (TEAM_ID)"
ENTITLEMENTS = entitlements.plist

secret: 
	go build -o secret cmd/secret/main.go
	codesign --sign $(DEVELOPER_ID) \
	         --entitlements $(ENTITLEMENTS) \
	         --options runtime \
	         --force \
	         ./secret

.PHONY: secret

Step 8: Verify Code Signing

Check that your binary is properly signed:

# Check code signature
codesign -dv --verbose=4 ./secret

# Check entitlements
codesign -d --entitlements :- ./secret

Step 9: Test Biometric Authentication

Run your app and verify that:

1. Touch ID/Face ID prompts appear when accessing keychain
2. No entitlement errors occur
3. Keychain operations work correctly

Troubleshooting

Common Issues:

1. errSecMissingEntitlement (-34018)

   • Ensure your provisioning profile includes keychain access
   • Verify code signing is applied correctly
   • Check that bundle ID matches exactly

2. No biometric prompt appears

   • Verify access control flags in your Security Framework calls
   • Ensure device has biometric authentication enabled
   • Check system preferences for app permissions

3. Code signing failures

   • Ensure certificate is installed in Keychain Access
   • Verify team ID matches between certificate and provisioning profile
   • Check that provisioning profile is installed

Debug Commands:

# List installed certificates
security find-identity -v -p codesigning

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

# Check provisioning profile contents
security cms -D -i ~/Library/MobileDevice/Provisioning\ Profiles/YOUR_PROFILE.provisionprofile

Production Distribution

For production distribution, you'll need to:

1. Create a "Developer ID Application" certificate
2. Create a "Developer ID" provisioning profile
3. Notarize your app with Apple
4. Staple the notarization ticket

This allows distribution outside the Mac App Store while maintaining system trust.

Important Notes

• Keychain access groups are automatically included for explicit App IDs
• Biometric authentication requires proper access controls in your Security Framework calls
• The com.apple.security.cs.disable-library-validation entitlement may be needed for Go binaries
• Test thoroughly on a clean system to ensure all entitlements work correctly