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

Artículo
09/23/2024

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:
- Información de contacto
- Nombre de la compañía
- 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 procesarán para el partner?
  - ¿Los eventos incluirían identificadores personales, como ubicaciones precisas de usuarios, 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 de los usuarios o se envían al partner?
- ¿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.
Si se aprueba la solicitud, Microsoft envía por correo electrónico un nombre de cadena de funcionalidad personalizado único con el formato 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:

Llame a DeriveCapabilitySidsFromName para convertir el nombre de la funcionalidad personalizada en un identificador de seguridad (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 lo anterior 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, haga lo siguiente 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. Reemplace CompanyName por el nombre de su empresa, myCustomCapabilityName por un nombre que sea único en su empresa y MyStorePubId por el identificador de la tienda del publicador.

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

Para establecer la propiedad en modo kernel, use código como el siguiente:

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

Nota:

Aunque la aplicación no tiene que firmarse directamente con el certificado, 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.

Para ello, antes de obtener el SCCD firmado por Microsoft, agregue 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>

El SCCD firmado resultante solo funciona en dispositivos en modo de desarrollador.

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. A partir de Windows 10 versión 1809, puede hacerlo agregando AllowAny al elemento AuthorizedEntities. Dado que el procedimiento recomendado es declarar entidades autorizadas en el archivo SCCD, proporcione una justificación para usar AllowAny al enviar su SCCD para que Microsoft lo firme.

<?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 validará en cualquier paquete de aplicación.

Varios SCCD

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. Consulte Caché de esquemas y Validación de documentos XML para obtener información sobre cómo importar un esquema y validarlo con 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>