Fuchsia 软件包网址

Fuchsia 软件包网址如下所示：

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

它由以下组件组成，这些组件构成了完整的软件包网址：

网址格式

fuchsia-pkg 网址协议结合了识别特征，以便建立一种引用代码库、软件包或资源的方法，具体取决于包含哪些部分。

语法

必需

fuchsia-pkg://<repository>[/<package-name>[?hash=<package-hash>][#<resource-path>]]

Fuchsia 软件包网址的架构为 fuchsia-pkg://。

方案必须采用小写形式；Fuchsia 网址解析器 (//src/lib/fuchsia-url) 会拒绝大写字符。

代码库

软件包网址包含一个代码库主机名，用于标识软件包的来源。主机名定义为一系列以点 (.) 分隔的 LDH 标签，每个标签由 1 到 63 个以下 latin-1 字符组成，并且不以连字符 (-) 开头或结尾：

  • 数字（0 到 9）
  • 小写字母（a 到 z）
  • 连字符 (-)

不允许使用其他字符。

主机名的总长度上限为 253 个字符（包括英文句点）。

代码库根验证（已知来源）

代码库的根角色（一个或多个公钥或私钥对的仲裁）会建立信任链，以便通过加密方式验证软件包的真实性、完整性和新鲜度。根角色为更受限的角色签署密钥，然后这些密钥用于签署软件包元数据和目标本身。如需了解详情，请参阅 TUF 安全性以及 TUF 角色和元数据。

如需验证软件包是否真实，您必须验证下载该软件包的代码库是否真实。

为此，设备上会维护一个已知源代码库及其公钥的列表。来自未知来源的软件包将被拒绝，但在某些 build 类型中，可以在运行时添加新的代码库。

语法

必需

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

示例

fuchsia-pkg://fuchsia.com

软件包名称

软件包名称是用于标识软件包的符号标签。软件包名称用于在代码库中查找软件包元数据。软件包元数据必须由代码库根目录信任的角色签名。

软件包名称由最多 255 个以下 latin-1 字符按任意顺序组成：

  • 数字（0 到 9）
  • 小写字母（a 到 z）
  • 连字符 (-)
  • 下划线 (_)
  • 经期 (.)

不允许使用其他字符。

每个软件包名称在代码库中的所有软件包中必须是唯一的。不同代码库中的软件包即使名称相同，也会被视为不同的软件包。

语法

必需

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

代码库和软件包名称之间必须有一个 / 字符。

示例

  • fuchsia-pkg://fuchsia.com/fuchsia-shell-utils
  • fuchsia-pkg://fuchsia.com/fuchsia-shell-fonts
  • fuchsia-pkg://fuchsia.com/fuchsia-shell-scenic

软件包哈希

软件包哈希是软件包 meta.far 的 merkleroot。由于软件包的元数据会对软件包文件的内容地址进行编码，因此对软件包的元数据或内容所做的任何更改都会产生不同的软件包哈希，从而可以区分软件包的每个唯一修订版本。

如果缺少软件包哈希，软件包解析器会从客户端可用的最新软件包修订版本中提取资源。

软件包哈希表示为十六进制编码的字符串，该字符串恰好由 64 个以下 latin-1 字符组成：数字（0 到 9）和小写字母（a 到 f）。不允许使用任何其他字符。

语法

可选

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

仅在指定了软件包名称的情况下有效。

查询必须仅由 ?hash= 后跟软件包哈希组成；Fuchsia 网址解析器会拒绝任何其他查询参数或第二个 hash= 参数。

示例

fuchsia-pkg://google.com/chrome?hash=80e8721f4eba5437c8b6e1604f6ee384f42aed2b6dfbfd0b616a864839cd7b4a#meta/webview.component

资源路径

资源路径是用于标识软件包中资源的 UTF-8 字符串。它是一个相对文件路径，由以单个 / 分隔的片段组成。每个段都必须是非空的 UTF-8 字节序列，长度不超过 255 字节，不等于 . 或 ..，并且不得包含 NUL (\0) 或换行符 (\n)。此定义与 Fuchsia 文件系统路径匹配，但它要求使用有效的 UTF-8（解析器将 %HH 转义解码为 UTF-8 并拒绝其他字节序列），拒绝换行符，并且对总路径长度没有限制。

在网址中，单个 # 字符位于经过百分号编码的资源路径之前。

Fuchsia 网址解析器会按照 RFC 3986 中的规定，对 #<resource-path> 中的每个 %HH 转义（其中 HH 是两个十六进制数字，不区分大小写）进行解码，然后验证解码后的资源路径。由于解析器在将资源路径拆分为多个片段之前会解码转义字符，因此 %2F 会充当片段分隔符。

您必须对以下字符进行百分比编码，因为如果这些字符在 # 之后未经编码，解析器会拒绝它们：

字符 编码
空格 %20
双引号 (") %22
数字符号 (#) %23
百分号 (%)，除非它位于 %HH 转义序列的开头 %25
小于号 (<) %3C
大于号 (>) %3E
反引号 (`) %60
控制字符 U+0000 至 U+001F %00到 %1F
控制字符 U+007F 至 U+009F %7F 和 %C2%80 转换为 %C2%9F
任何其他非 ASCII 字符 其 UTF-8 字节，例如 é 的 %C3%A9

由于每个 % 都必须以 %HH 转义开头，因此解析器会拒绝后面没有两个十六进制数字的 %（例如，在 100% 或 %zz 中）。您可以添加任何其他未经编码的 ASCII 字符。要求对非 ASCII 字符进行百分号编码可确保每个网址都采用 ASCII 字符，这样一来，不可见或看起来像其他字符的字符（例如不换行空格、从右到左覆盖或西里尔文 о [U+043E]）就无法隐藏在网址中。由于解码后的资源路径仍必须遵循上述规则，因此 %00 (NUL) 和 %0A（换行符）即使经过编码也是无效的。

规范网址使用 WHATWG 片段百分比编码集以及 % 和 # 对资源路径进行编码。这会使用大写十六进制数字对上表中的字符进行精确编码。

例如，hello/unicode/%F0%9F%98%81 会解码为 hello/unicode/😁，而解析器会拒绝未编码的 #hello/unicode/😁。同样，data/my%20file.txt 会解码为 data/my file.txt，data/100%25.txt 会解码为 data/100%.txt，而解析器会拒绝未编码的 #data/my file.txt 或 #data/100%.txt。

语法

可选

仅在指定了软件包时有效。

fuchsia-pkg://<repository>/<package-name>?hash=<package-hash>#<resource-path>

示例

  • fuchsia-pkg://fuchsia.com/fuchsia-shell-utils#bin/ls
  • fuchsia-pkg://google.com/chrome#meta/webview.component
  • fuchsia-pkg://google.com/chrome#lib/mylibrary.so

构建软件包网址

您可以使用可修改的变量来构建软件包网址，然后复制该网址：

fuchsia-pkg://repository/package-name?hash=package-hash#resource-path