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

Un'app di supporto hardware (HSA) è 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") dei driver di Windows.

Prenotazione di una funzionalità personalizzata

Prima di tutto, riservare una funzionalità personalizzata:

  1. Email Revisione delle app di supporto hardware Microsoft (HSAReview@microsoft.com) con le informazioni seguenti:

    • Informazioni contatto

    • Nome azienda

    • Nome della funzionalità (deve essere univoco e fare riferimento al proprietario)

    • Quali risorse devono accedere alle risorse?

    • Eventuali problemi di sicurezza o privacy

    • Quali eventi di dati verranno elaborati al partner?

      • Gli eventi includono identificatori personali, ad esempio percorsi utente precisi, password, indirizzo IP, PUID, ID dispositivo, CID, nome utente e dati di contatto)?

      • Gli eventi di dati rimangono nel dispositivo degli utenti o vengono inviati al partner?

    • Quali dati forniscono l'accesso alle funzionalità?

    • Qual è il vantaggio dell'utente finale di questa funzionalità?

    • Includere l'ID editore dell'app di Microsoft Store. Per ottenerne uno, creare una voce di app scheletro nella pagina di Microsoft Store. Per altre info sulla prenotazione del pfn dell'app, vedi Creare la tua app riservando un nome.

  2. Se la richiesta viene approvata, Microsoft invia un messaggio di posta elettronica a un nome 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:

  1. Chiamare DeriveCapabilitySidsFromName per convertire il nome della funzionalità personalizzata in un ID di sicurezza (SID).

  2. Aggiungere il SID all'accesso consentito ACE insieme a qualsiasi altro SID necessario per il descrittore di sicurezza dell'endpoint RPC.

  3. Creare un endpoint RPC usando le informazioni del descrittore di sicurezza.

È possibile visualizzare un'implementazione di sopra nel codice del server RPCnell'esempio di funzionalità personalizzata.

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 della società e MyStorePubId con l'ID dello store dell'editore.

Per un esempio del codice driver illustrato immediatamente sopra, vedere il toolkit di installazione del pacchetto 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 il codice SCCD firmato al proprietario della funzionalità.

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

Limitazione dell'ambito di un SCCD

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

A tale scopo, prima di ottenere la firma SCCD 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) in grado di usare una funzionalità personalizzata. In alcuni casi, tuttavia, potresti voler consentire a qualsiasi app di includere un SCCD. A partire da Windows 10 versione 1809, è possibile eseguire questa operazione 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.

Riepilogo della sequenza di firma SCCD

Il diagramma seguente riepiloga la sequenza descritta in precedenza:

Recupero di un oggetto SCCD firmato.

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

Vedi anche

Introduzione ai driver di Windows

Introduzione alla piattaforma UWP (Universal Windows Platform)

Piattaforma UWP (Universal Windows Platform)

Funzionalità dell'app

Sviluppare app UWP con Visual Studio

Associazione di un driver a un'app UWP (Universal Windows Platform)

Sviluppare app UWP

Creare il pacchetto di un'app con Desktop App Converter (Desktop Bridge)

App di esempio di funzionalità personalizzate

Esempio di driver di funzionalità personalizzate

Trasferisci localmente le app in Windows 10

Domande frequenti sulle funzionalità personalizzate