HSA (aplicativo de suporte de hardware): etapas para desenvolvedores de driver
Um HSA (Aplicativo de Suporte de Hardware) é um aplicativo específico do dispositivo que é emparelhado com um driver específico ou um 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 fornecem a capacidade para o 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 HSA (Aplicativo de Suporte de Hardware): etapas para desenvolvedores de aplicativos.
O HSA é um dos três princípios de design ("DCH") dos Drivers do Windows.
Reservando uma funcionalidade personalizada
Primeiro, reserve uma funcionalidade personalizada:
Email Revisão de Aplicativos de Suporte de Hardware da Microsoft (HSAReview@microsoft.com) com as seguintes informações:
Informações de contato
Nome da empresa
Nome da funcionalidade (deve ser exclusivo e referenciar o proprietário)
Quais recursos a funcionalidade precisa acessar?
Quaisquer preocupações de segurança ou privacidade
Quais eventos de dados serão processados para o parceiro?
Os eventos incluiriam identificadores pessoais, como locais precisos 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 de usuários ou são enviados ao 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 uma, 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 envia um email para um nome de cadeia de caracteres de funcionalidade personalizado 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 o 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 ao ACE permitido de acesso, juntamente com 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 acima no código do servidor RPC no exemplo de Funcionalidade Personalizada.
Permitir o acesso a um driver a um aplicativo UWP usando a funcionalidade personalizada
Para permitir o acesso a 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 em sua 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 pacote de driver 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
Preparando o arquivo SCCD (Descritor de Funcionalidade Personalizada Assinada)
Um arquivo SCCD (Descritor de Funcionalidade Personalizada Assinada) é um arquivo XML assinado que autoriza o uso de um ou mais recursos personalizados. 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 seguinte exemplo 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 PFN (Nome da Família de Pacotes) 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 envia um 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 do aplicativo precisa fazer, consulte HSA (Aplicativo de Suporte de Hardware): Etapas para desenvolvedores de aplicativos.
Limitando 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 para 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
É recomendável especificar entidades autorizadas (aplicativos) que podem usar uma funcionalidade personalizada. Em alguns casos, no entanto, talvez você queira permitir que qualquer aplicativo inclua um SCCD. A partir Windows 10 versão 1809, você pode fazer isso adicionando AllowAny ao elemento AuthorizedEntities. Como a melhor prática é 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 recursos personalizados de um ou mais arquivos SCCD. Coloque os arquivos SCCD na raiz do pacote do aplicativo.
Resumo da sequência de assinatura do SCCD
O diagrama a seguir resume a sequência descrita acima:
Esquema XML SCCD
Veja a seguir o esquema XSD XML formal para um arquivo SCCD. Use esse esquema para validar o SCCD antes de enviá-lo para revisão. Confira Validação de Cache de Esquema e 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>
Confira também
Introdução com drivers do Windows
Introdução à Plataforma Universal do Windows
UWP (Plataforma Universal do Windows)
Desenvolver aplicativos UWP usando o Visual Studio
Emparelhamento de um driver com um aplicativo UWP (Plataforma Universal do Windows)
Empacotar um aplicativo usando o Desktop App Converter (Ponte de Desktop)
Aplicativo de exemplo de funcionalidade personalizada
Exemplo de driver de funcionalidade personalizado
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de