Native Manifeste

Native Manifeste sind JSON-Dateien, die auf dem Computer des Benutzers auf anderem Wege als dem Erweiterungsinstallationsprozess bereitgestellt werden. Zum Beispiel könnte ein natives Manifest von einem Geräteadministrator oder einem nativen Anwendungsinstallationsprogramm bereitgestellt werden.

Es gibt drei Arten von nativen Manifesten:

Native Messaging Manifeste Aktiviert ein Feature namens Native Messaging, bei dem eine Erweiterung mit einer auf dem Gerät installierten nativen App kommunizieren kann.
Verwaltete Speicher-Manifeste Definiert schreibgeschützte Daten, auf die eine Erweiterung mit der storage.managed API zugreifen kann.
PKCS #11 Manifeste Ermöglicht einer Erweiterung die Nutzung der pkcs11 API, um PKCS #11 Sicherheitsmodule aufzulisten und in Firefox zu installieren.

Für alle nativen Manifeste müssen Sie die Datei so speichern, dass der Browser sie finden kann. Der Abschnitt zur Manifest-Speicherort beschreibt, wie dies getan wird. Unter Linux und macOS befinden sich die Dateien an einem festen Speicherort, unter Windows wird der Speicherort der Datei in der Windows-Registrierung festgelegt.

Native Messaging Manifeste

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

Name Typ Beschreibung
name String

Name der nativen Anwendung.

Dies 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 Speicherort des Native Messaging Manifests enthält.

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

description String Beschreibung der nativen Anwendung.
path String

Pfad zur nativen Anwendung.

Unter Windows kann dies relativ zum Manifest selbst sein. Unter macOS und Linux muss es absolut sein.

type String

Beschreibt die Methode, mit der die Erweiterung mit der App verbunden wird.

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

allowed_extensions Array von String

Ein Array von Add-on ID Werten. Jeder Wert steht für eine Erweiterung, die mit dieser nativen Anwendung kommunizieren darf.

Hinweis: Dies bedeutet, dass Sie den browser_specific_settings Schlüssel in die manifest.json Datei Ihrer Erweiterung einfügen möchten, um während der Entwicklung eine explizite ID festzulegen.

Zum Beispiel zeigt das folgende Beispiel den 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, zu verbinden, indem sie den Namen ping_pong in die relevante runtime API-Funktion übergibt. Die native Anwendung befindet sich unter /path/to/native-messaging/app/ping_pong.py.

Verwaltete Speicher-Manifeste

Das verwaltete Speicher-Manifest ist eine Datei mit einem Namen, der mit der im browser_specific_settings Schlüssel der Erweiterung spezifizierten ID und der .json Erweiterung übereinstimmt. Es enthält ein JSON-Objekt mit diesen Eigenschaften:

Name Typ Beschreibung
name String

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

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

description String Menschlich lesbare Beschreibung, von Firefox ignoriert.
type String

Dies muss "storage" sein.
data Objekt

Ein JSON-Objekt, das beliebige gültige 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 Favorite Colour Beispiel die verwaltete Speicherungs-Daten in der Datei mit dem Namen favourite-colour-examples@mozilla.org.json festgelegt, 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 dem folgenden 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 mit dem Namen des PKCS #11 Moduls (wie in der pkcs11 API verwendet) und der .json Erweiterung übereinstimmt. Es enthält ein JSON-Objekt mit diesen Eigenschaften:

Name Typ Beschreibung
name String

Name des PKCS #11 Moduls.

Dies muss mit dem Namen übereinstimmen, der in der pkcs11 API verwendet wird.

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

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

description String

Beschreibung des PKCS #11 Moduls.

Dies setzt den benutzerfreundlichen Namen für das Modul in der Benutzeroberfläche des Browsers (zum Beispiel im Dialog "Sicherheitsgeräte" 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 steht für eine Erweiterung, die mit dem Modul interagieren darf.

Hinweis: Dies bedeutet, dass Sie den browser_specific_settings Schlüssel in die manifest.json Datei Ihrer Erweiterung einfügen möchten, um während der Entwicklung eine explizite ID festzulegen.

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 bei /path/to/libpkcs11testmodule.dylib mit folgendem Code installieren:

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

Manifest-Speicherort

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 Manifesttypen gleich, außer dass die vorletzte Komponente des Pfades den Typ des Manifests identifiziert. Die folgenden Beispiele zeigen die Form für jede der drei unterschiedlichen Typen. In allen Beispielen ist <name> der Wert der Namenseigenschaft im nativen Manifest.

Windows

Für globale Sichtbarkeit erstellen Sie einen Registrierungsschlüssel mit folgendem 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, welcher der Pfad zum Manifest ist.

Warnung: Seit Firefox 64 wird die 32-Bit-Registrierungsansicht Wow6432Node zuerst für diese Schlüssel überprüft, gefolgt von der "nativen" Registrierungsansicht. Verwenden Sie diejenige, die für Ihre Anwendung angemessen 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 werden immer nach dem Schlüssel unter der "nativen" Ansicht der Registrierung suchen, nicht 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 in RegCreateKeyEx übergeben. Siehe Accessing an Alternate Registry View.

Für Benutzersichtbarkeit erstellen Sie einen Registrierungsschlüssel mit folgendem 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, welcher 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 Benutzersichtbarkeit 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 Benutzersichtbarkeit speichern Sie das Manifest in:

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

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

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