Aplicación para compatibilidad con hardware (HSA): Pasos para desarrolladores de controladores

Important

Los metadatos de dispositivo están obsoletos y se eliminarán en una futura versión de Windows. Para obtener información sobre el reemplazo de esta funcionalidad, vea Driver Package Container Metadata.

Una aplicación para compatibilidad con hardware (HSA) es una aplicación específica del dispositivo que está emparejada con un controlador específico o un punto de conexión de RPC (llamada a procedimiento remoto).

Para asociar una aplicación de la Tienda con un controlador, reserve primero un valor especial denominado funcionalidad personalizada. A continuación, permita el acceso a las aplicaciones que anuncian la funcionalidad y proporcione la funcionalidad al desarrollador de la aplicación. En esta página se describen estos pasos para el desarrollador de controladores.

Los pasos para el desarrollador de aplicaciones se describen en Aplicación para compatibilidad con hardware (HSA): Pasos para desarrolladores de aplicaciones.

HSA es uno de los tres principios de diseño "DCH".

Reserva de una funcionalidad personalizada

En primer lugar, reserve una funcionalidad personalizada:

Envíe por correo electrónico la revisión de las aplicaciones para compatibilidad con hardware de Microsoft (HSAReview@microsoft.com) con la siguiente información:
- Contact information
- Company name
- Nombre de la funcionalidad (debe ser único y hacer referencia al propietario)
- ¿A qué recursos necesita acceder la funcionalidad?
- Cualquier problemas de seguridad o privacidad
- ¿Qué eventos de datos se procesan para el asociado?
  - ¿Los eventos incluyen identificadores personales, como ubicaciones de usuario precisas, contraseñas, dirección IP, PUID, id. de dispositivo, CID, nombre de usuario y datos de contacto?
  - ¿Los eventos de datos permanecen en el dispositivo del usuario o se envían al asociado?
- ¿A qué datos proporciona acceso la funcionalidad?
- ¿Qué ventaja tiene para el usuario final esta funcionalidad?
- Incluya el identificador del publicador de aplicaciones de Microsoft Store. Para obtener uno, cree una entrada de aplicación maestra en la página de Microsoft Store. Para obtener más información sobre cómo reservar el PFN de una aplicación, consulte Creación de la aplicación reservando un nombre.
If the request is approved, Microsoft emails back a unique custom capability string name in the format CompanyName.capabilityName_PublisherID.

Ahora puede usar la funcionalidad personalizada para permitir el acceso a un punto de conexión RPC o a un controlador.

Permitir el acceso a un punto de conexión RPC a una aplicación para UWP mediante la funcionalidad personalizada

Para permitir el acceso a un punto de conexión RPC a una aplicación para UWP que tenga la funcionalidad personalizada, siga estos pasos:

Call DeriveCapabilitySidsFromName to convert the custom capability name to a security ID (SID).
Agregue el SID a la ACE de acceso permitido junto con cualquier otro SID necesario para el descriptor de seguridad del punto de conexión RPC.
Cree un punto de conexión RPC con la información del descriptor de seguridad.

Puede ver una implementación de este proceso en el código del servidor RPC en el ejemplo de funcionalidad personalizada.

Permitir el acceso a un controlador a una aplicación para UWP mediante la funcionalidad personalizada

Para permitir el acceso a un controlador a una aplicación para UWP con la funcionalidad personalizada, agregue algunas líneas al archivo INF o al origen del controlador.

En el archivo INF, especifique la funcionalidad personalizada de la siguiente manera:

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

O bien, implemente este código en el controlador:

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

Reemplace zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz por el GUID de la interfaz que se va a exponer. Replace CompanyName with your company name, myCustomCapabilityName with a name that is unique within your company, and MyStorePubId with your publisher store ID.

Para obtener un ejemplo de este código de controlador implementado, consulte el conjunto de herramientas de instalación del paquete de controladores para controladores universales.

Para establecer la propiedad en modo kernel, use este código:

#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

Preparación del archivo de descriptor de funcionalidad personalizada (SCCD) firmado

Un archivo de descriptor de funcionalidad personalizada (SCCD) firmado es un archivo XML firmado que autoriza el uso de una o varias funcionalidades personalizadas. El propietario del controlador o el punto de conexión RPC concede la funcionalidad personalizada al desarrollador de la aplicación proporcionando este archivo.

Para preparar el archivo SCCD, actualice primero la cadena de funcionalidad personalizada. Use el ejemplo siguiente como punto de partida:

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

A continuación, el propietario de la funcionalidad personalizada obtiene el nombre de familia de paquete (PFN) y el hash de firma del desarrollador de la aplicación y actualiza esas cadenas en el archivo SCCD.

Note

La aplicación no tiene que firmarse directamente con el certificado, pero el certificado especificado debe formar parte de la cadena de certificados que firma la aplicación.

Después de completar el SCCD, el propietario de la funcionalidad lo envía por correo electrónico a Microsoft para firmarlo. Microsoft devuelve el SCCD firmado al propietario de la funcionalidad.

A continuación, el propietario de la funcionalidad envía el SCCD al desarrollador de la aplicación. El desarrollador de la aplicación incluye el SCCD firmado en el manifiesto de la aplicación. Para obtener información sobre lo que el desarrollador de aplicaciones debe hacer, consulte Aplicación para compatibilidad con hardware (HSA): Pasos para desarrolladores de aplicaciones.

Limitación del ámbito de un SCCD

Con fines de prueba, un propietario de funcionalidad personalizada puede restringir la instalación de una aplicación para compatibilidad con hardware a los equipos en modo de desarrollador.

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.

Permitir que cualquier aplicación use una funcionalidad personalizada

Se recomienda especificar entidades autorizadas (aplicaciones) que puedan usar una funcionalidad personalizada. Sin embargo, en algunos casos, es posible que quiera permitir que cualquier aplicación incluya 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>

El SCCD firmado resultante se valida en cualquier paquete de aplicación.

Multiple SCCDs

A partir de windows 10 versión 1803, las aplicaciones pueden declarar funcionalidades personalizadas desde uno o varios archivos SCCD. Coloque los archivos SCCD en la raíz del paquete de la aplicación.

Esquema XML del SCCD

A continuación se muestra el esquema XSD XML formal para un archivo SCCD. Use este esquema para validar el SCCD antes de enviarlo para su revisión. 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>

El esquema siguiente también es válido a partir de Windows 10, versión 1809. Permite que un SCCD declare que cualquier paquete de aplicación sea una entidad autorizada.

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

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-24