Application de Support Matériel (HSA) : Étapes pour les Développeurs de Pilotes

Article
10/16/2024

Une application de support matériel (HSA) est une application spécifique à un appareil qui est associée à un pilote spécifique ou à un point de terminaison RPC (Remote Procedure Call).

Pour associer une application Store à un pilote, commencez par réserver une valeur spéciale appelée fonctionnalité personnalisée. Ensuite, autorisez l’accès aux applications qui annoncent cette fonctionnalité et fournissez la fonctionnalité au développeur de l’application. Cette page décrit ces étapes pour le développeur de pilote.

Les étapes pour le développeur d’application sont décrites dans Application de support matériel (HSA) : étapes pour les développeurs d’applications.

HSA est l’un des trois principes de conception « DCH ».

Réservation d’une fonctionnalité personnalisée

Tout d’abord, réservez une fonctionnalité personnalisée :

Envoyez un e-mail à Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) avec les informations suivantes :
- Informations de contact
- Nom de la société
- Nom de la fonctionnalité (doit être unique et faire référence au propriétaire)
- Quelles ressources cette fonctionnalité doit-elle accéder ?
- Y a-t-il des préoccupations en matière de sécurité ou de confidentialité ?
- Quels événements de données seront traités pour le partenaire ?
  - Les événements incluront-ils des identifiants personnels tels que des emplacements précis des utilisateurs, des mots de passe, des adresses IP, des PUID, des ID d’appareil, CID, nom d’utilisateur et données de contact ?
  - Les événements de données restent-ils sur l’appareil de l’utilisateur ou sont-ils envoyés au partenaire ?
- À quelles données votre fonctionnalité donne-t-elle accès ?
- Quel est le bénéfice pour l’utilisateur final de cette fonctionnalité ?
- Incluez l’ID de l’éditeur de l’application Microsoft Store. Pour en obtenir un, créez une entrée d’application de squelette sur la page Microsoft Store. Pour plus d’informations sur la réservation de votre PFN d’application, veuillez consulter la section Créer votre application en réservant un nom.
Si la demande est approuvée, Microsoft renverra un nom de chaîne de fonctionnalité personnalisée unique au format NomEntreprise.nomFonctionnalité_IDÉditeur.

Vous pouvez maintenant utiliser la fonctionnalité personnalisée pour autoriser l’accès soit à un point de terminaison RPC, soit à un pilote.

Autorisation d’accès à un point de terminaison RPC à une application UWP à l’aide de la fonctionnalité personnalisée

Pour autoriser l’accès à un point de terminaison RPC à une application UWP disposant de la fonctionnalité personnalisée, suivez ces étapes :

Appelez DeriveCapabilitySidsFromName pour convertir le nom de la fonctionnalité personnalisée en un identifiant de sécurité (SID).
Ajoutez le SID à votre ACE autorisé, ainsi que tout autre SID nécessaire pour le descripteur de sécurité de votre point de terminaison RPC.
Créez un point de terminaison RPC en utilisant les informations du descripteur de sécurité.

Vous pouvez voir une implémentation de ce qui précède dans le code serveur RPC de l’exemple de fonctionnalité personnalisée.

Autorisation d’accès à un pilote pour une application UWP à l’aide de la fonctionnalité personnalisée

Pour autoriser l’accès à un pilote pour une application UWP avec la fonctionnalité personnalisée, ajoutez quelques lignes soit au fichier INF, soit au code source du pilote.

Dans le fichier INF, spécifiez votre fonctionnalité personnalisée comme suit :

[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, faites ce qui suit dans le pilote :

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

Remplacez zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz par le GUID de l’interface à exposer. Remplacez NomEntreprise par le nom de votre entreprise, monNomFonctionnalitéPersonnalisée par un nom unique dans votre entreprise, et MonIdÉditeurStore par votre ID d’éditeur Store.

Pour un exemple du code de pilote présenté juste au-dessus, veuillez consulter la section Trousse d’installation du package de pilotes pour pilotes universels.

Pour définir la propriété en mode noyau, utilisez un code comme le suivant :

#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

Préparation du fichier SCCD (descripteur de fonctionnalité personnalisée signée)

Un fichier SCCD (descripteur de fonctionnalité personnalisée signée) est un fichier XML signé autorisant l’utilisation d’une ou plusieurs fonctionnalités personnalisées. Le propriétaire du pilote ou du point de terminaison RPC accorde la fonctionnalité personnalisée au développeur d’application en fournissant ce fichier.

Pour préparer le fichier SCCD, commencez par mettre à jour la chaîne de fonctionnalité personnalisée. Utilisez l’exemple suivant comme point de départ :

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

Ensuite, le propriétaire de la fonctionnalité personnalisée obtient le nom de famille de package (PFN) et le hachage de signature du développeur d’application et met à jour ces chaînes dans le fichier SCCD.

Remarque

L’application n’a pas besoin d’être signée directement avec le certificat, mais le certificat spécifié doit faire partie de la chaîne de certificats qui signe l’application.

Une fois le SCCD terminé, le propriétaire de la fonctionnalité l’envoie par e-mail à Microsoft pour signature. Microsoft renvoie le SCCD signé au propriétaire de la fonctionnalité.

Le propriétaire de la fonctionnalité envoie ensuite le SCCD au développeur d’application. Le développeur d’application inclut le SCCD signé dans le manifeste de l’application. Pour savoir ce que le développeur d’application doit faire, veuillez consulter la section Application de support matériel (HSA) : étapes pour les développeurs d’applications.

Limiter l’étendue d’un SCCD

À des fins de test, un propriétaire de fonctionnalité personnalisée peut restreindre l’installation d’une application de support matériel aux ordinateurs en mode développeur.

Pour ce faire, avant d’obtenir la signature du SCCD par Microsoft, ajoutez 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>

Le SCCD signé résultant ne fonctionnera que sur des appareils en mode développeur.

Autoriser toute application à utiliser une fonctionnalité personnalisée

Nous recommandons de spécifier des entités autorisées (applications) pouvant utiliser une fonctionnalité personnalisée. Dans certains cas, cependant, vous pourriez vouloir autoriser n’importe quelle application à inclure un SCCD. À partir de la version 1809 de Windows 10, vous pouvez le faire en ajoutant AllowAny à l’élément AuthorizedEntities. Étant donné que la bonne pratique consiste à déclarer des entités autorisées dans le fichier SCCD, veuillez fournir une justification pour l’utilisation de AllowAny lors de la soumission de votre SCCD pour signature par 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>

Le SCCD signé résultant sera validé dans tout package d’application.

Plusieurs SCCD

À partir de la version 1803 de Windows 10, les applications peuvent déclarer des fonctionnalités personnalisées à partir d’un ou plusieurs fichiers SCCD. Placez les fichiers SCCD à la racine du package d’application.

Schéma XML SCCD

Ce qui suit est le schéma XML XSD formel pour un fichier SCCD. Utilisez ce schéma pour valider votre SCCD avant de le soumettre pour révision. Veuillez consulter la section Cache de schémas et Validation de documents XML pour plus d’informations sur l’importation d’un schéma et la validation avec 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>

Le schéma suivant est également valide à partir de Windows 10, version 1809. Il permet à un SCCD de déclarer tout package d’application comme étant une entité autorisée.

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