Signing, Installer, New Workflows
This commit is contained in:
236
flutter_app/CERTIFICATE_GUIDE.md
Normal file
236
flutter_app/CERTIFICATE_GUIDE.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user