Hardwareunterstützungs-App (HSA): Schritte für Treiberentwickler

Artikel
06/15/2023

Eine Hardwareunterstützungs-App (HSA) ist eine gerätespezifische App, die mit einem bestimmten Treiber oder RPC-Endpunkt (Remote Procedure Call) gekoppelt ist.

Um eine Store-App einem Treiber zuzuordnen, reservieren Sie zunächst einen speziellen Wert, der als benutzerdefinierte Funktion bezeichnet wird. Lassen Sie dann den Zugriff auf Apps zu, die die Funktion ankündigen, und stellen Sie die Funktion für den App-Entwickler bereit. Auf dieser Seite werden diese Schritte für den Treiberentwickler beschrieben.

Die Schritte für den App-Entwickler werden unter Hardwaresupport-App (HSA): Schritte für App-Entwickler beschrieben.

HSA ist eines der drei DCH-Entwurfsprinzipien von Windows-Treibern.

Reservieren einer benutzerdefinierten Funktion

Reservieren Sie zunächst eine benutzerdefinierte Funktion:

Email Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) mit den folgenden Informationen:
- Kontaktinformationen
- Unternehmensname
- Name der Funktion (muss eindeutig sein und auf den Besitzer verweisen)
- Auf welche Ressourcen muss die Funktion zugreifen?
- Sicherheits- oder Datenschutzbedenken
- Welche Datenereignisse werden an den Partner verarbeitet?
  - Würden die Ereignisse persönliche Bezeichner wie genaue Benutzerspeicherorte, Kennwörter, IP-Adresse, PUID, Geräte-ID, CID, Benutzername und Kontaktdaten enthalten)?
  - Verbleiben die Datenereignisse auf dem Benutzergerät, oder werden sie an den Partner gesendet?
- Auf welche Daten bietet Ihre Funktion Zugriff?
- Welchen Nutzen bietet diese Funktion für den Endbenutzer?
- Schließen Sie die Herausgeber-ID der Microsoft Store-App ein. Erstellen Sie einen skelettierten App-Eintrag auf der Microsoft Store-Seite, um einen Eintrag zu erhalten. Weitere Informationen zum Reservieren Ihrer App-PFN finden Sie unter Erstellen Ihrer App durch Reservieren eines Namens.
Wenn die Anforderung genehmigt wurde, sendet Microsoft eine E-Mail an einen eindeutigen Namen einer benutzerdefinierten Funktionszeichenfolge im Format CompanyName.capabilityName_PublisherID zurück.

Jetzt können Sie die benutzerdefinierte Funktion verwenden, um den Zugriff auf einen RPC-Endpunkt oder einen Treiber zuzulassen.

Zulassen des Zugriffs auf einen RPC-Endpunkt für eine UWP-App mithilfe der benutzerdefinierten Funktion

Führen Sie die folgenden Schritte aus, um den Zugriff auf einen RPC-Endpunkt auf eine UWP-App zuzulassen, die über die benutzerdefinierte Funktion verfügt:

Rufen Sie DeriveCapabilitySidsFromName auf, um den Namen der benutzerdefinierten Funktion in eine Sicherheits-ID (SID) zu konvertieren.
Fügen Sie die SID zusammen mit allen anderen SIDs, die für den Sicherheitsdeskriptor Ihres RPC-Endpunkts erforderlich sind, zu Ihrem zugriffszugelassenen ACE hinzu.
Erstellen Sie einen RPC-Endpunkt mithilfe der Informationen aus dem Sicherheitsdeskriptor.

Eine Implementierung von oben finden Sie im RPC-Servercode im Beispiel für benutzerdefinierte Funktionen.

Zulassen des Zugriffs auf einen Treiber auf eine UWP-App mithilfe der benutzerdefinierten Funktion

Um den Zugriff auf einen Treiber auf eine UWP-App mit der benutzerdefinierten Funktion zuzulassen, fügen Sie der INF-Datei oder der Treiberquelle einige Zeilen hinzu.

Geben Sie in der INF-Datei Ihre benutzerdefinierte Funktion wie folgt an:

[WDMPNPB003_Device.NT.Interfaces]
AddInterface= {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz},,AddInterfaceSection

[AddInterfaceSection]
AddProperty= AddInterfaceSection.AddProps

[AddInterfaceSection.AddProps]
; DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities
{026e516e-b814-414b-83cd-856d6fef4822}, 8, 0x2012,, "CompanyName.myCustomCapabilityName_MyStorePubId"

Alternativ können Sie im Treiber wie folgt vorgehen:

WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = {};
WCHAR customCapabilities[] = L"CompanyName.myCustomCapabilityName_MyStorePubId\0";

WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT(
   &PropertyData,
   &m_VendorDefinedSubType,
   &DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities);

Status = WdfDeviceAssignInterfaceProperty(
    m_FxDevice,
    &PropertyData,
    DEVPROP_TYPE_STRING_LIST,
    ARRAYSIZE(customCapabilities),
    reinterpret_cast<PVOID>(customCapabilities));

Ersetzen Sie durch zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz die GUID für die schnittstelle, die verfügbar gemacht werden soll. Ersetzen Sie CompanyName durch Ihren Unternehmensnamen, myCustomCapabilityName durch einen namen, der innerhalb Ihres Unternehmens eindeutig ist, und MyStorePubId durch Ihre Herausgeber-Store-ID.

Ein Beispiel für den direkt oben gezeigten Treibercode finden Sie im Treiberpaketinstallations-Toolkit für universelle Treiber.

Um die Eigenschaft im Kernelmodus festzulegen, verwenden Sie Code wie den folgenden:

#if defined(NTDDI_WIN10_RS2) && (NTDDI_VERSION >= NTDDI_WIN10_RS2)

//
// Adding Custom Capability:
//
// Adds a custom capability to device interface instance that allows a Windows
// Store device app to access this interface using Windows.Devices.Custom namespace.
// This capability can be defined either in INF or here as shown below. In order
// to define it from the INF, uncomment the section "OsrUsb Interface installation"
// from the INF and remove the block of code below.
//

static const wchar_t customCapabilities[] = L"microsoft.hsaTestCustomCapability_q536wpkpf5cy2\0";

status = g_pIoSetDeviceInterfacePropertyData(&symbolicLinkName,
                                              &DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities,
                                              0,
                                              0,
                                              DEVPROP_TYPE_STRING_LIST,
                                              sizeof(customCapabilities),
                                              (PVOID)&customCapabilities);

if (!NT_SUCCESS(status)) {
    TraceEvents(TRACE_LEVEL_ERROR, DBG_PNP,
                "IoSetDeviceInterfacePropertyData failed to set custom capability property  %!STATUS!\n", status);
    goto Error;
}

#endif

Vorbereiten der signierten SCCD-Datei (Custom Capability Descriptor)

Eine signierte SCCD-Datei (Signed Custom Capability Descriptor) ist eine signierte XML-Datei, die die Verwendung einer oder mehrerer benutzerdefinierter Funktionen autorisiert. Der Besitzer des Treibers oder RPC-Endpunkts gewährt dem App-Entwickler die benutzerdefinierte Funktion, indem er diese Datei bereitstellt.

Aktualisieren Sie zunächst die benutzerdefinierte Funktionszeichenfolge, um die SCCD-Datei vorzubereiten. Verwenden Sie das folgende Beispiel als Ausgangspunkt:

<?xml version="1.0" encoding="utf-8"?>
<CustomCapabilityDescriptor xmlns="http://schemas.microsoft.com/appx/2016/sccd" xmlns:s="http://schemas.microsoft.com/appx/2016/sccd">
<CustomCapabilities>
    <CustomCapability Name="microsoft.hsaTestCustomCapability_q536wpkpf5cy2"></CustomCapability>
</CustomCapabilities>
<AuthorizedEntities>
    <AuthorizedEntity AppPackageFamilyName="MicrosoftHSATest.Microsoft.SDKSamples.Hsa.CPP_q536wpkpf5cy2" CertificateSignatureHash="ca9fc964db7e0c2938778f4559946833e7a8cfde0f3eaa07650766d4764e86c4"></AuthorizedEntity>
</AuthorizedEntities>
<Catalog>0000</Catalog>
</CustomCapabilityDescriptor>

Als Nächstes ruft der Besitzer der benutzerdefinierten Funktion den Paketfamiliennamen (Package Family Name, PFN) und den Signaturhash vom App-Entwickler ab und aktualisiert diese Zeichenfolgen in der SCCD-Datei.

Hinweis

Die App muss nicht direkt mit dem Zertifikat signiert werden, aber das angegebene Zertifikat muss Teil der Zertifikatkette sein, die die App signiert.

Nach Abschluss der SCCD sendet der Besitzer der Funktion eine E-Mail an Microsoft zur Signatur. Microsoft gibt die signierte SCCD an den Funktionsbesitzer zurück.

Der Besitzer der Funktion sendet dann die SCCD an den App-Entwickler. Der App-Entwickler schließt die signierte SCCD in das App-Manifest ein. Informationen zu den Aufgaben des App-Entwicklers finden Sie unter Hardwaresupport-App (HSA): Schritte für App-Entwickler.

Einschränken des Umfangs einer SCCD

Zu Testzwecken kann ein Besitzer von benutzerdefinierten Funktionen die Installation einer Hardwareunterstützungs-App auf Computer im Entwicklermodus einschränken.

Fügen Sie dazu DeveloperModeOnly hinzu, bevor Sie die SCCD von Microsoft signiert bekommen:

<?xml version="1.0" encoding="utf-8"?>
<CustomCapabilityDescriptor xmlns="http://schemas.microsoft.com/appx/2016/sccd" xmlns:s="http://schemas.microsoft.com/appx/2016/sccd">
<CustomCapabilities>
    <CustomCapability Name="microsoft.hsaTestCustomCapability_q536wpkpf5cy2"></CustomCapability>
</CustomCapabilities>
<AuthorizedEntities>
    <AuthorizedEntity AppPackageFamilyName="MicrosoftHSATest.Microsoft.SDKSamples.Hsa.CPP_q536wpkpf5cy2" CertificateSignatureHash="ca9fc964db7e0c2938778f4559946833e7a8cfde0f3eaa07650766d4764e86c4"></AuthorizedEntity>
</AuthorizedEntities>
<Catalog>0000</Catalog>
<DeveloperModeOnly Value="true" />
</CustomCapabilityDescriptor>

Die resultierende signierte SCCD funktioniert nur auf Geräten im Entwicklermodus.

Zulassen, dass jede App eine benutzerdefinierte Funktion verwendet

Es wird empfohlen, autorisierte Entitäten (Apps) anzugeben, die eine benutzerdefinierte Funktion verwenden können. In einigen Fällen können Sie jedoch zulassen, dass jede App eine SCCD enthält. Ab Windows 10 Version 1809 können Sie dazu AllowAny zum AuthorizedEntities-Element hinzufügen. Da die bewährte Methode darin besteht, autorisierte Entitäten in der SCCD-Datei zu deklarieren, geben Sie eine Begründung für die Verwendung von AllowAny an, wenn Sie Ihre von Microsoft signierte SCCD übermitteln.

<?xml version="1.0" encoding="utf-8"?>
<CustomCapabilityDescriptor xmlns="http://schemas.microsoft.com/appx/2018/sccd" xmlns:s="http://schemas.microsoft.com/appx/2018/sccd">
<CustomCapabilities>
    <CustomCapability Name="microsoft.hsaTestCustomCapability_q536wpkpf5cy2"></CustomCapability>
</CustomCapabilities>
<AuthorizedEntities AllowAny="true"/>
<Catalog>0000</Catalog>
</CustomCapabilityDescriptor>

Die resultierende signierte SCCD wird in jedem App-Paket überprüft.

Mehrere SCCDs

Ab Windows 10 Version 1803 können Apps benutzerdefinierte Funktionen aus einer oder mehreren SCCD-Dateien deklarieren. Platzieren Sie die SCCD-Dateien im Stammverzeichnis des App-Pakets.

Zusammenfassung der SCCD-Signatursequenz

Das folgende Diagramm fasst die oben beschriebene Sequenz zusammen:

Abrufen einer SCCD-Signatur.

SCCD-XML-Schema

Es folgt das formale XML-XSD-Schema für eine SCCD-Datei. Verwenden Sie dieses Schema, um Ihre SCCD zu überprüfen, bevor Sie sie zur Überprüfung übermitteln. Informationen zum Importieren eines Schemas und zur Validierung mit IntelliSense finden Sie unter Überprüfung des Schemacaches und XML-Dokuments .

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
  xmlns:xs="https://www.w3.org/2001/XMLSchema"
  targetNamespace="http://schemas.microsoft.com/appx/2016/sccd"
  xmlns:s="http://schemas.microsoft.com/appx/2016/sccd"
  xmlns="http://schemas.microsoft.com/appx/2016/sccd">

  <xs:element name="CustomCapabilityDescriptor" type="CT_CustomCapabilityDescriptor">
    <xs:unique name="Unique_CustomCapability_Name">
      <xs:selector xpath="s:CustomCapabilities/s:CustomCapability"/>
      <xs:field xpath="@Name"/>
    </xs:unique>
  </xs:element>

  <xs:complexType name="CT_CustomCapabilityDescriptor">
    <xs:sequence>
      <xs:element ref="CustomCapabilities" minOccurs="1" maxOccurs="1"/>
      <xs:element ref="AuthorizedEntities" minOccurs="1" maxOccurs="1"/>
      <xs:element ref="DeveloperModeOnly" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="Catalog" minOccurs="1" maxOccurs="1"/>
      <xs:any minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="CustomCapabilities" type="CT_CustomCapabilities" />

  <xs:complexType name="CT_CustomCapabilities">
    <xs:sequence>
      <xs:element ref="CustomCapability" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="CustomCapability">
    <xs:complexType>
      <xs:attribute name="Name" type="ST_CustomCapability" use="required"/>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name="ST_NonEmptyString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="32767"/>
      <xs:pattern value="[^\s]|([^\s].*[^\s])"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="ST_CustomCapability">
    <xs:annotation>
      <xs:documentation>Custom capabilities should be a string in the form of Company.capabilityName_PublisherId</xs:documentation>
    </xs:annotation>
    <xs:restriction base="ST_NonEmptyString">
      <xs:pattern value="[A-Za-z0-9][-_.A-Za-z0-9]*_[a-hjkmnp-z0-9]{13}"/>
      <xs:minLength value="15"/>
      <xs:maxLength value="255"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="AuthorizedEntities" type="CT_AuthorizedEntities" />

  <xs:complexType name="CT_AuthorizedEntities">
    <xs:sequence>
      <xs:element ref="AuthorizedEntity" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="AuthorizedEntity" type="CT_AuthorizedEntity" />

  <xs:complexType name="CT_AuthorizedEntity">
    <xs:attribute name="CertificateSignatureHash" type="ST_CertificateSignatureHash" use="required"/>
    <xs:attribute name="AppPackageFamilyName" type="ST_NonEmptyString" use="required"/>
  </xs:complexType>

  <xs:simpleType name="ST_CertificateSignatureHash">
    <xs:restriction base="ST_NonEmptyString">
      <xs:pattern value="[A-Fa-f0-9]+"/>
      <xs:minLength value="64"/>
      <xs:maxLength value="64"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="DeveloperModeOnly">
    <xs:complexType>
      <xs:attribute name="Value" type="xs:boolean" use="required"/>
    </xs:complexType>
  </xs:element>

  <xs:element name="Catalog" type="ST_Catalog" />

  <xs:simpleType name="ST_Catalog">
    <xs:restriction base="xs:string">
      <xs:pattern value="[A-Za-z0-9\+\/\=]+"/>
      <xs:minLength value="4"/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

Das folgende Schema ist auch ab Windows 10, Version 1809 gültig. Es ermöglicht einer SCCD, jedes App-Paket als autorisierte Entität zu deklarieren.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
  xmlns:xs="https://www.w3.org/2001/XMLSchema"
  targetNamespace="http://schemas.microsoft.com/appx/2018/sccd"
  xmlns:s="http://schemas.microsoft.com/appx/2018/sccd"
  xmlns="http://schemas.microsoft.com/appx/2018/sccd">

  <xs:element name="CustomCapabilityDescriptor" type="CT_CustomCapabilityDescriptor">
    <xs:unique name="Unique_CustomCapability_Name">
      <xs:selector xpath="s:CustomCapabilities/s:CustomCapability"/>
      <xs:field xpath="@Name"/>
    </xs:unique>
  </xs:element>

  <xs:complexType name="CT_CustomCapabilityDescriptor">
    <xs:sequence>
      <xs:element ref="CustomCapabilities" minOccurs="1" maxOccurs="1"/>
      <xs:element ref="AuthorizedEntities" minOccurs="1" maxOccurs="1"/>
      <xs:element ref="DeveloperModeOnly" minOccurs="0" maxOccurs="1"/>
      <xs:element ref="Catalog" minOccurs="1" maxOccurs="1"/>
      <xs:any minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  
  <xs:element name="CustomCapabilities" type="CT_CustomCapabilities" />

  <xs:complexType name="CT_CustomCapabilities">
    <xs:sequence>
      <xs:element ref="CustomCapability" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="CustomCapability">
    <xs:complexType>
      <xs:attribute name="Name" type="ST_CustomCapability" use="required"/>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name="ST_NonEmptyString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="32767"/>
      <xs:pattern value="[^\s]|([^\s].*[^\s])"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="ST_CustomCapability">
    <xs:annotation>
      <xs:documentation>Custom capabilities should be a string in the form of Company.capabilityName_PublisherId</xs:documentation>
    </xs:annotation>
    <xs:restriction base="ST_NonEmptyString">
      <xs:pattern value="[A-Za-z0-9][-_.A-Za-z0-9]*_[a-hjkmnp-z0-9]{13}"/>
      <xs:minLength value="15"/>
      <xs:maxLength value="255"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="AuthorizedEntities" type="CT_AuthorizedEntities" />

  <xs:complexType name="CT_AuthorizedEntities">
    <xs:sequence>
      <xs:element ref="AuthorizedEntity" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="AllowAny" type="xs:boolean" use="optional"/>
  </xs:complexType>
  
  <xs:element name="AuthorizedEntity" type="CT_AuthorizedEntity" />
  
  <xs:complexType name="CT_AuthorizedEntity">
    <xs:attribute name="CertificateSignatureHash" type="ST_CertificateSignatureHash" use="required"/>
    <xs:attribute name="AppPackageFamilyName" type="ST_NonEmptyString" use="required"/>
  </xs:complexType>

  <xs:simpleType name="ST_CertificateSignatureHash">
    <xs:restriction base="ST_NonEmptyString">
      <xs:pattern value="[A-Fa-f0-9]+"/>
      <xs:minLength value="64"/>
      <xs:maxLength value="64"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="DeveloperModeOnly">
    <xs:complexType>
      <xs:attribute name="Value" type="xs:boolean" use="required"/>
    </xs:complexType>
  </xs:element>

  <xs:element name="Catalog" type="ST_Catalog" />

  <xs:simpleType name="ST_Catalog">
    <xs:restriction base="xs:string">
      <xs:pattern value="[A-Za-z0-9\+\/\=]+"/>
      <xs:minLength value="4"/>
    </xs:restriction>
  </xs:simpleType>
  
</xs:schema>