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

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 di contatto
- Nome della società
- Nome della funzionalità (deve essere univoco e fare riferimento al proprietario)
- A quali risorse deve accedere la capacità?
- Eventuali problemi di sicurezza o privacy
- Quali eventi di dati vengono 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 dell'utente o vengono inviati al partner?
- A quali dati l'accesso viene fornito dalla tua 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 scheletro di app nella pagina del Microsoft Store. Per ulteriori informazioni 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 che include 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'applicazione 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'ACE di accesso consentito insieme agli altri SIDs necessari per il descrittore di sicurezza dell'endpoint RPC.
Creare un endpoint RPC usando le informazioni del descrittore di sicurezza.

È possibile visualizzare un'implementazione di questo processo nel codice del server RPC nell'esempio di funzionalità personalizzata.

Consentire l'accesso di un driver a un'app UWP usando la capacità 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, implementare questo codice 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 vostra società, myCustomCapabilityName con un nome unico all'interno della vostra azienda e MyStorePubId con l'ID del vostro negozio come editore.

Per un esempio di questo codice driver implementato, vedere toolkit di installazione dei pacchetti driver per i driver universali.

Per impostare la proprietà in modalità kernel, usare questo codice:

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

Note

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 viene convalidato in qualsiasi pacchetto di un'app.

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-25