Navigator: requestMediaKeySystemAccess() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2019.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die requestMediaKeySystemAccess()-Methode der Navigator-Schnittstelle gibt ein Promise zurück, das ein MediaKeySystemAccess-Objekt liefert. Dieses kann verwendet werden, um auf ein bestimmtes Mediensystem zuzugreifen, das wiederum zur Erstellung von Schlüsseln zur Entschlüsselung eines Medienstreams verwendet werden kann.

Diese Methode ist Teil der Encrypted Media Extensions API, die Unterstützung für verschlüsselte Medien und DRM-geschützte Videos ins Web bringt.

Diese Methode kann nutzerseitige Auswirkungen haben, wie das Anfordern von Berechtigungen für den Zugriff auf Systemressourcen. Berücksichtigen Sie dies bei der Entscheidung, wann requestMediaKeySystemAccess() aufgerufen werden soll; diese Anfragen sollten nicht zu unpassenden Zeiten erfolgen. Im Allgemeinen sollte diese Funktion nur dann aufgerufen werden, wenn es an der Zeit ist, ein MediaKeys-Objekt zu erstellen und zu verwenden, indem die Methode createMediaKeys() des zurückgegebenen MediaKeySystemAccess-Objekts aufgerufen wird.

Syntax

requestMediaKeySystemAccess(keySystem, supportedConfigurations)

Parameter

keySystem

Ein String, der das Schlüsselsystem identifiziert. Zum Beispiel com.example.some-system oder org.w3.clearkey.

supportedConfigurations

Ein nicht-leeres Array von Objekten, das dem von MediaKeySystemAccess.getConfiguration zurückgegebenen Objekt entspricht. Das erste Element mit einer erfüllbaren Konfiguration wird verwendet.

Jedes Objekt kann die folgenden Eigenschaften haben:

Hinweis: Entweder videoCapabilities oder audioCapabilities können leer sein, aber nicht beide!

label Optional

Ein optionales Label für die Konfiguration, das standardmäßig "" ist. Dieses Label wird für Konfigurationen beibehalten, die mit MediaKeySystemAccess.getConfiguration abgerufen werden.

initDataTypes

Ein Array von Strings, das die Datentypnamen für die unterstützten Initialisierungsdatenformate anzeigt (standardmäßig ein leeres Array). Diese Namen sind wie "cenc", "keyids" und "webm" definiert im Encrypted Media Extensions Initialization Data Format Registry.

audioCapabilities

Ein Array unterstützter Audiofähigkeiten. Wenn das Array leer ist, unterstützt der Inhaltstyp keine Audiofähigkeiten.

Jedes Objekt im Array hat die folgenden Eigenschaften:

contentType: Ein String, der den Medien-MIME-Typ der Medienressource angibt, wie "audio/mp4;codecs=\"mp4a.40.2\". Beachten Sie, dass der leere String ungültig ist und dass, wenn die MIME-Typ-Definition Parameter wie codecs enthält, diese ebenfalls enthalten sein müssen.
encryptionScheme: Das Verschlüsselungsschema, das mit dem Inhaltstyp verbunden ist, wie cenc, cbcs, cbcs-1-9. Dieser Wert sollte von einer Anwendung gesetzt werden (standardmäßig null, was bedeutet, dass jedes Verschlüsselungsschema verwendet werden kann).
robustness: Das Robustheitsniveau, das mit dem Inhaltstyp verbunden ist. Der leere String zeigt an, dass jede Fähigkeit zur Entschlüsselung und Dekodierung des Inhaltstyps akzeptabel ist.

videoCapabilities

Ein Array unterstützter Videofähigkeiten. Die Objekte im Array haben die gleiche Form wie die in audioCapabilities.

distinctiveIdentifier

Ein String, der angibt, ob die Implementierung "unverwechselbare Identifikatoren" (oder unverwechselbare permanente Identifikatoren) für Operationen verwenden darf, die mit einem von dieser Konfiguration erstellten Objekt verbunden sind. Die zulässigen Werte sind:

required: Das zurückgegebene Objekt muss dieses Feature unterstützen.
optional: Das zurückgegebene Objekt kann dieses Feature unterstützen. Dies ist die Standardeinstellung.
not-allowed: Das zurückgegebene Objekt darf dieses Feature nicht unterstützen oder verwenden.

persistentState

Ein String, der angibt, ob das zurückgegebene Objekt in der Lage sein muss, Sitzungsdaten oder einen anderen Typ von Status zu speichern. Die Werte sind die gleichen wie für distinctiveIdentifier und haben die gleiche Bedeutung: required, optional (Standard), not-allowed. Nur "vorübergehende" Sitzungen dürfen erstellt werden, wenn persistenter Status nicht erlaubt ist.

sessionTypes

Ein Array von Strings, das die Sitzungsarten angibt, die unterstützt werden müssen. Zulässige Werte umfassen:

temporary: Eine Sitzung, für die die Lizenz, der/die Schlüssel und Aufzeichnungen oder Daten, die sich auf die Sitzung beziehen, nicht gespeichert werden. Die Anwendung muss solchen Speicher nicht verwalten. Implementierungen müssen diese Option unterstützen, und sie ist der Standard.
persistent-license: Eine Sitzung, für die die Lizenz (und möglicherweise andere mit der Sitzung verbundenen Daten) gespeichert werden. Ein Nachweis über die Lizenz und zugehörige Schlüssel bleibt erhalten, auch wenn die Lizenz zerstört wird, was eine Bestätigung liefert, dass die Lizenz und die Schlüssel, die sie enthält, vom Client nicht mehr verwendet werden können.

Rückgabewert

Ein Promise, das mit einem MediaKeySystemAccess-Objekt erfüllt wird, das die Mediensystemkonfiguration darstellt, die durch keySystem und supportedConfigurations beschrieben wird.

Ausnahmen

Im Falle eines Fehlers wird das zurückgegebene Promise mit einem DOMException abgelehnt, dessen Name angibt, welche Art von Fehler aufgetreten ist.

NotSupportedError DOMException: Entweder wird das angegebene keySystem von der Plattform oder dem Browser nicht unterstützt, oder keine der Konfigurationen, die von supportedConfigurations angegeben werden, kann erfüllt werden (wenn zum Beispiel keiner der in contentType angegebenen codecs verfügbar ist).
SecurityError DOMException: Die Verwendung dieses Features wurde durch Permissions-Policy: encrypted-media blockiert.
TypeError: Entweder ist keySystem ein leerer String oder das supportedConfigurations-Array ist leer.

Beispiele

Das folgende Beispiel zeigt, wie Sie requestMediaKeySystemAccess() verwenden könnten, indem Sie ein Schlüsselsystem und eine Konfiguration angeben.

const clearKeyOptions = [
  {
    initDataTypes: ["keyids", "webm"],
    audioCapabilities: [
      { contentType: 'audio/webm; codecs="opus"' },
      { contentType: 'audio/webm; codecs="vorbis"' },
    ],
    videoCapabilities: [
      { contentType: 'video/webm; codecs="vp9"' },
      { contentType: 'video/webm; codecs="vp8"' },
    ],
  },
];

navigator
  .requestMediaKeySystemAccess("org.w3.clearkey", clearKeyOptions)
  .then((keySystemAccess) => {
    /* use the access to get create keys */
  });

Spezifikationen

Specification
Encrypted Media Extensions # navigator-extension-requestmediakeysystemaccess