Aplicativo de suporte de hardware (HSA): etapas para desenvolvedores de drivers

Artigo
09/23/2024

Um HSA (Aplicativo de Suporte de Hardware) é um aplicativo específico do dispositivo emparelhado com um driver específico ou ponto de extremidade RPC (Chamada de Procedimento Remoto).

Para associar um aplicativo da Store a um driver, primeiro reserve um valor especial chamado de funcionalidade personalizada. Em seguida, permita o acesso a aplicativos que anunciam a funcionalidade e forneça a funcionalidade ao desenvolvedor do aplicativo. Esta página descreve essas etapas para o desenvolvedor do driver.

As etapas para o desenvolvedor do aplicativo são descritas em Etapas do aplicativo de suporte a hardware (HSA) para desenvolvedores de drivers.

HSA é um dos três princípios de design "DCH" .

Reservar uma funcionalidade personalizada

Primeiro, reserve uma funcionalidade personalizada:

Envie um email para o Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) com as seguintes informações:
- Informações de contato
- Nome da empresa
- Nome da funcionalidade (deve ser exclusivo e fazer referência ao proprietário)
- Quais recursos a funcionalidade precisa acessar?
- Qualquer preocupação de segurança ou de privacidade
- Quais eventos de dados serão processados para o parceiro?
  - Os eventos incluiriam identificadores pessoais, como localizações precisas do usuário, senhas, endereço IP, PUID, ID do dispositivo, CID, nome de usuário e dados de contato)?
  - Os eventos de dados permanecem no dispositivo do usuário ou são enviados para o parceiro?
- A quais dados sua funcionalidade fornece acesso?
- Qual é o benefício para o usuário final dessa funcionalidade?
- Inclua a ID do Editor de Aplicativos da Microsoft Store. Para obter um, crie uma entrada de aplicativo esqueleto na página da Microsoft Store. Para obter mais informações sobre como reservar seu PFN de aplicativo, consulte Criar seu aplicativo reservando um nome.
Se a solicitação for aprovada, a Microsoft enviará um email de volta com um nome de cadeia de caracteres de funcionalidade personalizada exclusivo no formato CompanyName.capabilityName_PublisherID.

Agora você pode usar a funcionalidade personalizada para permitir o acesso a um ponto de extremidade RPC ou a um driver.

Permitir acesso a um ponto de extremidade RPC para um aplicativo UWP usando a funcionalidade personalizada

Para permitir o acesso a um ponto de extremidade RPC a um aplicativo UWP que tenha a funcionalidade personalizada, siga estas etapas:

Chame DeriveCapabilitySidsFromName para converter o nome da funcionalidade personalizada em uma SID (ID de segurança).
Adicione o SID à sua ACE de acesso permitido junto com quaisquer outros SIDs necessários para o descritor de segurança do ponto de extremidade RPC.
Crie um ponto de extremidade RPC usando as informações do Descritor de Segurança.

Você pode ver uma implementação do que foi dito acima no código do servidor RPC na Amostra de funcionalidade personalizada.

Permitir o acesso a um driver para um aplicativo UWP usando a funcionalidade personalizada

Para permitir o acesso de um driver a um aplicativo UWP com a funcionalidade personalizada, adicione algumas linhas ao arquivo INF ou à origem do driver.

No arquivo INF, especifique sua funcionalidade personalizada da seguinte maneira:

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

Ou faça o seguinte no 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));

Substitua zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz pelo GUID para a interface a ser exposta. Substitua CompanyName pelo nome da sua empresa, myCustomCapabilityName por um nome exclusivo na empresa e MyStorePubId pela ID da loja do editor.

Para obter um exemplo do código de driver mostrado imediatamente acima, consulte o Kit de ferramentas de instalação de pacotes de drivers para drivers universais.

Para definir a propriedade no modo kernel, use um código como o seguinte:

#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

Preparar o arquivo SCCD (Signed Custom Capability Descriptor)

Um arquivo SCCD (Signed Custom Capability Descriptor) é um arquivo XML assinado que autoriza o uso de uma ou mais funcionalidades personalizadas. O proprietário do driver ou do ponto de extremidade RPC concede a funcionalidade personalizada ao desenvolvedor do aplicativo fornecendo esse arquivo.

Para preparar o arquivo SCCD, primeiro atualize a cadeia de caracteres de funcionalidade personalizada. Use o exemplo seguinte como ponto de partida:

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

Em seguida, o proprietário da funcionalidade personalizada obtém o nome da família de pacotes (PFN) e o hash de assinatura do desenvolvedor do aplicativo e atualiza essas cadeias de caracteres no arquivo SCCD.

Observação

O aplicativo não precisa ser assinado diretamente com o certificado, mas o certificado especificado deve fazer parte da cadeia de certificados que assina o aplicativo.

Depois de concluir o SCCD, o proprietário da funcionalidade a envia por email para a Microsoft para assinatura. A Microsoft retorna o SCCD assinado para o proprietário da funcionalidade.

Em seguida, o proprietário da funcionalidade envia o SCCD para o desenvolvedor do aplicativo. O desenvolvedor do aplicativo inclui o SCCD assinado no manifesto do aplicativo. Para saber o que o desenvolvedor de aplicativos precisa fazer, consulte Aplicativo de suporte a hardware (HSA): etapas para desenvolvedores de aplicativos.

Limitar o escopo de um SCCD

Para fins de teste, um proprietário de funcionalidade personalizada pode restringir a instalação de um aplicativo de suporte de hardware a computadores no modo de desenvolvedor.

Para fazer isso, antes de obter o SCCD assinado pela Microsoft, adicione 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>

O SCCD assinado resultante funciona apenas em dispositivos no Modo de desenvolvedor.

Permitir que qualquer aplicativo use uma funcionalidade personalizada

Recomendamos especificar entidades autorizadas (apps) que podem usar uma funcionalidade personalizada. Em alguns casos, no entanto, talvez você queira permitir que qualquer aplicativo inclua um SCCD. A partir do Windows 10 versão 1809, você pode fazer isso adicionando AllowAny ao elemento AuthorizedEntities. Como a prática recomendada é declarar entidades autorizadas no arquivo SCCD, forneça uma justificativa para usar AllowAny ao enviar seu SCCD para ser assinado pela 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>

O SCCD assinado resultante será validado em qualquer pacote de aplicativo.

Vários SCCDs

A partir do Windows 10 versão 1803, os aplicativos podem declarar funcionalidades personalizadas de um ou mais arquivos SCCD. Coloque os arquivos SCCD na raiz do pacote do aplicativo.

Esquema XML do SCCD

Veja a seguir o esquema XML XSD formal para um arquivo SCCD. Use esse esquema para validar seu SCCD antes de enviá-lo para revisão. Consulte Cache de esquema e validação de documento XML para obter informações sobre como importar um esquema e validar com o 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>

O esquema a seguir também é válido a partir de Windows 10, versão 1809. Ele permite que um SCCD declare qualquer pacote de aplicativo como uma entidade autorizada.

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