Application de support matériel (HSA) : étapes pour les développeurs de pilotes

Article
06/15/2023

Une application de support matériel (HSA) est une application spécifique à un appareil qui est associée à un point de terminaison rpc (appel de procédure distante) spécifique.

Pour associer une application du Store à un pilote, réservez d’abord une valeur spéciale appelée fonctionnalité personnalisée. Autorisez ensuite l’accès aux applications qui publient la fonctionnalité et fournissent la fonctionnalité au développeur de l’application. Cette page décrit ces étapes pour le développeur de pilotes.

Les étapes pour le développeur d’applications 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 ») des pilotes Windows.

Réservation d’une fonctionnalité personnalisée

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

Email révision des applications de support matériel Microsoft (HSAReview@microsoft.com) avec les informations suivantes :
- Informations de contact
- Nom de la société
- Nom de la fonctionnalité (doit être unique et référencer le propriétaire)
- À quelles ressources la fonctionnalité a-t-elle besoin pour accéder ?
- Tout problème de sécurité ou de confidentialité
- Quels événements de données seront traités pour le partenaire ?
  - Les événements incluent-ils des identificateurs personnels tels que l’emplacement précis de l’utilisateur, les mots de passe, l’adresse IP, le PUID, l’ID d’appareil, le CID, le nom d’utilisateur et les données de contact) ?
  - Les événements de données restent-ils sur l’appareil des utilisateurs ou sont-ils envoyés au partenaire ?
- À quelles données votre capacité fournit-elle l’accès ?
- Quel est l’avantage pour l’utilisateur final de cette fonctionnalité ?
- Incluez l’ID d’éditeur d’application du Microsoft Store. Pour en obtenir une, créez une entrée d’application squelette sur la page du Microsoft Store. Pour plus d’informations sur la réservation de votre PFN d’application, consultez Créer votre application en réservant un nom.
Si la demande est approuvée, Microsoft envoie par e-mail un nom de chaîne de capacité personnalisée unique au format CompanyName.capabilityName_PublisherID.

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

Autoriser l’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 qui a la fonctionnalité personnalisée, procédez comme suit :

Appelez DeriveCapabilitySidsFromName pour convertir le nom de la fonctionnalité personnalisée en ID de sécurité (SID).
Ajoutez le SID à votre ACE autorisé avec tout autre SID nécessaire pour le descripteur de sécurité de votre point de terminaison RPC.
Créez un point de terminaison RPC à l’aide des informations du descripteur de sécurité.

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

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

Pour autoriser l’accès à un pilote à une application UWP avec la fonctionnalité personnalisée, ajoutez quelques lignes au fichier INF ou à la 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"

Vous pouvez également effectuer les opérations suivantes 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 par zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz le GUID de l’interface à exposer. Remplacez CompanyName par le nom de votre entreprise, myCustomCapabilityName par un nom unique au sein de votre entreprise et MyStorePubId par votre ID de magasin d’éditeur.

Pour obtenir un exemple de code de pilote indiqué immédiatement ci-dessus, 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 un code semblable à ce qui suit :

#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 (Signed Custom Capability Descriptor)

Un fichier SCCD (Signed Custom Capability Descriptor) 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 de l’application en fournissant ce fichier.

Pour préparer le fichier SCCD, commencez par mettre à jour la chaîne de capacité 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 capacité personnalisée obtient le nom de la famille de packages (PFN) et le hachage de signature auprès du développeur de l’application et met à jour ces chaînes dans le fichier SCCD.

Notes

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 capacité l’envoie par e-mail à Microsoft pour signature. Microsoft retourne le SCCD signé au propriétaire de la fonctionnalité.

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

Limitation de l’étendue d’un SCCD

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

Pour ce faire, avant d’obtenir la signature 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 fonctionne uniquement sur les appareils en mode développeur.

Autoriser n’importe quelle application à utiliser une fonctionnalité personnalisée

Nous vous recommandons de spécifier des entités (applications) autorisées qui peuvent utiliser une fonctionnalité personnalisée. Dans certains cas, toutefois, vous pouvez autoriser n’importe quelle application à inclure un SCCD. À compter de Windows 10 version 1809, vous pouvez le faire en ajoutant AllowAny à l’élément AuthorizedEntities. Étant donné que la meilleure pratique consiste à déclarer des entités autorisées dans le fichier SCCD, veuillez fournir une justification pour l’utilisation de AllowAny lors de l’envoi de votre SCCD pour être signé 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 est validé dans n’importe quel package d’application.

Plusieurs SCCD

À partir de Windows 10 version 1803, 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.

Résumé de la séquence de signature SCCD

Le diagramme suivant résume la séquence décrite ci-dessus :

Obtention d’une signature SCCD.

Schéma XML SCCD

Voici le schéma XSD XML formel pour un fichier SCCD. Utilisez ce schéma pour valider votre SCCD avant de l’envoyer pour révision. Pour plus d’informations sur l’importation d’un schéma et la validation avec IntelliSense, consultez Cache de schéma et Validation de document 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>

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