Aplikasi Dukungan Perangkat Keras (HSA): Langkah-langkah untuk Pengembang Driver

Important

Metadata perangkat tidak digunakan lagi dan akan dihapus dalam rilis Windows mendatang. Untuk informasi tentang penggantian fungsionalitas ini, lihat Metadata Kontainer Paket Driver.

Aplikasi Dukungan Perangkat Keras (HSA) adalah aplikasi khusus perangkat yang dipasangkan dengan titik akhir driver atau RPC (Panggilan Prosedur Jarak Jauh) tertentu.

Untuk mengaitkan aplikasi Store dengan driver, pertama-tama pesan nilai khusus yang disebut kemampuan kustom. Kemudian izinkan akses ke aplikasi yang mengiklankan kemampuan dan memberikan kemampuan kepada pengembang aplikasi. Halaman ini menjelaskan langkah-langkah ini untuk pengembang driver.

Langkah-langkah untuk pengembang aplikasi dijelaskan dalam Aplikasi Dukungan Perangkat Keras (HSA): Langkah-langkah untuk Pengembang Aplikasi.

HSA adalah salah satu dari tiga prinsip desain "DCH".

Mempertahankan kemampuan kustom

Pertama, pesan kemampuan kustom:

Email Tinjauan Aplikasi Dukungan Perangkat Keras Microsoft (HSAReview@microsoft.com) dengan informasi berikut:
- Contact information
- Company name
- Nama kemampuan (harus unik dan mereferensikan pemilik)
- Sumber daya apa yang perlu diakses oleh kemampuan?
- Masalah keamanan atau privasi apa pun
- Peristiwa data apa yang diproses ke mitra?
  - Apakah peristiwa tersebut mencakup pengidentifikasi pribadi seperti lokasi pengguna, kata sandi, alamat IP, PUID, ID perangkat, CID, nama pengguna, dan data kontak yang tepat?
  - Apakah peristiwa data tetap berada di perangkat pengguna, atau dikirim ke mitra?
- Data apa yang dapat diakses oleh kemampuan Anda?
- Apa manfaatnya bagi pengguna akhir dari kemampuan ini?
- Sertakan ID Penerbit Aplikasi Microsoft Store. Untuk mendapatkannya, buat entri aplikasi kerangka di halaman Microsoft Store. Untuk informasi selengkapnya tentang cara menservasi PFN Aplikasi Anda, lihat Membuat aplikasi Anda dengan membuat nama.
If the request is approved, Microsoft emails back a unique custom capability string name in the format CompanyName.capabilityName_PublisherID.

Sekarang Anda dapat menggunakan kemampuan kustom untuk memungkinkan akses ke titik akhir RPC atau driver.

Mengizinkan akses ke titik akhir RPC ke aplikasi UWP menggunakan kemampuan kustom

Untuk mengizinkan akses ke titik akhir RPC ke aplikasi UWP yang memiliki kemampuan kustom, ikuti langkah-langkah berikut:

Call DeriveCapabilitySidsFromName to convert the custom capability name to a security ID (SID).
Tambahkan SID ke akses Anda yang diizinkan ACE bersama dengan SID lain yang diperlukan untuk pendeskripsi keamanan titik akhir RPC Anda.
Buat titik akhir RPC menggunakan informasi dari Deskriptor Keamanan.

Anda dapat melihat implementasi proses ini dalam kode server RPC dalam sampel Kemampuan Kustom.

Mengizinkan akses ke driver ke aplikasi UWP menggunakan kemampuan kustom

Untuk mengizinkan akses ke driver ke aplikasi UWP dengan kemampuan kustom, tambahkan beberapa baris ke file INF atau sumber driver.

Dalam file INF, tentukan kemampuan kustom Anda sebagai berikut:

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

Atau terapkan kode ini di driver:

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

Ganti zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz dengan GUID agar antarmuka dapat diekspos. Replace CompanyName with your company name, myCustomCapabilityName with a name that is unique within your company, and MyStorePubId with your publisher store ID.

Untuk contoh kode driver yang telah diterapkan ini, lihat alat bantu penginstalan paket driver untuk driver universal.

Untuk mengatur properti dalam mode kernel, gunakan kode ini:

#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

Menyiapkan file Deskriptor Kemampuan Kustom (SCCD) yang Ditandatangani

File Deskriptor Kemampuan Kustom (SCCD) yang Ditandatangani adalah file XML yang ditandatangani yang mengotorisasi penggunaan satu atau beberapa kemampuan kustom. Pemilik driver atau titik akhir RPC memberikan kemampuan kustom kepada pengembang aplikasi dengan menyediakan file ini.

Untuk menyiapkan file SCCD, pertama-tama perbarui string kemampuan kustom. Gunakan contoh berikut sebagai titik awal:

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

Selanjutnya, pemilik kemampuan kustom mendapatkan Nama Keluarga Paket (PFN) dan hash tanda tangan dari pengembang aplikasi dan memperbarui string tersebut dalam file SCCD.

Note

Aplikasi tidak harus ditandatangani langsung dengan sertifikat, tetapi sertifikat yang ditentukan harus menjadi bagian dari rantai sertifikasi yang menandatangani aplikasi.

Setelah menyelesaikan SCCD, pemilik kemampuan mengirimkannya melalui email ke Microsoft untuk ditandatangani. Microsoft mengembalikan SCCD yang ditandatangani kepada pemilik kemampuan.

Pemilik kemampuan kemudian mengirim SCCD ke pengembang aplikasi. Pengembang aplikasi menyertakan SCCD yang ditandatangani dalam manifes aplikasi. Untuk mempelajari apa yang perlu dilakukan pengembang aplikasi, lihat Aplikasi Dukungan Perangkat Keras (HSA): Langkah-langkah untuk Pengembang Aplikasi.

Membatasi cakupan SCCD

Untuk tujuan pengujian, pemilik kemampuan kustom dapat membatasi penginstalan aplikasi dukungan perangkat keras ke komputer dalam mode pengembang.

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.

Mengizinkan aplikasi apa pun menggunakan kemampuan kustom

Sebaiknya tentukan entitas resmi (aplikasi) yang dapat menggunakan kemampuan kustom. Namun, dalam beberapa kasus, Anda mungkin ingin mengizinkan aplikasi apa pun untuk menyertakan 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>

SCCD yang telah ditandatangani yang dihasilkan dapat divalidasi dalam paket aplikasi mana pun.

Multiple SCCDs

Mulai windows 10 versi 1803, aplikasi dapat mendeklarasikan kemampuan kustom dari satu atau beberapa file SCCD. Tempatkan file SCCD di akar paket aplikasi.

Skema XML SCCD

Berikut ini adalah skema XML XSD formal untuk file SCCD. Gunakan skema ini untuk memvalidasi SCCD Anda sebelum mengirimkannya untuk ditinjau. 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>

Skema berikut juga valid pada Windows 10, versi 1809. Ini memungkinkan SCCD untuk mendeklarasikan paket aplikasi apa pun menjadi entitas resmi.

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-07-24