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

Important

Metadata zařízení jsou zastaralá a budou odebrána v budoucí verzi Windows. Informace o nahrazení této funkce naleznete v tématu Metadata kontejneru balíčku 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:

Odešlete e-mail společnosti Microsoft Pro kontrolu hardwarových aplikací (HSAReview@microsoft.com) s následujícími informacemi:
- Contact information
- Company name
- 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.
If the request is approved, Microsoft emails back a unique custom capability string name in the format 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:

Call DeriveCapabilitySidsFromName to convert the custom capability name to a security ID (SID).
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.
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. Replace CompanyName with your company name, myCustomCapabilityName with a name that is unique within your company, and MyStorePubId with your publisher store ID.

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.

To do so, before getting the SCCD signed by Microsoft, add 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>

The resulting signed SCCD works only on devices in Developer Mode.

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. Starting in Windows 10 version 1809, you can do this by adding AllowAny to the AuthorizedEntities element. Because the best practice is to declare authorized entities in the SCCD file, please provide a justification for using AllowAny when submitting your SCCD to be signed by Microsoft.

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

Multiple SCCDs

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. See Schema Cache and XML Document validation for info on importing a schema and validating with IntelliSense.

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-07-24