Native-Manifeste

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

Es gibt drei Typen 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 Ermöglicht einer Erweiterung die Verwendung 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 über den Standort des Manifests beschreibt, wie dies zu tun ist. Auf Linux und macOS befinden sich die Dateien an einem festen Ort, auf Windows wird der Dateispeicherort in der Windows-Registrierungsdatenbank festgehalten.

Native Messaging Manifeste

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

Name Typ Beschreibung
name String

Name der nativen Anwendung.

Dies muss mit dem von der Erweiterung an runtime.connectNative() oder runtime.sendNativeMessage() übergebenen Namen übereinstimmen.

Unter Windows verwenden Sie diesen Wert als Namen des Registrierungsschlüssels, den Sie erstellen, um den Speicherort des Native Messaging Manifests anzugeben.

Der Name muss regulären Ausdruck entsprechen: "^\w+(\.\w+)*$". Das bedeutet, dass er nur (kleine oder große) 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 darf dieser relativ zum Manifest selbst sein. Unter macOS und Linux muss er absolut sein.

type String

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

Nimmt den Wert "stdio" an, was bedeutet, dass Nachrichten von der App mithilfe des Standardeingangs (stdin) empfangen und mithilfe des Standardausgangs (stdout) gesendet werden.

allowed_extensions Array von Strings

Ein Array von Add-on-IDs. Jeder Wert repräsentiert eine Erweiterung, die mit dieser nativen Anwendung kommunizieren darf.

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

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"]
}

Dadurch kann die Erweiterung mit der ID ping_pong@example.org eine Verbindung herstellen, 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.

Managed Storage Manifeste

Das Managed Storage Manifest ist eine Datei mit einem Namen, der mit der in der Erweiterung unter dem Schlüssel browser_specific_settings angegebenen ID übereinstimmt, mit der Erweiterung .json. Es enthält ein JSON-Objekt mit folgenden Eigenschaften:

Name Typ Beschreibung
name String

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

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, die von Firefox ignoriert wird.
type String

Dies muss "storage" sein.
data Objekt

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

Zum Beispiel wird im favourite-colour Beispiel Managed Storage Data in der Datei 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 Erweiterung favourite-colour-examples@mozilla.org 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 mit dem Namen des PKCS #11 Moduls übereinstimmt (wie in der pkcs11 API verwendet) und die Erweiterung .json aufweist. Es enthält ein JSON-Objekt mit folgenden 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+)*$". Das bedeutet, dass er nur kleine 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 setzt den benutzerfreundlichen Namen für das Modul in der Benutzeroberfläche des Browsers (zum Beispiel im Dialogfeld "Sicherheitsgeräte" in Firefox).

path String

Pfad zum PKCS #11 Modul.

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

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

Ein Array von Add-on-IDs. Jeder Wert repräsentiert eine Erweiterung, die mit dem Modul interagieren darf.

Hinweis: Dies bedeutet, dass Sie den browser_specific_settings Schlüssel in Ihrer manifest.json-Datei der Erweiterung einschließen 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"]
}

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

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

Manifeststandort

Auf 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 verschiedenen Typen. In allen Beispielen ist <name> der Wert der Namen-Eigenschaft im nativen 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 Weg 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 geeignet ist.

Für Firefox 63 und ältere Versionen: 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 unter der "nativen" Ansicht der Registrierung, nicht in der 32-Bit-Emulation. 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 übergeben. Siehe Zugriff auf eine alternative Registrierungsansicht.

Für benutzerspezifische Sichtbarkeit 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 den Pfad zum Manifest angibt.

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 benutzerspezifische 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

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 benutzerspezifische Sichtbarkeit speichern Sie das Manifest in:

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

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

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