# Code Signing Certificate Guide for rmtPocketWatcher

This guide explains how to create and use code signing certificates for your Windows application to eliminate security warnings and build user trust.

## Quick Start

1. **Create Certificate**: `.\create_certificate.ps1`
2. **Build & Sign**: `.\build_windows.ps1 -Release`
3. **Distribute**: Share the signed executables and optionally the public certificate

## Certificate Types

### Self-Signed Certificates (Free)
- **Cost**: Free
- **Trust Level**: Low (requires manual installation)
- **Best For**: Development, internal distribution, open source projects
- **Limitations**: Users see "Unknown Publisher" warnings initially

### Commercial Certificates ($100-$500/year)
- **Cost**: $100-$500 annually
- **Trust Level**: High (automatically trusted)
- **Best For**: Commercial software, wide distribution
- **Providers**: DigiCert, Sectigo, GlobalSign, Entrust

## Self-Signed Certificate Setup

### Step 1: Create Certificate
```powershell
.\create_certificate.ps1
```

This creates:
- `certificates/rmtPocketWatcher.pfx` - Private certificate (keep secure!)
- `certificates/rmtPocketWatcher.cer` - Public certificate (for distribution)
- `certificates/CERTIFICATE_INFO.txt` - Certificate details

### Step 2: Build with Signing
```powershell
.\build_windows.ps1 -Release
```

This automatically:
- Builds the application
- Signs the executable with your certificate
- Creates signed MSIX installer
- Packages everything for distribution

### Step 3: Manual Signing (if needed)
```powershell
.\sign_executable.ps1 -ExePath "path\to\your\app.exe"
```

## Certificate Installation for Users

### Automatic Installation (Recommended)
When users run your signed app for the first time:
1. Windows shows "Unknown Publisher" warning
2. User clicks "More info" → "Run anyway"
3. Certificate is automatically added to their trusted store

### Manual Installation (Optional)
For organizations or power users:
1. Distribute the `.cer` file alongside your app
2. Users double-click the `.cer` file
3. Click "Install Certificate"
4. Choose "Local Machine" (requires admin) or "Current User"
5. Select "Trusted Root Certification Authorities"
6. Click "Next" and "Finish"

## Commercial Certificate Setup

### Step 1: Purchase Certificate
Popular providers:
- **DigiCert**: $474/year (EV), $239/year (OV)
- **Sectigo**: $199/year (EV), $85/year (OV)
- **GlobalSign**: $249/year (EV), $127/year (OV)

### Step 2: Certificate Validation
- **Organization Validation (OV)**: Business verification (1-3 days)
- **Extended Validation (EV)**: Enhanced verification (1-5 days)
- **Individual**: Personal ID verification

### Step 3: Install Certificate
1. Download certificate from provider
2. Install to Windows Certificate Store
3. Update build scripts with certificate details

### Step 4: Update Configuration
```yaml
# pubspec.yaml
msix_config:
  certificate_path: path/to/commercial/cert.pfx
  certificate_password: your_secure_password
```

## Security Best Practices

### Certificate Storage
- **Never commit** `.pfx` or `.p12` files to version control
- Store certificates in secure, encrypted locations
- Use strong passwords for certificate files
- Backup certificates securely

### Password Management
- Use strong, unique passwords for certificates
- Store passwords in secure password managers
- Use environment variables in CI/CD pipelines
- Rotate passwords regularly

### CI/CD Integration
```yaml
# GitHub Actions example
- name: Setup Certificate
  run: |
    echo "${{ secrets.CERT_BASE64 }}" | base64 -d > cert.pfx
    
- name: Sign Application
  run: |
    signtool sign /f cert.pfx /p "${{ secrets.CERT_PASSWORD }}" app.exe
```

## Troubleshooting

### "SignTool not found"
**Solution**: Install Windows SDK
- Download from: https://developer.microsoft.com/windows/downloads/windows-sdk/
- Or install Visual Studio with Windows development tools

### "Certificate not valid for code signing"
**Solution**: Ensure certificate has "Code Signing" usage
```powershell
# Check certificate usage
Get-PfxCertificate -FilePath cert.pfx | Select-Object -ExpandProperty Extensions
```

### "Timestamp server unavailable"
**Solution**: Try different timestamp servers
- http://timestamp.digicert.com
- http://timestamp.sectigo.com
- http://timestamp.globalsign.com

### "Access denied" when signing
**Solution**: Run PowerShell as Administrator
```powershell
# Check if running as admin
([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")
```

### Users still see warnings
**Possible causes**:
1. Certificate not properly installed
2. Certificate expired
3. System clock incorrect
4. Antivirus interference

## Certificate Lifecycle

### Monitoring Expiration
```powershell
# Check certificate expiration
$cert = Get-PfxCertificate -FilePath "certificates/rmtPocketWatcher.pfx"
$daysUntilExpiry = ($cert.NotAfter - (Get-Date)).Days
Write-Host "Certificate expires in $daysUntilExpiry days"
```

### Renewal Process
1. **Self-signed**: Run `.\create_certificate.ps1 -Force`
2. **Commercial**: Renew through certificate provider
3. Update build scripts with new certificate
4. Re-sign and redistribute applications

### Migration to Commercial
1. Purchase commercial certificate
2. Update `pubspec.yaml` configuration
3. Update build scripts
4. Re-sign all distributed applications
5. Notify users of the change

## Cost-Benefit Analysis

### Self-Signed Certificates
**Pros**:
- Free
- Full control
- Good for development/testing
- Suitable for open source projects

**Cons**:
- Users see warnings initially
- Requires user education
- Not suitable for commercial distribution

### Commercial Certificates
**Pros**:
- Immediate trust
- Professional appearance
- Better user experience
- Required for some distribution channels

**Cons**:
- Annual cost
- Validation process
- Vendor dependency

## Recommendations

### For Development/Testing
- Use self-signed certificates
- Document installation process for users
- Consider upgrading for production releases

### For Commercial Distribution
- Invest in commercial certificates
- Choose reputable certificate authorities
- Plan for certificate lifecycle management

### For Open Source Projects
- Start with self-signed certificates
- Consider community funding for commercial certificates
- Provide clear installation instructions

## Scripts Reference

| Script | Purpose | Usage |
|--------|---------|-------|
| `create_certificate.ps1` | Create self-signed certificate | `.\create_certificate.ps1` |
| `sign_executable.ps1` | Sign individual executables | `.\sign_executable.ps1 -ExePath app.exe` |
| `build_windows.ps1` | Build and sign complete package | `.\build_windows.ps1 -Release` |

## Support

For certificate-related issues:
1. Check Windows Event Viewer for detailed errors
2. Verify certificate validity and usage
3. Test on clean Windows installation
4. Consult certificate provider documentation