Hardwaresupport-App (HSA): Schritte für Treiberentwickler

Artikel
10/16/2024

Eine Hardwaresupport-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 zuerst einen speziellen Wert, der als benutzerdefinierte Funktion bezeichnet wird. Erlauben Sie dann den Zugriff auf Apps, die diese Funktion ankündigen und dem App-Entwickler bereitstellen. Auf dieser Seite werden diese Schritte für die Treiberentwickler beschrieben.

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

HSA ist eine der drei "DCH"-Designprinzipien.

Reservieren einer benutzerdefinierten Funktion

Reservieren Sie zunächst eine benutzerdefinierte Funktion:

Senden Sie eine E-Mail an 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 zugegriffen werden?
- Alle Bedenken hinsichtlich Sicherheit und Datenschutz
- Welche Datenereignisse werden an den Partner verarbeitet?
  - Würden die Ereignisse persönliche Kennungen wie etwa genaue Benutzerstandorte, Kennwörter, IP-Adresse, PUID, Geräte-ID, CID, Benutzername und Kontaktdaten enthalten?
  - Bleiben die Datenereignisse auf dem Benutzergerät oder werden an den Partner gesendet?
- Auf welche Daten bietet Ihre Funktion Zugriff?
- Was ist der Vorteil für den Endbenutzer dieser Funktion?
- Fügen Sie die Microsoft Store-App Publisher-ID ein. Um eine zu erhalten, erstellen Sie einen Skelett-App-Eintrag auf der Microsoft Store-Seite. Weitere Informationen zum Reservieren Ihres App-PFN finden Sie unter Erstellen Ihrer App durch Reservieren eines Namens.
Wenn die Anforderung genehmigt wurde, sendet Microsoft eine E-Mail-E-Mail an einen eindeutigen Benutzerdefinierten Funktionszeichenfolgennamen im Format CompanyName.capabilityName_PublisherID.

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

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 zu ermöglichen, die über die benutzerdefinierte Funktion verfügt:

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

Sie können eine Implementierung des oben genannten im RPC-Servercode im Beispiel für benutzerdefinierte Funktionen sehen.

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 zu ermöglichen, fügen Sie der INF-Datei oder der Treiberquelle einige Zeilen hinzu.

Spezifizieren Sie in der INF-Datei die benutzerdefinierte Funktion wie folgt:

[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"

Oder gehen Sie im Treiber wie folgt vor:

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 zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz durch die GUID für die Schnittstelle, die verfügbar gemacht werden soll. Ersetzen Sie "CompanyName" durch Ihren Firmennamen, "myCustomCapabilityName" durch einen Namen, der innerhalb Ihres Unternehmens eindeutig ist, und "MyStorePubId" durch Ihre Herausgeberspeicher-ID.

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

Verwenden Sie Code wie folgt, um die Eigenschaft im Kernelmodus festzulegen:

#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 Datei "Signed Custom Capability Descriptor" (SCCD)

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.

Um die SCCD-Datei vorzubereiten, aktualisieren Sie zuerst die benutzerdefinierte Funktionszeichenfolge. 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 des App-Entwicklers 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 Funktionsbesitzer ihn zur Signierung per E-Mail an Microsoft. Microsoft gibt den signierten SCCD an den Funktionsbesitzer zurück.

Der Funktionsbesitzer sendet dann den SCCD an den App-Entwickler. Der App-Entwickler enthält die signierte SCCD im App-Manifest. Informationen dazu, was der App-Entwickler tun muss, finden Sie unter Hardwaresupport-App (HSA): Schritte für App-Entwickler.

Einschränken des Umfangs einer SCCD

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

Fügen Sie dazu vor dem Von Microsoft signierten SCCD DeveloperModeOnly hinzu:

<?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 sollten Sie jedoch zulassen, dass jede App eine SCCD enthält. Ab Windows 10, Version 1809, können Sie dies tun, indem Sie AllowAny zum AuthorizedEntities-Element hinzufügen. Da die bewährte Methode darin besteht, autorisierte Entitäten in der SCCD-Datei zu deklarieren, geben Sie bitte eine Begründung für die Verwendung von AllowAny an, wenn Sie Ihre SCCD übermitteln, um von Microsoft signiert zu werden.

<?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.

SCCD XML-Schema

Nachfolgend sehen Sie 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 Überprüfung mit IntelliSense finden Sie unter Schemacache- und XML-Dokumentüberprüfung .

<?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 gilt auch für Windows 10, Version 1809. Sie ermöglicht es einem 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>