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

Important

Les métadonnées de l’appareil sont déconseillées et seront supprimées dans une version ultérieure de Windows. Pour plus d’informations sur le remplacement de cette fonctionnalité, consultez Métadonnées du conteneur de package de pilotes.

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 :
- Contact information
- Company name
- 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 sont traités pour le partenaire ?
  - Les événements incluent-ils des identificateurs personnels tels que des emplacements utilisateur précis, des mots de passe, une adresse IP, puID, un ID d’appareil, un CID, un nom d’utilisateur et des données de contact précises ?
  - 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.
If the request is approved, Microsoft emails back a unique custom capability string name in the format CompanyName.capabilityName_PublisherID.

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 :

Call DeriveCapabilitySidsFromName to convert the custom capability name to a security ID (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 processus dans le code du serveur RPC dans 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 implémentez ce code 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. Replace CompanyName with your company name, myCustomCapabilityName with a name that is unique within your company, and MyStorePubId with your publisher store ID.

Pour obtenir un exemple de ce code de pilote implémenté, consultez le kit de ressources d’installation du package de pilotes pour les pilotes universels.

Pour définir la propriété en mode noyau, utilisez ce code :

#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.

Note

L’application ne doit pas ê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.

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.

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

Le SCCD signé obtenu valide dans n’importe quel package d’application.

Multiple SCCDs

À 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. 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>

Le schéma suivant est également valide à partir de Windows 10, version 1809. Il permet à un SCCD de déclarer n’importe quel package d’application comme 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>

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-07-24