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

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 eine Fähigkeit zugreifen?
- Alle Bedenken hinsichtlich Sicherheit und Datenschutz
- Welche Datenereignisse werden an den Partner verarbeitet?
  - Würden die Ereignisse persönliche Kennungen wie zum Beispiel präzise Benutzerstandorte, Kennwörter, IP-Adressen, PUID, Geräte-ID, CID, Benutzernamen und Kontaktdaten präsent haben?
  - Bleiben die Datenereignisse auf dem Gerät des Benutzers 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 wird, sendet Microsoft eine E-Mail zurück mit einem 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 DeriveCapabilitySidsFromName auf, um den benutzerdefinierten Fähigkeitsnamen in eine Sicherheits-ID (SID) zu konvertieren.
Fügen Sie die SID Ihrem Access Allowed ACE zusammen mit allen anderen SIDs hinzu, die für den Sicherheitsdeskriptor Ihres RPC-Endpunkts erforderlich sind.
Erstellen Sie einen RPC-Endpunkt mithilfe der Informationen aus dem Sicherheitsdeskriptor.

Sie können eine Implementierung dieses Prozesses 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 implementieren Sie diesen Code im Treiber:

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 offengelegt 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 diesen implementierten Treibercode finden Sie im Treiberpaketinstallations-Toolkit für universelle Treiber.

Verwenden Sie diesen Code, 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 "Signierter benutzerdefinierter Fähigkeitsdeskriptor" (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.

Note

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 des SCCD sendet der Funktionsbesitzer es zur Unterzeichnung via 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 kann in jedem App-Paket validiert werden.

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. Es ermöglicht 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>

Feedback

War diese Seite hilfreich?

Last updated on 2026-03-25