Understanding Code Signing and Notarization in Electron: A Step-by-Step Guide

In today’s digital landscape, security and trust are paramount, especially when distributing software to end-users. Electron, a popular framework for building cross-platform desktop applications, requires additional steps to ensure your app is both secure and trusted by users. This is where code signing and notarization come into play. In this blog, we will dive deep into what these processes entail and how to implement them in your Electron application, ensuring a smooth and secure distribution process.

What is Code Signing?

Code signing is the process of applying a digital signature to your application’s code. This signature assures users that the software comes from a verified source and has not been tampered with since it was signed. It acts as a guarantee of the code’s integrity and authenticity.

How Does Code Signing Work? When you sign your code, a cryptographic hash is generated based on the content of your application. This hash is then encrypted using a private key that only you, the developer, possess. The resulting signature is attached to your application. When a user installs or runs your application, their system can decrypt the hash using your public key and compare it to a freshly generated hash of the application. If the hashes match, the code is verified as authentic.

Why is Code Signing Important?

• User Trust: Signed applications are less likely to be flagged as malicious by operating systems and antivirus software.
• Compliance: Code signing is required by Apple for macOS applications distributed outside the Mac App Store and recommended for Windows applications.
• Security: It prevents unauthorized modifications to your code, protecting both you and your users from potential security breaches.

What is Notarization?

Notarization is a security process required by Apple for macOS applications distributed outside the Mac App Store. It involves submitting your signed application to Apple, where it is scanned for malicious content. If your app passes the scan, Apple issues a notarization ticket that is “stapled” to your application, signaling to macOS that the app is safe to run.

How Does Notarization Work? After signing your app, you upload it to Apple’s notarization service. Apple performs a series of security checks and, if everything is in order, returns a notarization ticket. This ticket is then attached to your app, and you can distribute it with confidence that it won’t trigger security warnings on macOS.

Why is Notarization Important?

• macOS Compatibility: Starting with macOS Catalina, Apple requires all applications distributed outside the Mac App Store to be notarized. Without notarization, your app may be blocked from running.
• Enhanced Security: Notarization adds an extra layer of security by ensuring that your app is free of known malware before it reaches users.

Implementing Code Signing and Notarization in Electron

Step 1: Set Up Prerequisites

For macOS:

1. Apple Developer Account: You need an Apple Developer account to create certificates. Sign up at Apple Developer.
2. Install Xcode Command Line Tools: Run the following command in your terminal:

xcode-select --install

3. Create a Developer ID Application Certificate:

• Log in to the Apple Developer website.
• Navigate to “Certificates, Identifiers & Profiles” and create a “Developer ID Application” certificate.
• Download and install the certificate on your Mac.

For Windows:

1. Obtain a Code Signing Certificate:

• Purchase a code signing certificate from a trusted Certificate Authority (e.g., DigiCert, Comodo).
• Install the certificate on your Windows machine.

Step 2: Configure Electron Builder

Electron Builder is a tool that simplifies the packaging and distribution of Electron applications. It supports both code signing and notarization.

1. Install Electron Builder:

npm install electron-builder --save-dev

2. Configure package.json: Add the following configuration to your package.json under the build key:

{
  "build": {
    "appId": "com.example.yourapp",
    "mac": {
      "category": "public.app-category.utilities",
      "target": "dmg",
      "hardenedRuntime": true,
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist",
      "gatekeeperAssess": false,
      "sign": "Developer ID Application: Your Name (TeamID)"
    },
    "win": {
      "target": "nsis",
      "sign": {
        "certificateFile": "path/to/your/certificate.p12",
        "certificatePassword": "your-certificate-password"
      }
    }
  }
}

• mac: Configure settings for macOS, including Developer ID certificate and entitlements.
• win: Configure settings for Windows, including certificate path and password.

3. Create Entitlements File for macOS:

• Create a file named entitlements.mac.plist in the build directory with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.cs.allow-jit</key>
  <true/>
  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
  <true/>
  <key>com.apple.security.cs.debugger</key>
  <true/>
</dict>
</plist>

Step 3: Code Signing

For macOS:

Build and Sign the Application: Run the following command to build and sign your Electron app:

npm run electron:build --mac

//This command creates a signed .dmg file for distribution.

For Windows:

Build and Sign the Application: Run the following command to build and sign your Electron app:

npm run electron:build --win
//This command creates a signed .exe file for distribution.

Step 4: Notarization (macOS)

1. Install notarize CLI Tool: Install notarize using npm:

npm install @electron/notarize --save-dev

2. Add Notarization Script: In your package.json, add the following script under the build key:

npm install @electron/notarize --save-dev

Create a notarize.js file in the scripts directory with the following content:

const { notarize } = require('@electron/notarize');

exports.default = async function notarizing(context) {
  const { electronPlatformName, appOutDir } = context;

  if (electronPlatformName !== 'darwin') {
    return;
  }

  const appName = context.packager.appInfo.productFilename;

  await notarize({
    appBundleId: 'com.example.yourapp',
    appPath: `${appOutDir}/${appName}.app`,
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_ID_PASSWORD,
  });
};

3.Set Environment Variables: Set the following environment variables in your terminal or CI/CD pipeline:

export APPLE_ID="your-apple-id@example.com"
export APPLE_ID_PASSWORD="your-app-specific-password"

4. Run the Build and Notarize: Execute the build command:

npm run electron:build --mac

1. This command will build, sign, and notarize your macOS app. Once notarized, your app is ready for distribution.

Step 5: Distribute Your Application

After completing code signing and notarization:

• For macOS: Distribute the .dmg file. Users will have a smoother installation experience without security warnings.
• For Windows: Distribute the .exe file. The signed application will be trusted by the operating system and antivirus programs.

Conclusion

Implementing code signing and notarization is a critical step in ensuring the security and trustworthiness of your Electron applications. By following the steps outlined above, you can protect your users from potential threats and provide a smoother installation experience. Whether you’re targeting macOS or Windows, proper code signing and notarization will enhance the credibility and reliability of your software.

For detailed guidance on notarizing Electron applications, you can refer to Kilian Valkhof’s comprehensive tutorial: Notarizing Your Electron Application.

For an in-depth overview of code signing in Electron, you can explore the official Electron documentation: Electron Code Signing.

The official Electron documentation also provides a useful tutorial on code signing: Electron Code Signing Tutorial.