mail2couch/rust/TLS_SUPPORT.md

# TLS Support in mail2couch Rust Implementation

The Rust implementation of mail2couch now includes full TLS support for secure IMAP connections.

## Automatic TLS Detection

The client automatically determines whether to use TLS based on the configured port:

- **Port 993** (IMAPS): Uses TLS encryption (default for Gmail, Outlook, etc.)
- **Port 143** (IMAP): Uses plain text connection (insecure, typically for testing)
- **Port 3143**: Uses plain text (test environment default)
- **Other ports**: Defaults to TLS with a warning message

## Example Configurations

### Gmail with TLS (Recommended)
```json
{
  "name": "Personal Gmail",
  "host": "imap.gmail.com",
  "port": 993,
  "user": "your-email@gmail.com",
  "password": "your-app-password"
}
```

### Outlook with TLS
```json
{
  "name": "Work Outlook",
  "host": "outlook.office365.com", 
  "port": 993,
  "user": "you@company.com",
  "password": "your-app-password"
}
```

### Test Environment (Plain)
```json
{
  "name": "Test Server",
  "host": "localhost",
  "port": 3143,
  "user": "testuser",
  "password": "testpass"
}
```

## Security Notes

1. **Always use port 993** for production email providers
2. **Never use port 143** with real email accounts (credentials sent in plain text)
3. **Use app passwords** instead of account passwords for Gmail/Outlook
4. **Port 3143** is only for local testing environments

## Provider-Specific Settings

### Gmail
- Host: `imap.gmail.com`
- Port: `993` (TLS)
- Requires app password (not regular password)
- Enable 2FA and generate app password in Google Account settings

### Microsoft Outlook/Office 365
- Host: `outlook.office365.com`
- Port: `993` (TLS)
- May require app password depending on organization settings

### Yahoo Mail
- Host: `imap.mail.yahoo.com`
- Port: `993` (TLS)
- Requires app password

## Testing TLS Functionality

1. **Test with local environment**: Port 3143 (plain)
   ```bash
   ./mail2couch -c config-test.json
   ```

2. **Test with Gmail**: Port 993 (TLS)
   ```bash
   ./mail2couch -c config-gmail.json
   ```

3. **Verify TLS detection**: Check logs for connection type
   - TLS connections will show successful handshake
   - Plain connections will connect directly

## Implementation Details

The TLS support is implemented using:
- `async-native-tls` for TLS connections
- `async-std` for plain TCP connections
- Custom `ImapStream` enum that wraps both connection types
- Automatic port-based detection logic

This ensures compatibility with both secure production environments and insecure test setups.