rmtPocketWatcher/flutter_app/CERTIFICATE_GUIDE.md

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

.\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

.\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)

.\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

# 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

# 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

# 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

# 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

# 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