236 lines
6.9 KiB
Markdown
236 lines
6.9 KiB
Markdown
# 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 |