Aplikace hardwarové podpory (HSA): Postup pro vývojáře ovladačů

Aplikace hardwarové podpory (HSA) je aplikace specifická pro zařízení, která je spárovaná s konkrétním ovladačem nebo koncovým bodem RPC (Vzdálené volání procedur).

Pokud chcete přidružit aplikaci pro Store k ovladači, nejprve si vyhraďte speciální hodnotu označovanou jako vlastní schopnost. Pak povolte přístup k aplikacím, které inzerují tuto funkci, a poskytují možnosti vývojáři aplikací. Tato stránka popisuje tyto kroky pro vývojáře ovladačů.

Kroky pro vývojáře aplikací jsou popsané v aplikaci hardwarové podpory (HSA): Kroky pro vývojáře aplikací.

HSA je jedním ze tří principů návrhu DCH.

Rezervace vlastní funkce

Nejprve si zarezervujte vlastní funkce:

  1. Odešlete e-mail společnosti Microsoft Pro kontrolu hardwarových aplikací (HSAReview@microsoft.com) s následujícími informacemi:

    • Kontaktní informace

    • Název společnosti

    • Název funkce (musí být jedinečný a odkazovat na vlastníka)

    • K jakým prostředkům je potřeba získat přístup?

    • Jakékoli obavy týkající se zabezpečení nebo ochrany osobních údajů

    • Jaké datové události se zpracovávají pro partnera?

      • Zahrnují události osobní identifikátory, jako jsou přesná umístění uživatelů, hesla, IP adresa, PUID, ID zařízení, IDENTIFIKÁTOR CID, uživatelské jméno a kontaktní údaje?

      • Zůstávají datové události na zařízení uživatele nebo se odesílají partnerovi?

    • K jakým datům vaše funkce poskytuje přístup?

    • Jaká je výhoda pro koncového uživatele této funkce?

    • Uveďte ID vydavatele aplikace z Microsoft Storu. Pokud ho chcete získat, vytvořte položku kostry aplikace na stránce Microsoft Storu. Další informace o rezervaci aplikace PFN najdete v tématu Vytvoření aplikace tak, že si rezervujete název.

  2. Pokud je žádost schválena, Microsoft pošle e-mailem jedinečný název vlastního řetězce schopností ve formátu CompanyName.capabilityName_PublisherID.

Teď můžete pomocí vlastní funkce povolit přístup ke koncovému bodu RPC nebo ovladači.

Povolení přístupu ke koncovému bodu RPC k aplikaci pro UPW pomocí vlastní funkce

Pokud chcete povolit přístup ke koncovému bodu RPC aplikaci pro UPW, která má vlastní funkci, postupujte takto:

  1. Zavolejte DeriveCapabilitySidsFromName pro převod názvu vlastní schopnosti na ID zabezpečení (SID).

  2. Přidejte SID ke komponentě ACE s povoleným přístupem spolu s dalšími SID, které jsou potřebné pro bezpečnostní deskriptor vašeho koncového bodu RPC.

  3. Vytvořte koncový bod RPC pomocí informací z popisovače zabezpečení.

Implementaci tohoto procesu můžete zobrazit v kódu serveru RPC v ukázce Vlastních schopností.

Povolení přístupu k ovladači k aplikaci pro UWP pomocí vlastního oprávnění

Pokud chcete povolit přístup k ovladači k aplikaci pro UPW s vlastní funkcí, přidejte do souboru INF nebo zdroje ovladače několik řádků.

V souboru INF zadejte vlastní funkce následujícím způsobem:

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

Nebo implementujte tento kód v ovladači:

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));

Nahraďte zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz identifikátorEM GUID rozhraní, které se má zveřejnit. Název společnosti nahraďte názvem vaší společnosti, myCustomCapabilityName názvem, který je jedinečný v rámci vaší společnosti, a MyStorePubId id vašeho úložiště vydavatele.

Příklad tohoto implementovaného kódu ovladače najdete v instalační sadě nástrojů balíčku ovladačů pro univerzální ovladače.

K nastavení vlastnosti v režimu jádra použijte tento kód:

#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

Příprava souboru SCCD (Signed Custom Capability Descriptor)

Podepsaný soubor SCCD (Signed Custom Capability Descriptor) je podepsaný soubor XML, který autorizuje použití jedné nebo více vlastních funkcí. Vlastník ovladače nebo koncového bodu RPC přidělí vývojáři aplikace vlastní oprávnění prostřednictvím poskytnutí tohoto souboru.

Pokud chcete připravit soubor SCCD, nejprve aktualizujte vlastní řetězec schopností. Jako výchozí bod použijte následující příklad:

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

V dalším kroku získá vlastník vlastní funkce název rodiny balíčků (PFN) a hodnotu hash podpisu od vývojáře aplikace a aktualizuje tyto řetězce v souboru SCCD.

Note

Aplikace nemusí být podepsána přímo pomocí certifikátu, ale zadaný certifikát musí být součástí řetězu certifikátů, který aplikaci podepíše.

Po dokončení SCCD ji vlastník funkce pošle Microsoftu k podepisování. Microsoft vrátí podepsané SCCD vlastníkovi funkce.

Vlastník funkce pak pošle SCCD vývojáři aplikace. Vývojář aplikace zahrnuje podepsaný SCCD do manifestu aplikace. Informace o tom, co vývojář aplikace potřebuje udělat, najdete v tématu Aplikace pro podporu hardwaru (HSA): Postup pro vývojáře aplikací.

Omezení rozsahu SCCD

Pro účely testování může vlastník vlastní funkce omezit instalaci aplikace hardwarové podpory na počítače v režimu vývojáře.

Provedete to tak, že před získáním podpisu SCCD od Microsoftu přidáte DeveloperModeOnly:

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

Výsledný podepsaný SCCD funguje jenom na zařízeních v režimu vývojáře.

Povolení použití vlastní funkce pro libovolnou aplikaci

Doporučujeme zadat autorizované entity (aplikace), které můžou používat vlastní funkce. V některých případech ale můžete chtít povolit, aby každá aplikace obsahovala SCCD. Počínaje Windows 10 verze 1809 to můžete udělat přidáním AllowAny do elementu AuthorizedEntities. Vzhledem k tomu, že osvědčeným postupem je deklarovat autorizované entity v souboru SCCD, uveďte prosím odůvodnění použití allowAny při odeslání podpisu SCCD microsoftem.

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

Výsledný podepsaný SCCD se ověří v jakémkoli balíčku aplikace.

Více SCCD

Počínaje Windows 10 verze 1803 můžou aplikace deklarovat vlastní možnosti z jednoho nebo více souborů SCCD. Umístěte soubory SCCD do kořenového adresáře balíčku aplikace.

Schéma XML SCCD

Následuje formální schéma XSD XML pro soubor SCCD. Toto schéma použijte k ověření SCCD před odesláním ke kontrole. Informace o importu schématu a ověřování pomocí IntelliSense najdete v tématu Mezipaměť schématu a ověření dokumentu XML .

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

Následující schéma je také platné od Windows 10 verze 1809. Umožňuje SCCD deklarovat jakýkoli balíček aplikace jako autorizovanou entitu.

<?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>
  • Last updated on