Native Manifeste

Native Manifeste sind JSON-Dateien, die auf dem Computer des Benutzers durch andere Mittel als den Erweiterungsinstallationsprozess bereitgestellt werden. Beispielsweise könnte ein nativer Manifest von einem Geräteadministrator oder einem nativen Anwendungsinstaller bereitgestellt werden.

Es gibt drei Arten von nativen Manifesten:

Native Messaging Manifeste Ermöglicht eine Funktion namens native messaging, bei der eine Erweiterung mit einer auf dem Gerät installierten nativen App kommunizieren kann.
Managed Storage Manifeste Definiert schreibgeschützte Daten, auf die eine Erweiterung mit der storage.managed API zugreifen kann.
PKCS #11 Manifeste Ermöglicht einer Erweiterung die Verwendung der pkcs11 API, um PKCS #11 Sicherheitsmodule aufzuzählen und in Firefox zu installieren.

Für alle nativen Manifeste müssen Sie die Datei so ablegen, dass der Browser sie findet. Der Abschnitt über den Speicherort des Manifests beschreibt, wie das gemacht wird. Unter Linux und macOS befinden sich die Dateien an einem festen Ort, unter Windows wird der Dateipfad in die Windows-Registrierung geschrieben.

Native Messaging Manifeste

Das Native Messaging Manifest ist eine Datei mit einem Namen, der dem von der Erweiterung in runtime.connectNative() oder runtime.sendNativeMessage() übergebenen String mit der Erweiterung .json entspricht. Es enthält ein JSON-Objekt mit diesen Eigenschaften:

Name Typ Beschreibung
name String

Name der nativen Anwendung.

Dieser muss mit dem Namen übereinstimmen, der in runtime.connectNative() oder runtime.sendNativeMessage() von der Erweiterung übergeben wird.

Unter Windows verwenden Sie diesen Wert als Namen des Registrierungsschlüssels, den Sie erstellen, der den Standort des Native Messaging Manifests enthält.

Der Name muss dem regulären Ausdruck entsprechen: "^\w+(\.\w+)*$". Dies bedeutet, dass er nur alphanumerische Zeichen (Klein- oder Großbuchstaben), Unterstriche und Punkte enthalten darf. Er darf nicht mit einem Punkt beginnen oder enden, und ein Punkt darf nicht auf einen anderen Punkt folgen.

description String Beschreibung der nativen Anwendung.
path String

Pfad zur nativen Anwendung.

Unter Windows kann dieser relativ zum Manifest selbst sein. Auf MacOS und Linux muss er absolut sein.

type String

Beschreibt die Methode, um die Erweiterung mit der App zu verbinden.

Nimmt nur den Wert "stdio" an, was bedeutet, dass Nachrichten von der App über die Standardeingabe (stdin) empfangen und über die Standardausgabe (stdout) gesendet werden.

allowed_extensions Array von String

Ein Array von Add-on-ID Werten. Jeder Wert repräsentiert eine Erweiterung, die berechtigt ist, mit dieser nativen Anwendung zu kommunizieren.

Hinweis: Dies bedeutet, dass Sie den browser_specific_settings Schlüssel in der manifest.json-Datei Ihrer Erweiterung einfügen sollten, damit Sie während der Entwicklung eine explizite ID festlegen.

Zum Beispiel hier ist der Inhalt der ping_pong.json Manifestdatei für die ping_pong native Anwendung aus dem native messaging Beispiel:

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

Dies erlaubt der Erweiterung mit der ID ping_pong@example.org, sich zu verbinden, indem sie den Namen ping_pong in die entsprechende runtime API-Funktion übergibt. Die native Anwendung befindet sich unter /path/to/native-messaging/app/ping_pong.py.

Managed Storage Manifeste

Das Managed Storage Manifest ist eine Datei mit einem Namen, der der im Schlüssel browser_specific_settings der Erweiterung angegebenen ID entspricht, mit der Erweiterung .json. Es enthält ein JSON-Objekt mit diesen Eigenschaften:

Name Typ Beschreibung
name String

Die ID der Erweiterung, die auf diesen Speicher zugreifen kann, angegeben als die ID im Schlüssel browser_specific_settings der Erweiterung.

Unter Windows verwenden Sie dies als Namen des Registrierungsschlüssels, den Sie erstellen, der den Standort des Manifests enthält.

description String Menschenlesbare Beschreibung, von Firefox ignoriert.
type String

Dies muss "storage" sein.
data Object

Ein JSON-Objekt, das alle gültigen JSON-Werte enthalten kann, einschließlich Strings, Zahlen, Booleans, Arrays oder Objekten. Dies wird zu den Daten im browser.storage.managed Speicherbereich.

Zum Beispiel wird im favourite-colour Beispiel das Managed Storage Daten in der Datei favourite-colour-examples@mozilla.org.json gesetzt, die Folgendes enthält:

json
{
  "name": "favourite-colour-examples@mozilla.org",
  "description": "ignored",
  "type": "storage",
  "data": {
    "color": "management thinks it should be blue!"
  }
}

Die favourite-colour-examples@mozilla.org Erweiterung greift dann mit folgendem Code auf die Daten zu:

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

PKCS #11 Manifeste

Das PKCS #11 Manifest ist eine Datei mit einem Namen, der dem Namen des PKCS #11 Moduls entspricht (wie in der pkcs11 API verwendet) mit der Erweiterung .json. Es enthält ein JSON-Objekt mit diesen Eigenschaften:

Name Typ Beschreibung
name String

Name des PKCS #11 Moduls.

Dieses muss mit dem in der pkcs11 API verwendeten Namen übereinstimmen.

Unter Windows verwenden Sie dies als Namen des Registrierungsschlüssels, den Sie erstellen, der den Standort des Manifests enthält.

Der Name muss dem regulären Ausdruck entsprechen: "^\w+(\.\w+)*$". Dies bedeutet, dass er nur alphanumerische Zeichen, Unterstriche und Punkte enthalten darf. Er darf nicht mit einem Punkt beginnen oder enden, und ein Punkt darf nicht auf einen anderen Punkt folgen.

description String

Beschreibung des PKCS #11 Moduls.

Dies stellt den freundlichen Namen für das Modul in der Benutzeroberfläche des Browsers bereit (zum Beispiel im "Sicherheitsgeräte" Dialog in Firefox).

path String

Pfad zum PKCS #11 Modul.

Der Pfad zum PKCS #11 Modul kann absolut oder relativ zum Manifest selbst sein.

type String Dies muss "pkcs11" sein.
allowed_extensions Array von String

Ein Array von Add-on-ID Werten. Jeder Wert repräsentiert eine Erweiterung, die berechtigt ist, mit dem Modul zu interagieren.

Hinweis: Dies bedeutet, dass Sie den browser_specific_settings Schlüssel in Ihrer manifest.json-Datei einfügen sollten, damit Sie während der Entwicklung eine explizite ID festlegen.

Zum Beispiel:

json
{
  "name": "my_module",
  "description": "My test module",
  "type": "pkcs11",
  "path": "/path/to/libpkcs11testmodule.dylib",
  "allowed_extensions": ["my-extension@mozilla.org"]
}

Mit diesem JSON-Manifest, gespeichert als my_module.json, könnte die my-extension@mozilla.org Erweiterung das Sicherheitsmodul unter /path/to/libpkcs11testmodule.dylib installieren, indem sie Code wie diesen verwendet:

js
browser.pkcs11.installModule("my_module");

Speicherort des Manifests

Unter Linux und macOS müssen Sie das Manifest an einem bestimmten Ort speichern. Unter Windows müssen Sie einen Registrierungsschlüssel erstellen, der auf den Speicherort des Manifests verweist.

Die detaillierten Regeln sind für alle Manifests gleich, abgesehen davon, dass die vorletzte Komponente des Pfades den Typ des Manifests identifiziert. Die unten stehenden Beispiele zeigen die Form für jeden der drei verschiedenen Typen. In allen Beispielen ist <name> der Wert der name Eigenschaft im Manifest.

Windows

Für globale Sichtbarkeit erstellen Sie einen Registrierungsschlüssel mit dem folgenden Namen:

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\NativeMessagingHosts\<name>

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\ManagedStorage\<name>

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\PKCS11Modules\<name>

Der Schlüssel sollte einen einzigen Standardwert haben, der der Pfad zum Manifest ist.

Warnung: Seit Firefox 64 wird zuerst die 32-Bit-Registry-Ansicht Wow6432Node für diese Schlüssel geprüft, gefolgt von der "nativen" Registry-Ansicht. Verwenden Sie, was für Ihre Anwendung geeignet ist.

Für Firefox 63 und älter: Dieser Schlüssel sollte nicht unter Wow6432Node erstellt werden, selbst wenn die App 32-Bit ist. Frühere Versionen des Browsers suchen den Schlüssel immer unter der "nativen" Ansicht der Registry, nicht unter der 32-Bit-Emulation. Um sicherzustellen, dass der Schlüssel in der "nativen" Ansicht erstellt wird, können Sie die KEY_WOW64_64KEY oder KEY_WOW64_32KEY Flags bei RegCreateKeyEx übergeben. Siehe Accessing an Alternate Registry View.

Für Benutzer-Visibilität erstellen Sie einen Registrierungsschlüssel mit dem folgenden Namen:

HKEY_CURRENT_USER\SOFTWARE\Mozilla\NativeMessagingHosts\<name>

HKEY_CURRENT_USER\SOFTWARE\Mozilla\ManagedStorage\<name>

HKEY_CURRENT_USER\SOFTWARE\Mozilla\PKCS11Modules\<name>

Der Schlüssel sollte einen einzigen Standardwert haben, der der Pfad zum Manifest ist.

macOS

Für globale Sichtbarkeit speichern Sie das Manifest in:

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

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

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

Für Benutzer-Visibilität speichern Sie das Manifest in:

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

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

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

Linux

Für globale Sichtbarkeit speichern Sie das Manifest in entweder:

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

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

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

oder:

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

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

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

Für Benutzer-Visibilität speichern Sie das Manifest in:

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

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

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