Aplicación de soporte técnico de hardware (HSA): pasos para desarrolladores de controladores
Una aplicación de soporte técnico de hardware (HSA) es una aplicación específica del dispositivo que está emparejada con un controlador específico o un punto de conexión RPC (llamada a procedimiento remoto).
Para asociar una aplicación de la Tienda a un controlador, reserve primero un valor especial denominado funcionalidad personalizada. A continuación, permita el acceso a las aplicaciones que anuncian la funcionalidad y proporcionen 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 de soporte técnico de hardware (HSA): Pasos para desarrolladores de aplicaciones.
HSA es uno de los tres principios de diseño ("DCH") de los controladores de Windows.
Reserva de una funcionalidad personalizada
En primer lugar, reserve una funcionalidad personalizada:
Email Revisión de aplicaciones de soporte técnico de 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 problema de seguridad o privacidad
¿Qué eventos de datos se procesarán 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 de los usuarios o se envían al asociado?
¿A qué datos proporciona su funcionalidad acceso?
¿Cuál es la ventaja para el usuario final de esta funcionalidad?
Incluya el identificador del publicador de aplicaciones de Microsoft Store. Para obtener una, cree una entrada de aplicación esqueleto en la página de Microsoft Store. Para obtener más información sobre cómo reservar el PFN de la aplicación, consulta Creación de la aplicación reservando un nombre.
Si se aprueba la solicitud, Microsoft envía un correo electrónico a un nombre de cadena de funcionalidad personalizado único en 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 permitida de acceso junto con cualquier otro SID necesario para el descriptor de seguridad del punto de conexión RPC.
Cree un punto de conexión RPC mediante 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 la empresa, myCustomCapabilityName por un nombre único dentro de la empresa y MyStorePubId por el identificador de la tienda del publicador.
Para obtener un ejemplo del código de controlador que se muestra inmediatamente arriba, 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 Signed Custom Capability Descriptor (SCCD) 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
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 necesita hacer, consulte Aplicación de soporte técnico de hardware (HSA): Pasos para desarrolladores de aplicaciones.
Limitar el ámbito de un SCCD
Con fines de prueba, un propietario de funcionalidad personalizada puede restringir la instalación de una aplicación de soporte técnico de hardware a los equipos en modo de desarrollador.
Para ello, antes de que Microsoft firme el SCCD, 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 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.
Resumen de la secuencia de firma de SCCD
En el diagrama siguiente se resume la secuencia descrita anteriormente:
Esquema XML de 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 validar 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 cualquier paquete de aplicación para que 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>
Consulte también
Introducción con controladores de Windows
Introducción a la Plataforma universal de Windows
Plataforma universal de Windows (UWP)
Características de aplicaciones
Desarrollo de aplicaciones para UWP con Visual Studio
Emparejamiento de un controlador con una aplicación de Plataforma universal de Windows (UWP)
Desarrollar aplicaciones para UWP
Empaquetamiento de una aplicación con Desktop App Converter (Puente de dispositivo de escritorio)
Aplicación de ejemplo de funcionalidad personalizada
Ejemplo de controlador de funcionalidad personalizada
Instalación de prueba de aplicaciones en Windows 10
Preguntas más frecuentes sobre las funcionalidades personalizadas
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de