Native Manifeste

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

Es gibt drei Arten von nativen Manifesten:

Native Messaging Manifeste Aktiviert 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 mithilfe der storage.managed API zugreifen kann.
PKCS #11 Manifeste Erlaubt es einer Erweiterung, die pkcs11 API zu verwenden, 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 Verortung von Manifesten beschreibt, wie Sie dies tun. 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 übergebenen String in runtime.connectNative() oder runtime.sendNativeMessage() entspricht, mit der Endung .json. Es enthält ein JSON-Objekt mit folgenden Eigenschaften:

Name Typ Beschreibung
name String

Name der nativen Anwendung.

Dies muss dem Namen entsprechen, der von der Erweiterung in runtime.connectNative() oder runtime.sendNativeMessage() ü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 (groß- oder kleingeschriebene) alphanumerische Zeichen, Unterstriche und Punkte enthalten darf. Er darf nicht mit einem Punkt beginnen oder enden, und ein Punkt darf nicht von einem weiteren Punkt gefolgt werden.

description String Beschreibung der nativen Anwendung.
path String

Pfad zur nativen Anwendung.

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

type String

Beschreibt die Methode, die verwendet wird, 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 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 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 der Name ping_pong in die relevante runtime API-Funktion übergeben wird. 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 in den browser_specific_settings Schlüssel der Erweiterung angegebenen ID entspricht, mit der .json-Erweiterung. Es enthält ein JSON-Objekt mit folgenden Eigenschaften:

Name Typ Beschreibung
name String

Die ID der Erweiterung, die auf diesen Speicher zugreifen kann, gemäß der in der Erweiterung angegebenen ID browser_specific_settings Schlüssel.

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

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

Dies muss "storage" sein.
data Objekt

Ein JSON-Objekt, das beliebige gültige JSON-Werte wie Strings, Zahlen, Booleans, Arrays oder Objekte enthalten kann. Dies wird zu den Daten im browser.storage.managed Speicherbereich.

Zum Beispiel, im Lieblingsfarbe Beispiel werden die Managed Storage Daten in der Datei favourite-colour-examples@mozilla.org.json gesetzt, die 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 auf die Daten zu, indem sie Code wie diesen verwendet:

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 .json-Erweiterung. Es enthält ein JSON-Objekt mit folgenden Eigenschaften:

Name Typ Beschreibung
name String

Name des PKCS #11 Moduls.

Dies muss dem Namen entsprechen, der in der pkcs11 API verwendet wird.

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

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

description String

Beschreibung des PKCS #11 Moduls.

Dies legt den freundlichen Namen für das Modul in der Benutzeroberfläche des Browsers fest (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 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 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"]
}

Angenommen, dieses JSON Manifest wird als my_module.json gespeichert, könnte die my-extension@mozilla.org Erweiterung das Sicherheitsmodul unter /path/to/libpkcs11testmodule.dylib mit folgendem Code installieren:

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

Verortung von Manifesten

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, außer dass die vorletzte Komponente des Pfades den Typ des Manifests identifiziert. Die folgenden 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 die 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: Ab 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 passend 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 immer nach dem Schlüssel in der "nativen" Ansicht der Registry, nicht im 32-Bit-Emulationsmodus. Um sicherzustellen, dass der Schlüssel in der "nativen" Ansicht erstellt wird, können Sie die Flags KEY_WOW64_64KEY oder KEY_WOW64_32KEY in RegCreateKeyEx verwenden. Siehe Zugreifen auf eine alternative Registry-Ansicht.

Für die 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 die 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 die 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 entweder in:

/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 die Benutzersichtbarkeit speichern Sie das Manifest in:

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

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

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