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

Important

デバイスメタデータは非推奨となり、Windows の今後のリリースで削除される予定です。この機能の置き換えについては、「 ドライバーパッケージコンテナーメタデータ」を参照してください。

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

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

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

HSA は、3 つの「DVH」設計原則の 1 つです。

カスタム機能の予約

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

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

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

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

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

Call DeriveCapabilitySidsFromName to convert the custom capability name to a security 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ます。 Replace CompanyName with your company name, myCustomCapabilityName with a name that is unique within your company, and MyStorePubId with your publisher store 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 の範囲の制限

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

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.

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

カスタム機能を使用できる承認されたエンティティ (アプリ) を指定することをお勧めします。ただし、場合によっては、すべてのアプリに 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>

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

Multiple SCCDs

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

SCCD XML スキーマ

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

次のスキーマは、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>

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-07-24