技術（tech）

How to Sign Electron Apps in a Virtual Windows Environment: From Setup to Build

 
Contents
  1. Introduction
  2. Target Audience
  3. Technical Background
  4. The Challenge
  5. Solution Approach
  6. Implementation Steps
  7. Results and Benefits
  8. Conclusion
  9. References

Introduction

  • Key points: This article explains how Mac users can build Electron apps and sign them using a USB token in a virtual Windows environment
  • Technology stack: Windows (virtual environment), Node.js, Electron, electron-builder, GlobalSign certificate, USB token

This article is a continuation of our previous articles "How to Sign Code in a Virtual Windows Environment on Mac" and "Recovery Procedure for GlobalSign Certificate Download Failures". Using the virtual Windows environment we set up previously and the certificate stored on the USB token, we’ll now explain how to actually build and sign Electron applications.

Target Audience

  • Mac users who have already stored certificates on USB tokens
  • Those who have already set up a virtual Windows environment
  • Developers who want to release signed Electron applications
  • Anyone wanting to learn the basics of setting up Node.js projects in a Windows environment

Technical Background

Electron applications benefit from code signing during distribution to avoid security warnings and demonstrate safety to end users. Since April 2023, code signing certificates must be stored on USB tokens, and Mac users can use a virtual Windows environment to perform the signing process.

electron-builder is a tool that automates the packaging and code signing of Electron apps, but configuration in a Windows environment requires some finesse. Especially when using USB tokens for signing, things might not work properly without the right settings.

USB Tokens and CI/CD

The USB token requirement has changed the development landscape. Previously, PFX files enabled fully automated signing in CI/CD pipelines, but now physical tokens necessitate a semi-manual approach. Most developers now automate the build process but perform signing manually. For Mac users working with Windows applications, the virtual environment approach described here provides a practical solution.

The Challenge

Application development and signing in a virtual Windows environment comes with several challenges:

  1. Development environment setup: You need to properly configure basic tools like editors, Git, and Node.js
  2. Access to private GitHub repositories: Setting up authentication credentials securely takes some work
  3. Signing from a USB token: You need to configure your build process to use the certificate stored on the token
  4. Managing environment variables: Setting up all the parameters needed for development, building, and signing

Particularly, using a certificate from a USB token to sign with electron-builder requires several configuration steps.

Solution Approach

In this article, we’ll tackle these challenges with the following approach:

  1. We’ll use Cursor editor as our integrated development environment (though similar steps work for VS Code too)
  2. We’ll set up repository access using GitHub CLI for modern authentication methods
  3. We’ll configure the Windows certificate store to work with the USB token
  4. We’ll set up the signtool.exe path and environment variables for electron-builder

With this approach, you can develop, build, and sign in the virtual environment just like you would in a production environment.

Implementation Steps

1. Setting Up Basic Development Environment

Start by installing Cursor editor and Git to set up a basic development environment.

Installing Cursor Editor

Visit https://cursor.sh
Click "Download for Windows"
Run the downloaded installer (.exe)
Follow the installation wizard instructions

Installing Git

Visit https://git-scm.com/download/win
Download 64-bit Git for Windows Setup
Run the installer with mostly default settings
For "Adjusting your PATH environment," select "Git from the command line and also from 3rd-party software"

These tools provide the necessary environment for code editing and version control.

2. Setting Up GitHub Authentication (for Private Repositories)

Configure GitHub authentication in line with the latest security standards.

Installing and Configuring GitHub CLI

GitHub CLI provides a modern and secure method for accessing GitHub.

# Create a temporary directory
mkdir -p ~/temp/gh-cli && cd ~/temp/gh-cli

# Download the latest version (replace with the current version from the releases page)
curl -LO https://github.com/cli/cli/releases/download/v2.45.0/gh_2.45.0_windows_amd64.zip

# Extract the ZIP
unzip gh_2.45.0_windows_amd64.zip

# Add to PATH (temporary)
export PATH="$PATH:$HOME/temp/gh-cli/gh_2.45.0_windows_amd64/bin"

# For permanent PATH addition
echo 'export PATH="$PATH:$HOME/temp/gh-cli/gh_2.45.0_windows_amd64/bin"' >> ~/.bashrc
source ~/.bashrc

# Login with GitHub CLI
gh auth login

# Follow the interactive prompts:
# - Select GitHub.com
# - Select HTTPS
# - Select browser authentication
# - Authenticate in the browser that opens with your GitHub account

This approach uses browser authentication, providing a secure way to access repositories without managing personal access tokens.

Initial Git Configuration

# Set user information (only needed once)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

This configuration is recorded in commit history, so it’s recommended to set it up properly.

3. Cloning the Repository and Preparing the Development Environment

Retrieve the project code and set up the development environment.

Cloning from GitHub

# Right-click in an appropriate location (like Desktop) and select "Git Bash Here"

# Using GitHub CLI
gh repo clone username/repository-name
cd repository-name

# Or clone via HTTPS
git clone https://github.com/username/repository-name.git
cd repository-name

Example of actual cloning:

Sasaki@WIN-RF7UMHPTK93 CLANGARM64 ~
$ git clone https://github.com/your-company/your-app-name
Cloning into 'your-app-name'...
remote: Enumerating objects: 246, done.
remote: Counting objects: 100% (246/246), done.
remote: Compressing objects: 100% (124/124), done.
remote: Total 246 (delta 80), reused 212 (delta 46), pack-reused 0 (from 0)
Receiving objects: 100% (246/246), 1.38 MiB | 3.88 MiB/s, done.
Resolving deltas: 100% (80/80), done.

Opening the Repository in Cursor

Launch Cursor
Select "File" → "Open Folder" and choose the cloned repository folder

Now you’re ready for code editing.

4. Installing Node.js and Yarn

Install Node.js and Yarn necessary for developing and building Electron apps.

# Install Node.js (using curl)
cd ~/Downloads
curl -O https://nodejs.org/dist/v20.11.1/node-v20.11.1-x64.msi
# Run the downloaded MSI file (open in Explorer)
explorer .

# After installation, restart Git Bash and verify
node --version
npm --version

# Install Yarn
npm install -g yarn

# Verify installation
yarn --version

If versions are displayed, the installation was successful. It’s recommended to use the latest LTS version.

5. Setting Up the Code Signing Environment

Prepare the environment for signing applications using the USB token.

Configuring signtool.exe Path

Add the path to signtool.exe from the Windows SDK. This assumes you’ve already installed the Windows SDK from the previous article.

# Add to .bashrc file (for Git Bash)
echo 'export PATH="$PATH:/c/Program Files (x86)/Windows Kits/10/bin/10.0.26100.0/X64"' >> ~/.bashrc

# Apply the setting
source ~/.bashrc

Verification:

# Check if signtool command is available
signtool.exe /?

If help information is displayed, the path is configured correctly. When actually using it, you’ll need to specify the certificate name and timestamp server URL appropriately.

Exporting Certificate from USB Token and Importing to Windows

Registering the token’s certificate in the Windows certificate store streamlines the signing process.

  1. Exporting Certificate from SafeNet Authentication Client
1. Launch SafeNet Authentication Client (SAC)
2. Select the token and log in with the PIN code
3. Select "Certificates" from the left panel
4. Right-click the certificate you want to use for signing and select "Export"
5. Choose "DER encoded binary X.509 (.CER)"
6. Specify the save location and filename (e.g., `YourCompany_Cert.cer`)
  1. Importing to Windows Certificate Store

Using PowerShell:

# Open PowerShell as administrator and run
Import-Certificate -FilePath "C:\path\to\YourCompany_Cert.cer" -CertStoreLocation Cert:\CurrentUser\My

Similar operations can be done via GUI. To verify the certificate was imported correctly:

# Run in PowerShell
Get-ChildItem -Path Cert:\CurrentUser\My | Where-Object { $_.Subject -like "*YourCompany*" } | Format-List Subject, Thumbprint

In actual projects, replace company name sections appropriately.

6. Setting Up Electron Application Build Environment

Now let’s focus on the specific configuration needed for code signing with a USB token.

Setting Up the Signing Script

For signing with a USB token, create a custom signing script called sign-with-token.ts:

// scripts/sign-with-token.ts
exports.default = async function(configuration) {
    const { path } = configuration;
    const { execSync } = require('child_process');

    console.log(`Signing: ${path}`);

    try {
      execSync(`signtool sign /tr http://timestamp.globalsign.com/tsa/r6advanced1 /fd sha256 /td sha256 /n "Your Company Name" "${path}"`, 
        { stdio: 'inherit' });
      return true;
    } catch (error) {
      console.error('Signing error:', error);
      throw error;
    }
};

Key signtool parameters:

  • /tr: Timestamp server URL
  • /fd sha256 and /td sha256: SHA-256 hash algorithm
  • /n "Your Company Name": Certificate subject name in Windows certificate store

Configuring package.json

Configure electron-builder to use your signing script:

{
  "scripts": {
    "build:win": "yarn build && electron-builder -w --publish=never"
  },
  "build": {
    "win": {
      "sign": "./sign-with-token.ts"
    }
  }
}

This setup will execute the signing script for each file during the packaging process.

7. Building and Signing the Electron Application

Finally, build and sign the application.

Building the Application

# Navigate to the project directory
cd path/to/project

# Install dependencies
yarn install

# Make sure the USB token is connected

# Build the application
yarn build:win

This command runs the build script defined in package.json, and electron-builder handles the packaging and signing of the app.

Checking Build Artifacts

# Navigate to the artifacts directory
cd artifacts

Main artifacts:

  1. win-unpacked: Unpacked application folder

    • YourApp.exe: Main executable (signed)
    • resources: App resources

  2. Installer files:

    • YourApp Setup x.x.x.exe: Windows installer (signed)
    • YourApp-x.x.x-win.zip: Portable version (zip format)

Verifying the Signature

Here’s how to verify the signature through the Windows UI:

  1. Locate the signed file in Explorer:

    • Find YourApp Setup x.x.x.exe in the artifacts folder

  2. Open file properties:

    • Right-click on the file and select "Properties"

  3. Check the Digital Signatures tab:

    • Click on the "Digital Signatures" tab in the Properties window
    • You should see "Your Company Name" in the signature list

  4. View signature details:

    • Select the signature and click the "Details" button
    • Click "View Certificate" to examine the certificate information
    • Here you can verify issuer information, validity period, timestamp, and other details

If the Digital Signatures tab displays correctly and you can view the certificate information, the signing process was successful. It’s also good to verify that a valid timestamp has been applied.

Results and Benefits

Following these steps provides several benefits:

  1. Enhanced security: Secure signing process using USB token
  2. Automation: Automated building and signing with electron-builder
  3. Cross-platform development: Build Windows apps in a virtual environment on Mac
  4. Secure distribution: Ensure reliability with signed applications

In my experience, this method allowed me to build signed Electron apps directly from Mac without needing a dedicated Windows machine.

Conclusion

This article outlines the process for building and signing Electron apps with a USB token in a virtual Windows environment on Mac. This approach allows you to:

  1. Create signed Windows apps on a Mac without a physical Windows machine
  2. Maintain security while ensuring reliable application distribution
  3. Streamline development, build, and signing in one environment

As security requirements evolve, USB token signing will continue to be important for application distribution.

References

electron コードサイニング 証明書
RELATED POST