App di supporto hardware (HSA): passaggi per sviluppatori di driver

Articolo
06/22/2024

Un'app HSA (Hardware Support App) è un'app specifica del dispositivo associata a un driver specifico o a un endpoint RPC (Remote Procedure Call).

Per associare un'app dello Store a un driver, riservare prima un valore speciale denominato funzionalità personalizzata. Consentire quindi l'accesso alle app che annunciano la funzionalità e forniscono la funzionalità allo sviluppatore di app. Questa pagina descrive questi passaggi per lo sviluppatore di driver.

I passaggi per lo sviluppatore di app sono descritti in Hardware Support App (HSA): Passaggi per sviluppatori di app.

HSA è uno dei tre principi di progettazione "DCH".

Prenotazione di una funzionalità personalizzata

Prima di tutto, riservare una funzionalità personalizzata:

Inviare un messaggio di posta elettronica a Microsoft Hardware Support Apps Review (HSAReview@microsoft.com) con le informazioni seguenti:
- Informazioni sul contatto
- Nome della società
- Nome della funzionalità (deve essere univoco e fare riferimento al proprietario)
- Quali risorse devono poter accedere?
- Eventuali problemi di sicurezza o privacy
- Quali eventi di dati verranno elaborati al partner?
  - Gli eventi includono identificatori personali, ad esempio posizioni utente precise, password, indirizzo IP, PUID, ID dispositivo, CID, nome utente e dati di contatto)?
  - Gli eventi di dati rimangono sul dispositivo degli utenti o vengono inviati al partner?
- Quali dati forniscono l'accesso alle funzionalità?
- Qual è il vantaggio per l'utente finale di questa funzionalità?
- Includere l'ID editore dell'app di Microsoft Store. Per ottenerla, creare una voce di app scheletro nella pagina di Microsoft Store. Per altre info sulla prenotazione del pfn dell'app, vedi Creare l'app riservando un nome.
Se la richiesta viene approvata, Microsoft invia un messaggio di posta elettronica a un nome di stringa di funzionalità personalizzato univoco nel formato CompanyName.capabilityName_PublisherID.

È ora possibile usare la funzionalità personalizzata per consentire l'accesso a un endpoint RPC o a un driver.

Consentire l'accesso a un endpoint RPC a un'app UWP usando la funzionalità personalizzata

Per consentire l'accesso a un endpoint RPC a un'app UWP con la funzionalità personalizzata, seguire questa procedura:

Chiamare DeriveCapabilitySidsFromName per convertire il nome della funzionalità personalizzata in un ID di sicurezza (SID).
Aggiungere il SID all'accesso consentito ACE insieme a qualsiasi altro SID necessario per il descrittore di sicurezza dell'endpoint RPC.
Creare un endpoint RPC usando le informazioni del descrittore di sicurezza.

È possibile visualizzare un'implementazione di quanto sopra nel codice del server RPC nell'esempio di funzionalità personalizzate.

Consentire l'accesso a un driver a un'app UWP usando la funzionalità personalizzata

Per consentire l'accesso a un driver a un'app UWP con la funzionalità personalizzata, aggiungere alcune righe al file INF o all'origine del driver.

Nel file INF specificare la funzionalità personalizzata come indicato di seguito:

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

In alternativa, eseguire le operazioni seguenti nel 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));

Sostituire zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz con il GUID per l'interfaccia da esporre. Sostituire CompanyName con il nome della società, myCustomCapabilityName con un nome univoco all'interno dell'azienda e MyStorePubId con l'ID archivio dell'editore.

Per un esempio del codice driver illustrato immediatamente sopra, vedere toolkit di installazione dei pacchetti driver per i driver universali.

Per impostare la proprietà in modalità kernel, usare codice simile al seguente:

#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

Preparazione del file SCCD (Signed Custom Capability Descriptor)

Un file SCCD (Signed Custom Capability Descriptor) è un file XML firmato che autorizza l'uso di una o più funzionalità personalizzate. Il proprietario del driver o dell'endpoint RPC concede la funzionalità personalizzata allo sviluppatore dell'app fornendo questo file.

Per preparare il file SCCD, aggiornare prima di tutto la stringa di funzionalità personalizzata. Usare l'esempio seguente come punto di partenza:

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

Successivamente, il proprietario della funzionalità personalizzata ottiene il nome della famiglia di pacchetti (PFN) e l'hash della firma dallo sviluppatore dell'app e aggiorna tali stringhe nel file SCCD.

Nota

L'app non deve essere firmata direttamente con il certificato, ma il certificato specificato deve far parte della catena di certificati che firma l'app.

Dopo aver completato SCCD, il proprietario della funzionalità invia un messaggio di posta elettronica a Microsoft per la firma. Microsoft restituisce lo SCCD firmato al proprietario della funzionalità.

Il proprietario della funzionalità invia quindi lo SCCD allo sviluppatore dell'app. Lo sviluppatore di app include lo SCCD firmato nel manifesto dell'app. Per informazioni sulle attività che lo sviluppatore di app deve eseguire, vedere Hardware Support App (HSA): Passaggi per sviluppatori di app.

Limitazione dell'ambito di un SCCD

Ai fini dei test, un proprietario di funzionalità personalizzato può limitare l'installazione di un'app di supporto hardware ai computer in modalità sviluppatore.

A tale scopo, prima di ottenere il codice SCCD firmato da Microsoft, aggiungere 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>

Il codice SCCD firmato risultante funziona solo nei dispositivi in modalità sviluppatore.

Consentire a qualsiasi app di usare una funzionalità personalizzata

È consigliabile specificare entità autorizzate (app) che possono usare una funzionalità personalizzata. In alcuni casi, tuttavia, potrebbe essere necessario consentire a qualsiasi app di includere un SCCD. A partire da Windows 10 versione 1809, puoi farlo aggiungendo AllowAny all'elemento AuthorizedEntities. Poiché la procedura consigliata consiste nel dichiarare le entità autorizzate nel file SCCD, fornire una giustificazione per l'uso di AllowAny durante l'invio di SCCD per la firma da parte di 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>

Il codice SCCD firmato risultante verrà convalidato in qualsiasi pacchetto dell'app.

Più SCCD

A partire da Windows 10 versione 1803, le app possono dichiarare funzionalità personalizzate da uno o più file SCCD. Inserire i file SCCD nella radice del pacchetto dell'app.

SCCD XML Schema

Di seguito è riportato lo schema XSD XML formale per un file SCCD. Usare questo schema per convalidare il codice SCCD prima di inviarlo per la revisione. Per informazioni sull'importazione di uno schema e la convalida con IntelliSense, vedere Schema Cache and XML Document validation (Convalida della cache dello schema e del documento 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>

Lo schema seguente è valido anche a partire da Windows 10 versione 1809. Consente a un SCCD di dichiarare qualsiasi pacchetto dell'app come entità autorizzata.

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