Приложение поддержки оборудования (HSA): действия для разработчиков драйверов

  • Статья

Приложение поддержки оборудования (HSA) — это приложение для конкретного устройства, которое связано с определенным драйвером или конечной точкой RPC (удаленный вызов процедур ).

Чтобы связать приложение Магазина с драйвером, сначала зарезервируйте специальное значение, называемое пользовательской возможностью. Затем разрешите доступ к приложениям, которые объявляют возможность и предоставляют ее разработчику. На этой странице описаны эти шаги для разработчика драйверов.

Действия для разработчика приложения описаны в разделе Приложение поддержки оборудования (HSA): шаги для разработчиков приложений.

HSA — это один из трех принципов проектирования (DCH) драйверов Windows.

Резервирование пользовательской возможности

Сначала зарезервируйте пользовательскую возможность:

  1. Email Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) со следующими сведениями:

    • Контактные данные

    • Название организации

    • Имя возможности (должно быть уникальным и ссылаться на владельца)

    • К каким ресурсам требуется доступ для возможностей?

    • Любые проблемы безопасности или конфиденциальности

    • Какие события данных будут обрабатываться партнеру?

      • Будут ли события включать личные идентификаторы, такие как точные расположения пользователей, пароли, IP-адрес, PUID, идентификатор устройства, идентификатор CID, имя пользователя и контактные данные)?

      • Остаются ли события данных на устройстве пользователей или отправляются партнеру?

    • К каким данным предоставляет доступ ваша возможность?

    • В чем преимущество этой возможности для конечного пользователя?

    • Включите идентификатор издателя приложения Microsoft Store. Чтобы получить ее, создайте запись приложения на странице Microsoft Store. Дополнительные сведения о резервирования PFN приложения см. в статье Создание приложения путем резервирования имени.

  2. Если запрос утвержден, корпорация Майкрософт отправляет по электронной почте уникальное имя строки пользовательской возможности в формате CompanyName.capabilityName_PublisherID.

Теперь можно использовать пользовательскую возможность, чтобы разрешить доступ к конечной точке RPC или драйверу.

Предоставление доступа к конечной точке RPC к приложению UWP с помощью пользовательской возможности

Чтобы разрешить доступ к конечной точке RPC к приложению UWP с настраиваемой возможностью, выполните следующие действия.

  1. Вызовите Метод DeriveCapabilitySidsFromName , чтобы преобразовать имя настраиваемой возможности в идентификатор безопасности (SID).

  2. Добавьте идентификатор безопасности в разрешенный доступ ACE вместе с любыми другими идентификаторами безопасности, необходимыми для дескриптора безопасности конечной точки RPC.

  3. Создайте конечную точку RPC, используя сведения из дескриптора безопасности.

Реализацию выше можно увидеть в коде сервера RPC в примере настраиваемой возможности.

Предоставление доступа к драйверу к приложению UWP с помощью пользовательской возможности

Чтобы разрешить доступ к драйверу к приложению UWP с пользовательской возможностью, добавьте несколько строк в INF-файл или источник драйвера.

В INF-файле укажите пользовательскую возможность следующим образом:

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

Или выполните следующие действия в драйвере:

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

Замените zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz идентификатором GUID для интерфейса, который будет предоставляться. Замените CompanyName именем своей компании, myCustomCapabilityName — уникальным в пределах вашей компании именем, а MyStorePubId — идентификатором вашего магазина издателя.

Пример кода драйвера, показанного непосредственно выше, см. в разделе Набор средств установки пакета драйверов для универсальных драйверов.

Чтобы задать свойство в режиме ядра, используйте следующий код:

#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

Подготовка файла подписанного пользовательского дескриптора возможностей (SCCD)

Подписанный файл пользовательского дескриптора возможностей (SCCD) — это подписанный XML-файл, разрешающий использование одной или нескольких пользовательских возможностей. Владелец драйвера или конечной точки RPC предоставляет разработчику приложения пользовательскую возможность, предоставив этот файл.

Чтобы подготовить SCCD-файл, сначала обновите строку настраиваемой возможности. Используйте следующий пример в качестве отправной точки:

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

Затем владелец настраиваемой возможности получает имя семейства пакетов (PFN) и хэш подписи от разработчика приложения и обновляет эти строки в файле SCCD.

Примечание

Приложение не обязательно подписывается непосредственно сертификатом, но указанный сертификат должен быть частью цепочки сертификатов, подписывающую приложение.

После завершения SCCD владелец возможности отправляет его по электронной почте в корпорацию Майкрософт для подписания. Корпорация Майкрософт возвращает подписанный SCCD владельцу возможности.

Затем владелец возможности отправляет SCCD разработчику приложения. Разработчик приложения включает подписанный SCCD в манифест приложения. Сведения о том, что нужно сделать разработчику приложений, см. в статье Приложение поддержки оборудования (HSA): действия для разработчиков приложений.

Ограничение область SCCD

В целях тестирования владелец пользовательской возможности может ограничить установку приложения поддержки оборудования компьютерами в режиме разработчика.

Для этого перед получением SCCD, подписанного корпорацией Майкрософт, добавьте 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>

Полученный подписанный SCCD работает только на устройствах в режиме разработчика.

Разрешение любому приложению использовать пользовательскую возможность

Рекомендуется указать авторизованные сущности (приложения), которые могут использовать пользовательскую возможность. Однако в некоторых случаях может потребоваться разрешить любому приложению включить SCCD. Начиная с Windows 10 версии 1809, это можно сделать, добавив AllowAny в элемент AuthorizedEntities. Так как рекомендуется объявлять авторизованные сущности в файле SCCD, укажите обоснование использования AllowAny при отправке SCCD, подписанного корпорацией Майкрософт.

<?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 будет проверяться в любом пакете приложения.

Несколько SCCD

Начиная с Windows 10 версии 1803, приложения могут объявлять пользовательские возможности из одного или нескольких SCCD-файлов. Поместите SCCD-файлы в корень пакета приложения.

Сводка по последовательности подписывания SCCD

На следующей схеме представлена последовательность, описанная выше.

Получение подписи SCCD.

Схема XML SCCD

Ниже приведена формальная XSD-схема XML для SCCD-файла. Используйте эту схему для проверки SCCD перед отправкой на проверку. Сведения об импорте схемы и проверке с помощью IntelliSense см. в разделе Проверка кэша схем и 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>

Следующая схема также допустима с Windows 10, версия 1809. Это позволяет SCCD объявлять любой пакет приложения как авторизованный объект.

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

См. также раздел

начало работы с драйверами Windows

Общие сведения об универсальной платформе Windows

Универсальная платформа Windows (UWP)

Возможности приложения

Разработка приложений UWP с помощью Visual Studio

Связывание драйвера с приложением универсальная платформа Windows (UWP)

Разработка приложений UWP

Упаковка приложения с помощью Desktop App Converter (моста для классических приложений)

Пример приложения пользовательской возможности

Пример драйвера настраиваемых возможностей

Загрузка неопубликованных приложений в Windows 10

Часто задаваемые вопросы о пользовательских возможностях