次の方法で共有


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

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

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

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

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

カスタム機能の予約

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

  1. 次の情報を電子メールで Microsoft ハードウェア サポート アプリ レビュー (HSAReview@microsoft.com) に送信してください。

    • 連絡先情報

    • 会社名

    • 機能の名前 (一意であり、所有者を参照する必要があります)

    • 機能がアクセスする必要があるリソースは何ですか?

    • セキュリティやプライバシーに関する懸念がある場合

    • パートナーに対してどのようなデータ イベントが処理されますか?

      • イベントには、正確なユーザーの位置、パスワード、IP アドレス、PUID、デバイス ID、CID、ユーザー名、連絡先データなどの個人識別子が含まれますか?

      • データ イベントはユーザーのデバイスに残りますか、それともパートナーに送信されますか?

    • あなたの能力はどのデータへのアクセスを提供しますか?

    • この機能のエンドユーザーにとってのメリットは何ですか?

    • Microsoft Store アプリ発行者 ID を含めます。 これを入手するには、Microsoft Store ページでスケルトン アプリのエントリを作成します。 アプリの PFN の予約の詳細については、「名前を予約してアプリを作成する」を参照してください。

  2. 要求が承認されると、Microsoft は CompanyName.capabilityName_PublisherID の形式で一意のカスタム機能文字列名を電子メールで返します。

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

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

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

  1. DeriveCapabilitySidsFromName を呼び出して、カスタム機能名をセキュリティ ID (SID) に変換します。

  2. RPC エンドポイントのセキュリティ記述子に必要な他の SID とともに、アクセスが許可された ACE に SID を追加します。

  3. セキュリティ記述子の情報を使用して 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 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>

関連項目

Windows ドライバーの開発の概要

ユニバーサル Windows プラットフォームの紹介

ユニバーサル Windows プラットフォーム (UWP)

アプリの機能

Visual Studio を使用して UWP アプリを開発する

ドライバーとユニバーサル Windows プラットフォーム (UWP) アプリとのペアリング

UWP アプリを開発する

デスクトップ アプリ コンバーター (デスクトップ ブリッジ) を使用してアプリをパッケージ化する

カスタム機能サンプルアプリ

カスタム機能ドライバーのサンプル

Windows 10 のサイドロード アプリ

カスタム機能に関する FAQ