Security & Keychain Integration

Welcome to the HarborDB security guide. This comprehensive resource explains how HarborDB leverages macOS security features—especially Keychain—to keep your database credentials and data secure. Whether you're working with local development databases or production servers, understanding these security features is essential for protecting sensitive information.

Why Security Matters

Database connections often contain sensitive information:

• Usernames and passwords for PostgreSQL servers
• Connection details including hostnames and ports
• Query results that may contain confidential data
• Export files with business-critical information

HarborDB is designed with security as a core principle, using native macOS technologies to provide enterprise-grade protection without compromising usability.

macOS Keychain: Your Digital Safe

What is Keychain?

Keychain is macOS's built-in password management system. Think of it as a digital safe where macOS stores:

• Passwords for applications and websites
• Encryption keys for secure communications
• Certificates for identity verification
• Secure notes for sensitive information

How Keychain Protects Your Data

1. Encryption at Rest: All Keychain data is encrypted using AES-256 encryption
2. Access Controls: Each application must request permission to access Keychain items
3. User Isolation: Keychain items are tied to your user account
4. Automatic Locking: Keychain locks when your Mac sleeps or locks

HarborDB and Keychain Integration

Automatic Password Storage

When you save a connection in HarborDB:

1. Password is extracted from connection settings
2. Encrypted and stored in your user's Keychain
3. Connection file saves only non-sensitive information
4. On next connection, HarborDB retrieves password from Keychain

What Gets Stored Where

| Storage Location | What's Stored | Security Level | | ---------------------- | ---------------------------------- | ---------------------------- | | macOS Keychain | Passwords only | 🔒 Maximum (AES-256) | | Connection File | Host, port, database, username | 🔐 Medium (File permissions) | | Application Memory | Decrypted passwords during session | 🔐 High (RAM encryption) | | Disk Cache | Query results, temporary files | 🔐 Medium (FileVault) |

Keychain Item Structure

Each HarborDB connection creates a Keychain item with:

• Service Name: HarborDB
• Account Name: connection:[connection_name]
• Password: Your encrypted PostgreSQL password
• Access Group: Limited to HarborDB application

Security Best Practices

1. Password Management

Do:

• ✅ Use strong, unique passwords for each database
• ✅ Change passwords periodically (every 90 days)
• ✅ Use password managers for additional security
• ✅ Enable two-factor authentication where possible

Don't:

• ❌ Reuse passwords across different servers
• ❌ Store passwords in plain text files
• ❌ Share Keychain passwords with others
• ❌ Use simple or default passwords

2. Connection Security

Local Databases:

Host: localhost or 127.0.0.1
SSL: Optional (loopback is secure)
Keychain: Recommended

Development Servers:

Host: dev-db.internal
SSL: Prefer or Require
Keychain: Required
Firewall: Restrict to internal network

Production Servers:

Host: prod-db.example.com
SSL: Require or Verify-Full
Keychain: Required
VPN: Recommended for access

3. File Security

1. Store connection files in secure locations
2. Use FileVault for full-disk encryption
3. Regularly backup Keychain (via Time Machine)
4. Secure export folders with appropriate permissions

Touch ID and Biometric Integration

Using Touch ID with HarborDB

If your Mac has Touch ID (or Face ID on newer models), you can enhance security:

1. Enable Touch ID for Keychain in System Settings
2. HarborDB will prompt for fingerprint when accessing passwords
3. Fallback to password if biometrics fail

Setting Up Biometric Authentication

1. Open System Settings → Touch ID & Password
2. Add your fingerprints (up to 3)
3. Check "Keychain" in the list of uses
4. Restart HarborDB for changes to take effect

Benefits of Biometric Integration

• Convenience: No need to type master password
• Security: Unique to you (cannot be shared)
• Speed: Faster than password entry
• Audit trail: Each access is uniquely identified

FileVault and Disk Encryption

What is FileVault?

FileVault is macOS's full-disk encryption feature:

• Encrypts entire startup disk
• Protects data at rest
• Transparent to applications
• Required for some compliance standards

Enabling FileVault

1. Open System Settings → Privacy & Security
2. Click FileVault
3. Click Turn On
4. Choose recovery method (iCloud or recovery key)
5. Wait for encryption to complete (background process)

How FileVault Protects HarborDB Data

With FileVault enabled:

• Connection files are encrypted on disk
• Export files are protected
• Temporary files cannot be recovered
• Cache files are secure even if Mac is stolen

Network Security (SSL/TLS)

Understanding SSL/TLS

SSL (Secure Sockets Layer) and TLS (Transport Layer Security) encrypt data in transit:

HarborDB (macOS) → Encrypted Tunnel → PostgreSQL Server

SSL Modes in HarborDB

| Mode | Security Level | Use Case | | --------------- | -------------- | ---------------------------- | | Disable | ❌ None | Local development only | | Allow | ⚠️ Low | Prefer unencrypted | | Prefer | ✅ Medium | Default for most cases | | Require | ✅ High | Remote servers | | Verify-CA | ✅✅ High | Verify certificate authority | | Verify-Full | ✅✅✅ Highest | Full certificate validation |

Configuring SSL in HarborDB

1. Edit connection in HarborDB
2. Select SSL Mode from dropdown
3. Import certificates if using Verify-Full
4. Test connection to verify SSL handshake

Certificate Management

For enterprise environments:

• Import CA certificates in Keychain Access
• Use client certificates for mutual TLS
• Set certificate expiry alerts
• Regularly update revoked certificates

Troubleshooting Common Issues

Keychain Access Problems

"HarborDB cannot access Keychain"

1. Check permissions:

   # Open Keychain Access
   open /Applications/Utilities/Keychain\ Access.app
   

2. Reset HarborDB permissions:

   • Delete and re-add connection
   • Grant permission when prompted

3. Repair Keychain:

   • Open Keychain Access
   • Select "Login" keychain
   • File → "Keychain First Aid"

"Password not found in Keychain"

1. Verify connection name hasn't changed
2. Check multiple Keychains (Login, System, iCloud)
3. Rebuild Keychain index:

   security delete-keychain ~/Library/Keychains/login.keychain-db
   # Will recreate on next login
   

SSL Connection Issues

"SSL Handshake Failed"

1. Check PostgreSQL SSL configuration:

   # In postgresql.conf
   ssl = on
   ssl_cert_file = 'server.crt'
   ssl_key_file = 'server.key'
   

2. Verify certificate validity:

   openssl x509 -in server.crt -text -noout
   

3. Try different SSL mode (Require → Prefer)

General Security Issues

"Permission Denied" errors

1. Check file permissions:

   ls -la ~/Library/Application\ Support/HarborDB/
   

2. Reset HarborDB permissions:

   • Move preferences file
   • Restart HarborDB

3. Verify disk permissions:

   diskutil verifyVolume /
   

Advanced Security Features

Custom Keychain Configuration

For advanced users:

1. Create dedicated Keychain for HarborDB:

   security create-keychain -P harbor.keychain
   security set-keychain-settings harbor.keychain
   

2. Set shorter timeout for sensitive connections:

   security set-keychain-settings -t 300 harbor.keychain
   

3. Lock Keychain when not in use:

   security lock-keychain harbor.keychain
   

Audit and Monitoring

1. Enable connection logging in Preferences

2. Review Keychain access logs:

   log show --predicate 'subsystem == "com.apple.security"'
   

3. Set up alerts for failed connections

4. Regularly review exported file access logs

Compliance Considerations

GDPR/CCPA Compliance:

• Personal data encryption at rest and in transit
• Access logging and audit trails
• Data retention policies for exports

HIPAA Compliance:

• Full-disk encryption (FileVault)
• Session timeout for inactive connections
• Secure deletion of temporary files

PCI DSS Compliance:

• Never store credit card numbers in queries
• Mask sensitive data in exports
• Regular security assessments

Security Checklist

Daily Practices

• [ ] Lock Mac when stepping away
• [ ] Verify connection security before use
• [ ] Check for macOS security updates
• [ ] Review recent connection attempts

Weekly Practices

• [ ] Review exported file locations
• [ ] Check Keychain for outdated entries
• [ ] Verify FileVault is active
• [ ] Backup security configurations

Monthly Practices

• [ ] Rotate database passwords
• [ ] Review SSL certificates
• [ ] Audit connection permissions
• [ ] Test disaster recovery procedures

Getting Help

Security Incidents

If you suspect a security issue:

1. Immediate actions:

   • Change affected database passwords
   • Revoke compromised certificates
   • Enable additional logging

2. Contact support with:

   • Timeframe of incident
   • Affected connections
   • Any error messages
   • Steps already taken

Security Consultation

For enterprise security needs:

• Custom security assessments
• Compliance guidance (GDPR, HIPAA, PCI DSS)
• Integration with corporate security systems
• Training for team members

Additional Resources

• Apple Platform Security Guide
• PostgreSQL Security Documentation
• HarborDB Support Guide
• macOS Security Features

---

Security is a shared responsibility. By understanding and properly using macOS security features with HarborDB, you create a robust defense against data breaches and unauthorized access. Remember: good security practices become habits that protect your data every day.

Last updated: {{current_date}}