ハードウェアサポートアプリ (HSA): ドライバー開発者向けの手順

[アーティクル]
03/19/2024

ハードウェアサポートアプリ (HSA) は、特定のドライバーまたは RPC (リモートプロシージャコール) エンドポイントとペアになっているデバイス固有のアプリです。

ストアアプリをドライバーに関連付けるには、まずカスタム機能と呼ばれる特別な値を予約します。次に、その機能を宣伝し、アプリ開発者に機能を提供するアプリへのアクセスを許可します。このページでは、ドライバー開発者向けにこれらの手順を説明します。

アプリ開発者向けの手順は、ハードウェアサポートアプリ (HSA) で説明されています。アプリ開発者向けの手順

HSA は、Windows ドライバーの 3 つの設計原則 (「DCH」) の 1 つです。

カスタム機能の予約

まず、カスタム機能を予約します。

次の情報を電子メールで Microsoft ハードウェアサポートアプリレビュー (HSAReview@microsoft.com) に送信してください。
- 連絡先情報
- 会社名
- 機能の名前 (一意であり、所有者を参照する必要があります)
- 機能がアクセスする必要があるリソースは何ですか?
- セキュリティやプライバシーに関する懸念がある場合
- パートナーに対してどのようなデータイベントが処理されますか?
  - イベントには、正確なユーザーの位置、パスワード、IP アドレス、PUID、デバイス ID、CID、ユーザー名、連絡先データなどの個人識別子が含まれますか?
  - データイベントはユーザーのデバイスに残りますか、それともパートナーに送信されますか?
- あなたの能力はどのデータへのアクセスを提供しますか?
- この機能のエンドユーザーにとってのメリットは何ですか?
- Microsoft Store アプリ発行者 ID を含めます。これを入手するには、Microsoft Store ページでスケルトンアプリのエントリを作成します。アプリの PFN の予約の詳細については、「名前を予約してアプリを作成する」を参照してください。
要求が承認されると、Microsoft は CompanyName.capabilityName_PublisherID の形式で一意のカスタム機能文字列名を電子メールで返します。

これで、カスタム機能を使用して、RPC エンドポイントまたはドライバーへのアクセスを許可できるようになりました。

カスタム機能を使用して UWP アプリへの RPC エンドポイントへのアクセスを許可する

カスタム機能を持つ UWP アプリへの RPC エンドポイントへのアクセスを許可するには、次の手順を実行します。

DeriveCapabilitySidsFromName を呼び出して、カスタム機能名をセキュリティ ID (SID) に変換します。
RPC エンドポイントのセキュリティ記述子に必要な他の SID とともに、アクセスが許可された ACE に SID を追加します。
セキュリティ記述子の情報を使用して RPC エンドポイントを作成します。

カスタム機能サンプルの RPC サーバーコードで上記の実装を確認できます。

カスタム機能を使用して、UWP アプリへのドライバーへのアクセスを許可する

カスタム機能を使用して UWP アプリへのドライバーへのアクセスを許可するには、INF ファイルまたはドライバーソースのいずれかに数行を追加します。

INF ファイルで、次のようにカスタム機能を指定します。

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

または、ドライバーで次の操作を実行します。

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

公開するインターフェイスの GUID に置き換えzzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzzます。 CompanyName を会社名に、myCustomCapabilityName を会社内で一意の名前に、MyStorePubId を発行元のストア ID に置き換えます。

すぐ上に示したドライバーコードの例については、ユニバーサルドライバーのドライバーパッケージインストールツールキットを参照してください。

カーネルモードでプロパティを設定するには、次のようなコードを使用します。

#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

署名付きカスタム機能記述子 (SCCD) ファイルの準備

署名付きカスタム機能記述子 (SCCD) ファイルは、1 つ以上のカスタム機能の使用を許可する署名付き XML ファイルです。ドライバーまたは RPC エンドポイントの所有者は、このファイルを提供することで、アプリ開発者にカスタム機能を付与します。

SCCD ファイルを準備するには、まずカスタム機能文字列を更新します。次の例を出発点として使用してください。

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

次に、カスタム機能の所有者は、アプリ開発者からパッケージファミリ名 (PFN) と署名ハッシュを取得し、SCCD ファイル内のそれらの文字列を更新します。

Note

アプリは証明書で直接署名する必要はありませんが、指定された証明書はアプリに署名する証明書チェーンの一部である必要があります。

SCCD が完成したら、機能所有者はそれを署名のために Microsoft に電子メールで送信します。 Microsoft は、署名された SCCD を機能所有者に返却します。

次に、機能所有者は SCCD をアプリ開発者に送信します。アプリ開発者は、署名された SCCD をアプリのマニフェストに含めます。アプリ開発者が行う必要があることについては、「ハードウェアサポートアプリ (HSA)」を参照してください。アプリ開発者向けの手順

SCCD の範囲の制限

テスト目的で、カスタム機能所有者は、開発者モードのコンピューターへのハードウェアサポートアプリのインストールを制限できます。

これを行うには、Microsoft によって署名された SCCD を取得する前に、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>

結果として得られる署名付き SCCD は、開発者モードのデバイスでのみ機能します。

任意のアプリにカスタム機能の使用を許可する

カスタム機能を使用できる承認されたエンティティ (アプリ) を指定することをお勧めします。ただし、場合によっては、すべてのアプリに SCCD を含めることを許可したい場合があります。 Windows 10 バージョン 1809 以降では、AllowAny を AuthorizedEntities 要素に追加することでこれを行うことができます。ベストプラクティスは、SCCD ファイル内で承認されたエンティティを宣言することであるため、Microsoft による署名を得るために SCCD を送信するときに、AllowAny を使用する正当な理由を提供してください。

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

結果として得られる署名付き SCCD は、どのアプリパッケージでも検証されます。

複数の SCCD

Windows 10 バージョン 1803 以降、アプリは 1 つ以上の SCCD ファイルからカスタム機能を宣言できます。 SCCD ファイルをアプリパッケージのルートに配置します。

SCCD 署名シーケンスの概要

次の図は、上記のシーケンスを要約したものです。

Getting an SCCD signed.

SCCD XML スキーマ

以下は、SCCD ファイルの正式な XML XSD スキーマです。レビューのために送信する前に、このスキーマを使用して SCCD を検証します。スキーマのインポートと IntelliSense による検証については、「スキーマキャッシュと 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>

次のスキーマは、Windows 10 バージョン 1809 の時点でも有効です。これにより、SCCD は任意のアプリパッケージを承認されたエンティティであると宣言できるようになります。

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

ハードウェアサポートアプリ (HSA): ドライバー開発者向けの手順

カスタム機能の予約

カスタム機能を使用して UWP アプリへの RPC エンドポイントへのアクセスを許可する

カスタム機能を使用して、UWP アプリへのドライバーへのアクセスを許可する

署名付きカスタム機能記述子 (SCCD) ファイルの準備

SCCD の範囲の制限

任意のアプリにカスタム機能の使用を許可する

複数の SCCD

SCCD 署名シーケンスの概要

SCCD XML スキーマ

関連項目

フィードバック

フィードバック

その他のリソース

ハードウェア サポート アプリ (HSA): ドライバー開発者向けの手順

カスタム機能の予約

カスタム機能を使用して UWP アプリへの RPC エンドポイントへのアクセスを許可する

カスタム機能を使用して、UWP アプリへのドライバーへのアクセスを許可する

署名付きカスタム機能記述子 (SCCD) ファイルの準備

SCCD の範囲の制限

任意のアプリにカスタム機能の使用を許可する

複数の SCCD

SCCD 署名シーケンスの概要

SCCD XML スキーマ

関連項目

フィードバック

フィードバック

その他のリソース

ハードウェアサポートアプリ (HSA): ドライバー開発者向けの手順