Подписание кода

Подписание кода приложения

В этом руководстве описано, как подписывать приложения Wails для macOS, Windows и Linux. Wails v3 предоставляет встроенные инструменты командной строки для подписания кода, нотариального заверения и управления ключами PGP.

• macOS — подписывайте и нотариально заверяйте приложения для macOS
• Windows — подписывайте исполняемые файлы и пакеты для Windows
• Linux — подписывайте пакеты DEB и RPM ключами PGP

Матрица кроссплатформенного подписания

Эта матрица показывает, что можно подписывать на каждой исходной платформе:

Средства подписания

Wails автоматически выбирает лучшее из доступных средств подписания:

При работе на целевой платформе Wails использует нативные инструменты для максимальной совместимости. При кросс-компиляции используется встроенная поддержка подписания.

Быстрый старт

Быстрее всего настроить подписание с помощью мастера настройки:

wails3 setup

Эта команда записывает общую конфигурацию подписания в ~/.config/wails/defaults.yaml, которая учитывается при подписании на всех платформах (см. раздел «Приоритет конфигурации»). На этапе настройки подписания мастер:

• Определяет, какие инструменты подписания установлены для выбранной целевой платформы — на любом хосте, — и показывает команду их установки для вашей ОС (например, brew install gnupg, sudo apt install osslsigncode, winget install GnuPG.Gpg4win).
• В macOS выводит список сертификатов Developer ID из вашей связки ключей.
• Для Linux выводит список ваших ключей GPG и позволяет создать и экспортировать новый ключ.
• Для Windows позволяет с помощью OpenSSL создать самоподписанный сертификат (для тестирования).
• Безопасно сохраняет пароли в системном хранилище учетных данных (а не в Taskfile-файлах).

Приоритет конфигурации

При запуске задачи подписания значение каждого параметра определяется в следующем порядке (используется первое совпадение):

1. Явный флаг, переданный wails3 tool sign (например, --pgp-key, --certificate, --identity).
2. Соответствующая переменная Taskfile проекта (PGP_KEY, SIGN_CERTIFICATE/SIGN_THUMBPRINT, SIGN_IDENTITY, …).
3. Глобальная конфигурация в ~/.config/wails/defaults.yaml (созданная командой wails3 setup).

Таким образом, переменные Taskfile служат необязательными переопределениями: если переменная не задана, используется ключ, сертификат или удостоверение, заданные глобально. Если значение отсутствует во всех трех источниках, команда подписания выводит понятное сообщение об ошибке с инструкцией по настройке.

Конфигурация для отдельного проекта

Чтобы настроить подписание только для одного проекта, а не глобально, запустите мастер настройки проекта из каталога этого проекта — он запишет vars в файлы build/<platform>/Taskfile.yml проекта:

wails3 setup signing                                   # all detected platforms
wails3 setup signing --platform windows --platform linux

Настройка вручную

Также можно вручную изменить Taskfile-файлы для соответствующих платформ. Измените раздел vars в начале каждого файла:

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  KEYCHAIN_PROFILE: "my-notarize-profile"
  # ENTITLEMENTS: "build/darwin/entitlements.plist"

wails3 task darwin:sign           # Sign only
wails3 task darwin:sign:notarize  # Sign and notarize

vars:
  SIGN_CERTIFICATE: "path/to/certificate.pfx"
  # Or use thumbprint instead:
  # SIGN_THUMBPRINT: "certificate-thumbprint"
  # TIMESTAMP_SERVER: "http://timestamp.digicert.com"

wails3 task windows:sign           # Sign executable
wails3 task windows:sign:installer # Sign NSIS installer

vars:
  PGP_KEY: "path/to/signing-key.asc"
  # SIGN_ROLE: "builder"  # Options: origin, maint, archive, builder

wails3 task linux:sign:deb       # Sign DEB package
wails3 task linux:sign:rpm       # Sign RPM package
wails3 task linux:sign:packages  # Sign all packages

Состояние подписи также можно проверить непосредственно средствами системы:

# List available macOS code-signing identities
security find-identity -v -p codesigning

# List PGP keys (Linux package signing)
gpg --list-keys

Для интерактивной настройки подписи для всех платформ используйте мастер:

wails3 setup signing

Подписание кода в macOS

Предварительные требования

• Учётная запись Apple Developer ($99 в год)
• Сертификат Developer ID Application
• Установленные инструменты командной строки Xcode

Удостоверения для подписи

Проверьте доступные удостоверения для подписи:

security find-identity -v -p codesigning

Вывод:

Found 2 signing identities:

  Developer ID Application: Your Company (ABCD1234) [valid]
    Hash: ABC123DEF456...

  Apple Development: your@email.com (XYZ789) [valid]
    Hash: DEF789ABC123...

Конфигурация

Отредактируйте build/darwin/Taskfile.yml и задайте переменные подписи:

vars:
  SIGN_IDENTITY: "Developer ID Application: Your Company (TEAMID)"
  KEYCHAIN_PROFILE: "my-notarize-profile"
  ENTITLEMENTS: "build/darwin/entitlements.plist"

Затем выполните:

wails3 task darwin:sign           # Build, package, and sign
wails3 task darwin:sign:notarize  # Build, package, sign, and notarize

Разрешения

Разрешения определяют, к каким возможностям имеет доступ приложение. Приложениям Wails обычно требуются разные разрешения для разработки и рабочей среды:

• Разработка: требуются разрешения на JIT-компиляцию, неподписанную память и отладку
• Рабочая среда: минимальные разрешения (только доступ к сети)

Чтобы создать оба файла, воспользуйтесь мастером интерактивной настройки:

wails3 setup entitlements

Будут созданы:

• build/darwin/entitlements.dev.plist — для сборок разработки
• build/darwin/entitlements.plist — для рабочих/подписанных сборок

Доступные предустановки:\

Затем задайте в переменных Taskfile значение ENTITLEMENTS, указывающее на соответствующий файл.

Нотаризация

Apple требует нотаризации всех распространяемых приложений.

xcrun notarytool store-credentials "my-notarize-profile" \
  --apple-id "your@email.com" \
  --team-id "ABCD1234" \
  --password "app-specific-password"

wails3 task darwin:sign:notarize

spctl --assess --verbose=2 bin/MyApp.app

Подписание кода в Windows

Предварительные требования

• Сертификат для подписи кода (от DigiCert, Sectigo и т. п.)
• Для нативного подписания в Windows: установленный Windows SDK (для signtool.exe)
• Для кроссплатформенного подписания из macOS/Linux: osslsigncode (на этапе подписания wails3 setup отображается команда установки для конкретной хост-системы)

Создание самоподписанного сертификата (для тестирования)

Если вам нужно лишь протестировать процесс подписания, запустите wails3 setup, откройте вкладку Windows на этапе подписания и выберите Создать самоподписанный сертификат. С помощью OpenSSL будет создан сертификат для подписания кода .pfx, а путь к нему будет сохранён в глобальной конфигурации.

Конфигурация

Отредактируйте build/windows/Taskfile.yml и задайте переменные подписания:

vars:
  SIGN_CERTIFICATE: "path/to/certificate.pfx"
  # Or use thumbprint instead:
  # SIGN_THUMBPRINT: "certificate-thumbprint"
  # TIMESTAMP_SERVER: "http://timestamp.digicert.com"

Затем выполните:

wails3 task windows:sign           # Build and sign executable
wails3 task windows:sign:installer # Build and sign NSIS installer

Кроссплатформенное подписывание

Исполняемые файлы Windows можно подписывать на любой платформе. Одна и та же конфигурация Taskfile и одни и те же команды работают в macOS и Linux.

Поддерживаемые форматы Windows

Подписывание пакетов Linux

Пакеты Linux (DEB и RPM) подписываются с помощью ключей PGP/GPG. В отличие от подписывания кода в Windows и macOS, подписывание пакетов Linux подтверждает, что пакет получен из доверенного источника, а не то, что операционная система считает код доверенным.

Предварительные требования

• Пара ключей PGP (можно создать с помощью Wails)

Создание ключа PGP

Проще всего воспользоваться мастером настройки: запустите wails3 setup, откройте вкладку Linux на этапе подписания и выберите Создать новый ключ GPG. Мастер:

• создаёт ключ RSA 4096 в вашей связке ключей GPG (оставьте парольную фразу пустой, чтобы ключ можно было использовать без участия пользователя и он подходил для CI),
• экспортирует его в ~/.wails/signing/<keyid>.asc (это файл, которым подписывается сборка) и
• сохраняет идентификатор ключа и путь к экспортированному файлу в ~/.config/wails/defaults.yaml, чтобы ключ автоматически использовался при подписании.

Это также можно сделать вручную с помощью gpg:

# Interactive — the wizard will prompt for name, email, key size and expiry.
gpg --full-generate-key

# Export the key pair to ASCII-armoured files for the Taskfile to consume.
gpg --armor --export-secret-keys "your@email.com" > signing-key.asc
gpg --armor --export "your@email.com" > signing-key.pub.asc

Рекомендуемые параметры: RSA, 4096 бит, срок действия — 1 год, защита надёжным паролем.

Конфигурация

Отредактируйте build/linux/Taskfile.yml и задайте переменные подписания:

vars:
  PGP_KEY: "path/to/signing-key.asc"
  # SIGN_ROLE: "builder"  # Options: origin, maint, archive, builder

Затем выполните:

wails3 task linux:sign:deb       # Build and sign DEB package
wails3 task linux:sign:rpm       # Build and sign RPM package
wails3 task linux:sign:packages  # Build and sign all packages

Роли при подписании DEB

Для пакетов DEB роль при подписании можно указать с помощью SIGN_ROLE:

• origin: подпись от создателя пакета
• maint: подпись от сопровождающего пакета
• archive: подпись от сопровождающего архива
• builder: подпись от сборщика пакета (по умолчанию)

Кроссплатформенное подписание

Пакеты Linux можно подписывать на любой платформе. Одна и та же конфигурация Taskfile и одни и те же команды работают в Windows и macOS.

Просмотр сведений о ключе

gpg --show-keys signing-key.asc

Вывод:

pub   rsa4096 2024-01-15 [SC] [expires: 2025-01-15]
      1234 5678 90AB CDEF 1234 5678 90AB CDEF 1234 5678
uid                      Your Name <your@email.com>

Проверка пакетов Linux

# Verify DEB signature
dpkg-sig --verify myapp_1.0.0_amd64.deb

# Verify RPM signature
rpm --checksig myapp-1.0.0.x86_64.rpm

Распространение открытого ключа

Для проверки пакетов пользователям необходим ваш открытый ключ:

# Export public key for distribution
gpg --armor --export "your@email.com" > myapp-signing.pub.asc

# Users can import it:
# For DEB (apt):
sudo apt-key add myapp-signing.pub.asc
# Or for modern apt:
sudo cp myapp-signing.pub.asc /etc/apt/trusted.gpg.d/

# For RPM:
sudo rpm --import myapp-signing.pub.asc

Интеграция с GitHub Actions

В средах CI пароли передаются через переменные среды, а не через системное хранилище учётных данных:

Также можно передавать переменные Taskfile напрямую:

wails3 task darwin:sign SIGN_IDENTITY="$SIGN_IDENTITY" KEYCHAIN_PROFILE="$KEYCHAIN_PROFILE"

Рабочий процесс для macOS

name: Build and Sign macOS

on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - name: Install Wails
        run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest

      - name: Import Certificate
        env:
          CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE }}
          CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
        run: |
          echo $CERTIFICATE_BASE64 | base64 --decode > certificate.p12
          security create-keychain -p "" build.keychain
          security default-keychain -s build.keychain
          security unlock-keychain -p "" build.keychain
          security import certificate.p12 -k build.keychain -P "$CERTIFICATE_PASSWORD" -T /usr/bin/codesign
          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "" build.keychain

      - name: Store Notarization Credentials
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
        run: |
          xcrun notarytool store-credentials "notarize-profile" \
            --apple-id "$APPLE_ID" \
            --team-id "$APPLE_TEAM_ID" \
            --password "$APPLE_APP_PASSWORD"

      - name: Build, Sign, and Notarize
        env:
          SIGN_IDENTITY: ${{ secrets.MACOS_SIGN_IDENTITY }}
        run: |
          wails3 task darwin:sign:notarize \
            SIGN_IDENTITY="$SIGN_IDENTITY" \
            KEYCHAIN_PROFILE="notarize-profile"

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: MyApp-macOS
          path: bin/*.app

Рабочий процесс для Windows

name: Build and Sign Windows

on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - name: Install Wails
        run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest

      - name: Import Certificate
        env:
          CERTIFICATE_BASE64: ${{ secrets.WINDOWS_CERTIFICATE }}
        run: |
          $certBytes = [Convert]::FromBase64String($env:CERTIFICATE_BASE64)
          [IO.File]::WriteAllBytes("certificate.pfx", $certBytes)

      - name: Build and Sign
        env:
          WAILS_WINDOWS_CERT_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
        run: |
          wails3 task windows:sign SIGN_CERTIFICATE=certificate.pfx

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: MyApp-Windows
          path: bin/*.exe

Кроссплатформенный рабочий процесс (исполнитель Linux)

Подписывайте пакеты Windows и Linux с помощью одного исполнителя Linux:

name: Build and Sign (Cross-Platform)

on:
  push:
    tags: ['v*']

jobs:
  build-and-sign:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.23'

      - name: Install Wails
        run: go install github.com/wailsapp/wails/v3/cmd/wails3@latest

      - name: Install Build Dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y nsis rpm

      # Import certificates
      - name: Import Certificates
        env:
          WINDOWS_CERT_BASE64: ${{ secrets.WINDOWS_CERTIFICATE }}
          PGP_KEY_BASE64: ${{ secrets.PGP_PRIVATE_KEY }}
        run: |
          echo "$WINDOWS_CERT_BASE64" | base64 -d > certificate.pfx
          echo "$PGP_KEY_BASE64" | base64 -d > signing-key.asc

      # Build and sign Windows
      - name: Build and Sign Windows
        env:
          WAILS_WINDOWS_CERT_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
        run: |
          wails3 task windows:sign SIGN_CERTIFICATE=certificate.pfx

      # Build and sign Linux packages
      - name: Build and Sign Linux Packages
        env:
          WAILS_PGP_PASSWORD: ${{ secrets.PGP_PASSWORD }}
        run: |
          wails3 task linux:sign:packages PGP_KEY=signing-key.asc

      # Cleanup secrets
      - name: Cleanup
        if: always()
        run: rm -f certificate.pfx signing-key.asc

      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: signed-binaries
          path: |
            bin/*.exe
            bin/*.deb
            bin/*.rpm

Справочник по CLI

wails3 setup signing

Интерактивный мастер настройки подписания для проекта.

wails3 setup signing [flags]

Flags:
  --platform    Platform to configure (darwin, windows, linux). Repeatable.
                If omitted, auto-detects which platforms to configure from the build directory.

Мастер поможет выполнить следующие действия:

• macOS: выбрать сертификат Developer ID и настроить учётные данные для нотариального заверения (вызывает xcrun notarytool store-credentials).
• Windows: выбрать файл сертификата или отпечаток, задать пароль и сервер меток времени.
• Linux: использовать существующий ключ PGP или создать новый (вызывает gpg), а также настроить роль при подписании.

wails3 setup entitlements

Интерактивный мастер настройки прав macOS.

wails3 setup entitlements [flags]

Flags:
  --output    Output path for entitlements.plist (default: build/darwin/entitlements.plist)

Предустановки:

• Разработка: создаёт entitlements.dev.plist с правами для JIT-компиляции, отладки и доступа к сети
• Рабочая среда: создаёт entitlements.plist с минимальным набором прав
• Оба варианта: создаёт оба файла (рекомендуется)
• App Store: создаёт права для работы в песочнице Mac App Store
• Пользовательская настройка: позволяет выбрать отдельные права и целевой файл

wails3 sign

Подписывает двоичные файлы и пакеты для текущей или указанной платформы. Это команда-обёртка, которая вызывает соответствующую задачу подписания для конкретной платформы.

wails3 sign
wails3 sign GOOS=darwin
wails3 sign GOOS=windows
wails3 sign GOOS=linux

Команда запускает соответствующую задачу <platform>:sign, которая использует конфигурацию подписания из Taskfile.

wails3 tool sign

Низкоуровневая команда для непосредственного подписания определённого файла. Используется внутри файлов Taskfile.

wails3 tool sign [flags]

Общие флаги:\

Флаги для Windows и macOS:\

Флаги только для macOS:\

Флаги только для Windows:\

Флаги только для Linux:\

Проверка состояния подписи (штатными инструментами)

В v3 команды wails3 signing нет. Для проверки состояния подписи используйте непосредственно штатные инструменты:

Устранение неполадок

Проблемы в macOS

«Сертификат Developer ID не найден»

• Убедитесь, что сертификат установлен в связке ключей
• С помощью security find-identity -v -p codesigning проверьте, не истёк ли срок его действия
• Убедитесь, что у вас есть сертификат «Developer ID Application», а не только «Apple Development»

«Нотариальное заверение завершилось с ошибкой»

• Проверьте журнал нотариального заверения: xcrun notarytool log <submission-id> --keychain-profile <profile>
• Убедитесь, что усиленная среда выполнения включена
• Убедитесь, что приложение не содержит неподписанных исполняемых файлов

«Не удалось выполнить codesign»

• Убедитесь, что связка ключей разблокирована: security unlock-keychain
• Проверьте права доступа к файлам в пакете приложения

Проблемы в Windows

«Сертификат не найден»

• Убедитесь, что путь к сертификату указан правильно
• Проверьте пароль сертификата
• Убедитесь, что сертификат действителен (срок его действия не истёк и он не отозван)

«Ошибка сервера меток времени»

• Попробуйте другой сервер меток времени:
  • http://timestamp.digicert.com
  • http://timestamp.sectigo.com
  • http://timestamp.comodoca.com

Проблемы в Linux

«Недействительный ключ PGP»

• Убедитесь, что файл ключа имеет текстовый формат ASCII Armor
• С помощью gpg --show-keys <key.asc> проверьте, не истёк ли срок действия ключа
• Убедитесь, что пароль указан правильно

«Не удалось проверить подпись»

• Убедитесь, что открытый ключ импортирован правильно
• Убедитесь, что пакет не был изменён после подписания

Дополнительные ресурсы

Официальная документация

• Руководство Apple по подписанию кода
• Документация Apple по нотариальному заверению
• Документация Microsoft по подписанию кода
• Подписание пакетов Debian
• Подписание пакетов RPM