原生清单

原生清单是 JSON 文件，由除扩展安装过程之外的其他方式在用户的计算机上提供。例如，原生清单可以由设备管理员或原生应用程序安装程序提供。

原生清单有三种类型

原生消息传递清单	启用称为原生消息传递的功能，其中扩展可以与设备上安装的原生应用程序通信。
托管存储清单	定义扩展可以使用`storage.managed` API 访问的只读数据。
PKCS #11 清单	使扩展能够使用`pkcs11` API 枚举 PKCS #11 安全模块并在 Firefox 中安装它们。

对于所有原生清单，您都需要存储该文件，以便浏览器可以找到它。有关如何执行此操作的信息，请参见有关清单位置的部分。在 Linux 和 macOS 上，这些文件位于固定位置，在 Windows 上，文件位置被写入 Windows 注册表。

原生消息传递清单

原生消息传递清单是一个文件，其名称与扩展传递到runtime.connectNative() 或runtime.sendNativeMessage() 中的字符串匹配，并带有 .json 扩展名。它包含一个具有以下属性的 JSON 对象

名称	类型	描述
`名称`	字符串	原生应用程序的名称。这必须与扩展传递到`runtime.connectNative()` 或`runtime.sendNativeMessage()` 中的名称匹配。在 Windows 上，请使用此值作为您创建的注册表项的名称，其中包含原生消息传递清单的位置。名称必须与正则表达式匹配：`"^\w+(\.\w+)*$"`。这意味着它只能包含（小写或大写）字母数字字符、下划线和点。它不能以点开头或结尾，点后面不能紧跟另一个点。
`描述`	字符串	原生应用程序的描述。
`路径`	字符串	原生应用程序的路径。在 Windows 上，这可能是相对于清单本身的。在 MacOS 和 Linux 上，它必须是绝对路径。
`类型`	字符串	描述用于将扩展与应用程序连接的方法。仅接受值 `"stdio"`，这表示消息通过标准输入 (`stdin`) 接收，并通过标准输出 (`stdout`) 发送。
`允许的扩展`	字符串数组	附加组件 ID 值的数组。每个值代表一个允许与该原生应用程序通信的扩展。注意：这意味着您需要在扩展的 `manifest.json` 文件中包含 `browser_specific_settings` 键，以便在开发过程中设置明确的 ID。

例如，以下是来自原生消息传递示例的 ping_pong 原生应用程序的 ping_pong.json 清单文件的内容

json

{
  "name": "ping_pong",
  "description": "Example host for native messaging",
  "path": "/path/to/native-messaging/app/ping_pong.py",
  "type": "stdio",
  "allowed_extensions": ["[email protected]"]
}

这允许具有 ID [email protected] 的扩展通过将名称 ping_pong 传递到相关的runtime API 函数进行连接。原生应用程序位于 /path/to/native-messaging/app/ping_pong.py 中。

托管存储清单

托管存储清单是一个文件，其名称与扩展的browser_specific_settings 键中指定的 ID 匹配，并带有 .json 扩展名。它包含一个具有以下属性的 JSON 对象

名称	类型	描述
`名称`	字符串	可以访问此存储的扩展的 ID，以扩展的 `browser_specific_settings` 键中指定的 ID 形式给出。在 Windows 上，将其用作您创建的注册表项的名称，其中包含清单的位置。
`描述`	字符串	人类可读的描述，被 Firefox 忽略。
`类型`	字符串	这必须是 `"storage"`。
`数据`	对象	一个 JSON 对象，它可以包含任何有效的 JSON 值，包括字符串、数字、布尔值、数组或对象。这将成为 `browser.storage.managed` 存储区域中的数据。

例如，在favourite-colour 示例中，管理存储数据在名为 [email protected] 的文件中设置，该文件包含

json

{
  "name": "[email protected]",
  "description": "ignored",
  "type": "storage",
  "data": {
    "color": "management thinks it should be blue!"
  }
}

然后，[email protected] 扩展使用以下代码访问数据

let storageItem = browser.storage.managed.get("color");
storageItem.then((res) => {
  console.log(`Managed color is: ${res.color}`);
});

PKCS #11 清单

PKCS #11 清单是一个文件，其名称与 PKCS #11 模块的名称匹配（如 pkcs11 API 中所用），并带有 .json 扩展名。它包含一个具有以下属性的 JSON 对象

名称	类型	描述
`名称`	字符串	PKCS #11 模块的名称。这必须与`pkcs11` API 中使用的名称匹配。在 Windows 上，将其用作您创建的注册表项的名称，其中包含清单的位置。名称必须与正则表达式匹配：`"^\w+(\.\w+)*$"`。这意味着它只能包含小写字母数字字符、下划线和点。它不能以点开头或结尾，点后面不能紧跟另一个点。
`描述`	字符串	PKCS #11 模块的描述。这将为浏览器 UI 中的模块设置友好名称（例如，Firefox 中的“安全设备”对话框）。
`路径`	字符串	PKCS #11 模块的路径。 PKCS #11 模块的路径可以是绝对路径或相对于清单本身的路径。
`类型`	字符串	这必须是 `"pkcs11"`。
`允许的扩展`	字符串数组	附加组件 ID 值的数组。每个值代表一个允许与该模块交互的扩展。注意：这意味着您需要在扩展的 `manifest.json` 文件中包含 `browser_specific_settings` 键，以便在开发过程中设置明确的 ID。

例如

json

{
  "name": "my_module",
  "description": "My test module",
  "type": "pkcs11",
  "path": "/path/to/libpkcs11testmodule.dylib",
  "allowed_extensions": ["[email protected]"]
}

给定此 JSON 清单（保存为 my_module.json），[email protected] 扩展可以使用以下代码安装位于 /path/to/libpkcs11testmodule.dylib 的安全模块

browser.pkcs11.installModule("my_module");

清单位置

在 Linux 和 macOS 上，您需要将清单存储在特定位置。在 Windows 上，您需要创建一个指向清单位置的注册表项。

详细规则对于所有清单类型都相同，只是路径的倒数第二部分标识了清单的类型。以下示例显示了三种不同类型的形式。在所有示例中，<name> 是清单中 name 属性的值。

Windows

要实现全局可见性，请使用以下名称创建一个注册表项

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\NativeMessagingHosts\<name>

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\ManagedStorage\<name>

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\PKCS11Modules\<name>

该项应该有一个默认值，即指向清单的路径。

警告： 从 Firefox 64 开始，将首先检查 32 位注册表视图 Wow6432Node 中的这些键，然后检查“本机”注册表视图。请根据您的应用程序选择合适的视图。

对于 Firefox 63 及更早版本： 此键 *不应* 在 Wow6432Node 下创建，即使应用程序是 32 位的。浏览器先前版本将始终在注册表的“本机”视图中查找此键，而不是 32 位模拟视图。为了确保在“本机”视图中创建此键，您可以在 RegCreateKeyEx 中传递 KEY_WOW64_64KEY 或 KEY_WOW64_32KEY 标志。请参见访问备用注册表视图。

要实现每用户可见性，请使用以下名称创建注册表键

HKEY_CURRENT_USER\SOFTWARE\Mozilla\NativeMessagingHosts\<name>

HKEY_CURRENT_USER\SOFTWARE\Mozilla\ManagedStorage\<name>

HKEY_CURRENT_USER\SOFTWARE\Mozilla\PKCS11Modules\<name>

该项应该有一个默认值，即指向清单的路径。

macOS

要实现全局可见性，请将清单存储在以下位置

/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json

/Library/Application Support/Mozilla/ManagedStorage/<name>.json

/Library/Application Support/Mozilla/PKCS11Modules/<name>.json

要实现每用户可见性，请将清单存储在以下位置

~/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json

~/Library/Application Support/Mozilla/ManagedStorage/<name>.json

~/Library/Application Support/Mozilla/PKCS11Modules/<name>.json

Linux

要实现全局可见性，请将清单存储在以下任一位置

/usr/lib/mozilla/native-messaging-hosts/<name>.json

/usr/lib/mozilla/managed-storage/<name>.json

/usr/lib/mozilla/pkcs11-modules/<name>.json

或

/usr/lib64/mozilla/native-messaging-hosts/<name>.json

/usr/lib64/mozilla/managed-storage/<name>.json

/usr/lib64/mozilla/pkcs11-modules/<name>.json

要实现每用户可见性，请将清单存储在以下位置

~/.mozilla/native-messaging-hosts/<name>.json

~/.mozilla/managed-storage/<name>.json

~/.mozilla/pkcs11-modules/<name>.json