已归档: 很遗憾我不再积极使用这个项目,并且自2022年初以来就没有正确地维护它。我欢迎任何人分叉并接管这个项目。

gon - macOS公证的CLI和Go库

gon是一个简单、直接的工具,用于为macOS签名和公证你的CLI二进制文件。gon可以作为CLI使用,可以手动运行或在自动化流程中运行。它也可以作为Go库嵌入到用Go编写的项目中。gon可以签名和公证用任何语言编写的二进制文件。

从macOS Catalina (10.15)开始,苹果要求所有在Mac App Store外分发的软件都必须签名和公证。没有正确签名或公证的软件会显示一个错误消息,唯一可操作的选项是"移到垃圾桶"。即使从命令行,该软件也无法运行。对用户来说,解决方法很麻烦。gon帮助你自动化公证过程。

特性

为用任何语言编写的一个或多个文件进行代码签名
将签名文件打包成dmg或zip
公证软件包并等待公证完成
为多种输出格式并发公证
为支持的格式(dmg)添加公证票据,以便Gatekeeper验证可以离线工作

有关我们想支持但尚未支持的功能,请参见路线图。

示例

下面的示例运行gon对自身进行处理,生成zip和dmg。

gon示例

安装

安装gon最简单的方法是通过Homebrew:

$ brew install mitchellh/gon/gon

你也可以从releases页面下载适合你平台的发行版。这些都已签名和公证,可以在macOS 10.15+上开箱即用。

你也可以使用Go 1.13或更高版本,使用标准的go build从源代码编译。请确保启用了Go modules。

使用

gon需要一个配置文件,可以指定为文件路径或通过stdin传入。配置指定了gon用于签名和打包文件的所有设置。

gon必须在安装了XCode 11.0或更高版本的macOS机器上运行。 代码签名、公证和打包都需要只在macOS机器上可用的工具。

$ gon [flags] [CONFIG]

执行时,gon将对配置的文件进行签名、打包和公证,生成请求的格式。成功时gon将以0退出代码退出,失败时以任何其他值退出。

先决条件:获取Developer ID证书

在使用gon之前,你必须获取Developer ID证书。你可以通过网页或在Mac上通过Xcode本地完成此操作。如果你已经安装了Xcode,使用Xcode会更容易。

通过网页:

使用有效的Apple ID凭据登录developer.apple.com。你可能需要注册一个Apple开发者帐户。
导航到证书页面。
点击"+"图标,选择"Developer ID Application"并按照步骤操作。
下载证书后,双击将其导入到你的钥匙串。如果你在CI机器上构建,每台CI机器都必须在其钥匙串中有这个证书。

通过Xcode:

打开Xcode并转到Xcode => Preferences => Accounts
点击左下角的"+"并添加你的Apple ID(如果你还没有添加的话)。
选择你的Apple帐户,然后点击右下角的"Manage Certificates"。
点击左下角的"+"并点击"Developer ID Application"。
右键单击列表中新创建的证书,点击"export"并将文件导出为p12格式的证书。把它保存在某个地方。你将无法再次下载它。

要验证你是否正确完成了这个过程,你可以检查你的钥匙串:

$ security find-identity -v
  1) 97E4A93EAA8BAC7A8FD2383BFA459D2898100E56 "Developer ID Application: Mitchell Hashimoto (GK79KXBF4F)"
     1 valid identities found

你应该看到一个或多个证书,其中至少有一个是你的Developer ID Application证书。十六进制字符串前缀是你可以在配置文件中用来指定身份的值。

配置文件

配置文件可以指定报告的许可证允许/拒绝列表,特定依赖项的许可证覆盖等。配置文件格式是HCL或JSON。

示例:

source = ["./terraform"]
bundle_id = "com.mitchellh.example.terraform"

apple_id {
  username = "mitchell@example.com"
  password = "@env:AC_PASSWORD"
  provider = "UL304B4VGY"
}

sign {
  application_identity = "Developer ID Application: Mitchell Hashimoto"
}

dmg {
  output_path = "terraform.dmg"
  volume_name = "Terraform"
}

zip {
  output_path = "terraform.zip"
}

{
    "source" : ["./terraform"],
    "bundle_id" : "com.mitchellh.example.terraform",
    "apple_id": {
        "username" : "mitchell@example.com",
        "password":  "@env:AC_PASSWORD",
        "provider":  "UL304B4VGY"
    },
    "sign" :{
        "application_identity" : "Developer ID Application: Mitchell Hashimoto"
    },
    "dmg" :{
        "output_path":  "terraform.dmg",
        "volume_name":  "Terraform"
    },
    "zip" :{
        "output_path" : "terraform.zip"
    }
}

支持的配置:

source (array<string>) - 要签名、打包和公证的文件列表。如果你想用不同的身份签名多个文件或打包成不同的包,那么你应该用单独的配置调用gon。如果你使用带有notarize块的仅公证模式,这是可选的。
bundle_id (string) - 你的应用程序的bundle ID。你应该为你的应用程序选择一个唯一的标识符。你也可以在Apple注册这些。如果你使用带有notarize块的仅公证模式,这是可选的。
apple_id - 与用于公证的Apple ID相关的设置。
- username (string) - Apple ID用户名,通常是电子邮件地址。如果未设置,将默认使用AC_USERNAME环境变量。
- password (string) - 关联的Apple ID的密码。可以直接指定,也可以使用@keychain:<name>或@env:<name>来避免将明文密码直接放在配置文件中。@keychain:<name> 语法将从具有给定名称的macOS钥匙串加载密码。 @env:<name>语法将从命名的环境变量加载密码。如果未设置此值,我们将尝试使用AC_PASSWORD 环境变量作为默认值。
  
  注意: 如果你启用了双因素认证,密码必须是应用程序密码,而不是你的普通apple id密码。详情见故障排除。
- provider (string) - 在App Store Connect中使用多个团队时的App Store Connect提供商。如果未设置,我们将尝试读取AC_PROVIDER环境变量作为默认值。
sign - 与签名文件相关的设置。
- application_identity (string) - 用于签名应用程序的"Developer ID Application"证书的名称或ID。这接受macOS上codesign二进制文件的-s标志的任何有效值。有关接受值的详细文档,请参见man codesign。
- entitlements_file (string 可选) - plist格式.entitlements文件的完整路径,用于codesign的--entitlements参数
dmg (可选) - 与创建磁盘映像(dmg)作为输出相关的设置。只有在指定了这个选项时才会创建dmg。dmg还将有公证票据附加,以便可以离线验证, _不_需要互联网连接即可使用。
- output_path (string) - 创建zip存档的路径。如果此路径已存在, 它将被覆盖。source中的所有文件都将被复制到zip存档的根目录。
- volume_name (string) - 在finder中显示的已挂载dmg的名称,挂载的文件路径等。
zip (可选) - 与创建zip存档作为输出相关的设置。只有在指定了这个选项时才会创建zip存档。请注意,zip存档不支持附加,这意味着经过公证的zip存档中的文件在首次使用时将需要互联网连接来验证。
- output_path (string) - 创建zip存档的路径。如果此路径已存在, 它将被覆盖。source中的所有文件都将被复制到zip存档的根目录。

仅公证模式:

notarize (可选) - 用于公证已构建文件的设置。这是使用 source 选项的替代方法。此选项可以重复使用以公证多个文件。
- path (string) - 要公证的文件路径。必须是 Apple 支持的公证文件类型之一:dmg、pkg、app 或 zip。
- bundle_id (string) - 用于此公证的 bundle ID。这将代替顶层的 bundle_id (后者控制基于源的运行的值)。
- staple (bool 可选) - 控制公证成功后是否运行 stapler staple。这应该只为支持的文件类型设置(dmg、pkg 或 app)。

仅公证配置

你可以配置 gon 来公证已签名的文件。如果你正将 gon 集成到可能已支持创建 pkg、app 等文件的现有构建流程中,这会很有用。

由于公证要求包的有效负载也要签名,此模式假定你已对有效负载和包本身进行了代码签名。gon 不会在 notarize 块中签名你的包。请不要将此与设置了 source 且 gon 本身创建包的情况混淆,在那种情况下它也会签名这些包。

你也可以在指定 source 的同时使用此功能。在这种情况下, 我们将对 source 中指定的文件进行代码签名和打包,然后对这些结果以及 notarize 块中的内容进行公证。

HCL 示例和等效的 JSON 配置:

notarize {
  path = "/path/to/terraform.pkg"
  bundle_id = "com.mitchellh.example.terraform"
  staple = true
}

apple_id {
  username = "mitchell@example.com"
  password = "@env:AC_PASSWORD"
}

{
  "notarize": [{
    "path": "/path/to/terraform.pkg",
    "bundle_id": "com.mitchellh.example.terraform", 
    "staple": true
  }],

  "apple_id": {
     "username": "mitchell@example.com",
     "password": "@env:AC_PASSWORD"
  }
}

注意你可以指定多个 notarize 块来同时公证多个文件。

处理时间

公证过程需要将你的包提交给 Apple 并等待他们扫描。据我所知,Apple 没有提供公开的 SLA。

在开发 gon 和使用公证过程时,我发现该过程平均速度很快(< 10 分钟),但在某些情况下公证请求可能排队一小时或更长时间。

gon 会在进行时输出状态更新,并无限期等待公证完成。如果 gon 被中断,你可以使用 gon 提交后输出的请求 UUID 自行检查请求状态。

在自动化中使用

gon 旨在支持在自动化环境(如 CI 管道)中运行。在这种环境中,你应该使用 JSON 配置文件和 -log-json 标志来获取结构化日志输出。

机器可读输出

gon 始终在 stdout 上输出人类可读的内容(包括错误),并在 stderr 上输出所有日志。通过指定 -log-json,日志条目将以 JSON 结构化。你可以使用 jq 等工具或任何脚本语言处理 JSON 流来提取关键信息,如请求 UUID、状态等。

当 gon 在没有 TTY 的环境中运行时,人类可读输出将不会着色。这使其更适合输出日志。

示例:

$ gon -log-level=info -log-json ./config.hcl
...

注意你必须同时指定 -log-level 和 -log-json。 -log-level 标志通常启用日志记录。在自动化环境中,info 级别足以获得你想要的所有信息。

提示

首次运行时可能会多次提示输入密码。如果你点击"始终允许",则不会再次提示。这些提示来自 gon 子进程中的 Apple 软件,而不是来自 gon 本身。

我目前不知道如何自动化批准,因此对于构建机器,建议手动运行一次 gon。如果有人找到自动化的方法,请开一个 issue 告诉我,我会更新这个 README。

与 GoReleaser 一起使用

GoReleaser 是一个流行的全功能 Go 项目发布自动化工具。Gon 可以与 GoReleaser 一起使用,以增强签名步骤,在 GoReleaser 流程中公证你的二进制文件。

以下是用于签名二进制文件的 GoReleaser 配置示例:

builds:
- binary: foo
  id: foo
  goos:
  - linux
  - windows
  goarch:
  - amd64
# 注意我们需要为 macos 二进制单独构建:
- binary: foo
  id: foo-macos
  goos:
  - darwin
  goarch:
  - amd64
signs:
  - signature: "${artifact}.dmg"
    ids:
    - foo-macos # 这里我们只过滤 macos 构建 id
    # 你需要在 PATH 中有 gon
    cmd: gon
    # 你可以按照 gon 文档正确创建 gon.hcl 配置文件:
    # https://github.com/mitchellh/gon
    args:
    - gon.hcl
    artifacts: all

要了解更多信息,请参阅 GoReleaser 文档。