Разблокировка Windows с помощью устройств-компаньонов (IoT) для Windows HelloWindows Unlock with Windows Hello companion (IoT) devices

Устройство-компаньон Windows Hello — это устройство, которое может взаимодействовать с настольным компьютером Windows 10 для повышения удобства процедуры проверки подлинности пользователя.A Windows Hello companion device is a device that can act in conjunction with your Windows 10 desktop to enhance the user authentication experience. С помощью платформы устройств, сопровождающей Windows Hello, вспомогательное устройство может обеспечить широкие возможности Windows Hello, даже если они недоступны (например, если на рабочем столе Windows 10 отсутствует Камера для проверки подлинности лиц или устройства чтения отпечатков пальцев).Using the Windows Hello companion device framework, a companion device can provide a rich experience for Windows Hello even when biometrics are not available (for example, if the Windows 10 desktop lacks a camera for face authentication or fingerprint reader device, for example).

Примечание

API для платформы компаньона устройств Windows Hello является устаревшим в Windows 10, версия 2004.The API for the Windows Hello companion device framework is deprecated in Windows 10, version 2004.

Примечание

Платформа устройства Windows Hello Companion — это специализированная функция, которая недоступна для всех разработчиков приложений.The Windows Hello companion device framework is a specialized feature that's not available to all app developers. Чтобы использовать эту платформу, ваше приложение должно быть особым образом подготовлено к работе корпорацией Майкрософт и содержать ограниченную возможность secondaryAuthenticationFactor в своем манифесте.To use this framework, your app must be specifically provisioned by Microsoft and list the restricted secondaryAuthenticationFactor capability in its manifest. Чтобы получить утверждение, обратитесь к cdfonboard@microsoft.com .To obtain approval, contact cdfonboard@microsoft.com.

ВведениеIntroduction

Видеообзор см. в презентации Разблокировка Windows с помощью устройств IoT, представленной на конференции Build 2016 на веб-сайте Channel 9.For a video overview, see the Windows Unlock with IoT Devices session from Build 2016 on Channel 9.

Примеры кода см. в Репозитории Github платформы сопутствующих устройств для Windows Hello.For code samples, see the Windows Hello companion device framework Github repository.

Варианты использованияUse cases

Существует множество способов использования платформы сопутствующих устройств Windows Hello для реализации удобной разблокировки Windows с помощью устройства-компаньона.There are numerous ways one can use the Windows Hello companion device framework to build a great Windows unlock experience with a companion device. Например, пользователи могут делать следующее:For example, users could:

  • Подключить свое сопутствующее устройство к компьютеру через USB-порт, нажать кнопку на устройстве и автоматически разблокировать компьютер.Attach their companion device to PC via USB, touch the button on the companion device, and automatically unlock their PC.
  • Носить с собой телефон, уже связанный с компьютером через Bluetooth.Carry a phone in their pocket that is already paired with PC over Bluetooth. После нажатия на клавишу "ПРОБЕЛ" на компьютере на телефон приходит уведомление.Upon hitting the spacebar on their PC, their phone receives a notification. Подтвердить его, после чего компьютер разблокируется.Approve it and the PC simply unlocks.
  • Приложить сопутствующее устройство к NFC-сканеру, чтобы быстро разблокировать компьютер.Tap their companion device to an NFC reader to quickly unlock their PC.
  • Носить фитнес-браслет, владелец которого уже прошел проверку подлинности с его помощью.Wear a fitness band that has already authenticated the wearer. Когда пользователь подходит к компьютеру и выполняет особый жест (например, хлопок), происходит разблокировка компьютера.Upon approaching PC, and by performing a special gesture (like clapping), the PC unlocks.

Устройства-компаньоны для Windows Hello с поддержкой биометрииBiometric enabled Windows Hello companion devices

Если устройство-компаньон поддерживает биометрию, в некоторых случаях биометрическая платформа Windows может быть более удобным решением, чем платформа сопутствующих устройств для Windows Hello.If the companion device supports biometrics, in some cases the Windows Biometric framework may be a better solution than the Windows Hello companion device framework. Свяжитесь с cdfonboard@microsoft.com нами, и мы поможем вам выбрать правильный подход.Please contact cdfonboard@microsoft.com and we'll help you pick the right approach.

Компоненты решенияComponents of the solution

На схеме ниже представлены компоненты решения, а также указано, кто отвечает за их создание.The diagram below depicts the components of the solution and who is responsible for building them.

обзор платформы

Платформа сопутствующих устройств для Windows Hello реализована как служба под управлением Windows (в этой статье она носит название службы проверки подлинности устройств-компаньонов).The Windows Hello companion device framework is implemented as a service running on Windows (called the Companion Authentication Service in this article). Эта служба отвечает за создание маркера разблокировки, который должен быть защищен ключом HMAC, хранящимся на устройстве-компаньоне Windows Hello.This service is responsible for generating an unlock token which needs to be protected by an HMAC key stored on the Windows Hello companion device. Это гарантирует, что для доступа к маркеру разблокировки будет необходимо использовать само устройство-компаньон Windows Hello.This guarantees that access to the unlock token requires Windows Hello companion device presence. Для каждого кортежа (компьютер, пользователь Windows) создается уникальный маркер разблокировки.Per each (PC, Windows user) tuple, there will be a unique unlock token.

Условия успешной интеграции с платформой сопутствующих устройств для Windows Hello:Integration with the Windows Hello Companion Device Framework requires:

  • Наличие приложения универсальной платформы Windows (UWP) для устройства-компаньона Windows Hello, скачанного из Магазина приложений для Windows.A Universal Windows Platform (UWP) Windows Hello companion device app for the companion device, downloaded from the Windows app store.
  • Возможность создать два 256-битных ключа HMAC на устройстве-компаньоне Windows Hello и сформировать код HMAC с его помощью (с использованием алгоритма SHA-256).The ability to create two 256 bit HMAC keys on the Windows Hello companion device and generate HMAC with it (using SHA-256).
  • Верно настроенные параметры безопасности на настольном компьютере с Windows 10.Security settings on the Windows 10 desktop properly configured. Этот PIN-код потребуется службе проверки подлинности устройств-компаньонов, чтобы выполнить настройку, прежде чем к ней будет подключено устройство-компаньон Windows Hello.The Companion Authentication Service will require this PIN to be set up before any Windows Hello companion device can be plugged into it. Пользователям необходимо задать PIN-код в разделе "Параметры" > "Учетные записи" > "Параметры входа".The users must set up a PIN via Settings > Accounts > Sign-in options.

Помимо указанных выше требований, приложение устройства-компаньона Windows Hello также отвечает за выполнение следующих процессов:In addition to the above requirements, the Windows Hello companion device app is responsible for:

  • Взаимодействие с пользователем и отображение фирменной символики во время начальной регистрации, а также последующая отмена регистрации устройства-компаньона Windows Hello.User experience and branding of initial registration and later de-registration of the Windows Hello companion device.
  • Работа в фоновом режиме, обнаружение устройства-компаньона Windows Hello, подключение к этому устройству и службе проверки подлинности устройств-компаньонов.Running in the background, discovering the Windows Hello companion device, communicating to the Windows Hello companion device and also Companion Authentication Service.
  • Обработка ошибокError handling

Обычно сопутствующие устройства поставляются с приложением для начальной настройки, например для первоначальной настройки фитнес-браслета.Normally, companion devices ship with an app for initial setup, like setting up a fitness band for the first time. В подобном приложении описанные в этом документе функции могут быть уже реализованы. В этом случае отдельное приложение не потребуется.The functionality described in this document can be part of that app and a separate app should not be required.

Сигналы пользователяUser signals

Каждое устройство-компаньон Windows Hello должно работать в связке с приложением, поддерживающим три сигнала пользователя.Each Windows Hello companion device should be combined with an app that supports three user signals. Эти сигналы могут быть в форме действий или жестов.These signals can be in form of an action or gesture.

  • Сигнал намерения: позволяет пользователю выражать свое намерение разблокировать компьютер, например путем нажатия кнопки на устройстве-компаньоне Windows Hello.Intent signal: Allows the user to show his intent for unlock by, for example, hitting a button on the Windows Hello companion device. Сигнал намерения должен поступать c устройства-компаньона Windows Hello.The intent signal must be collected on Windows Hello companion device side.
  • Сигнал присутствия пользователя: подтверждает присутствие пользователя.User presence signal: Proves the presence of the user. Устройство-компаньон Windows Hello может, например, запросить PIN-код, прежде чем его можно будет использовать для разблокировки компьютера (не путать с PIN-кодом компьютера), либо запросить нажатие кнопки.The Windows Hello companion device might, for instance, require a PIN before it can be used for unlocking PC (not to be confused with PC PIN), or it might require press of a button.
  • Сигнал уточнения: уточняет, какой компьютер с Windows 10 пользователь хочет разблокировать, если на устройстве-компаньоне Windows Hello доступно несколько вариантов.Disambiguation signal: Disambiguates which Windows 10 desktop the user wants to unlock when multiple options are available to the Windows Hello companion device.

Любое число этих сигналов можно объединить в один сигнал.Any number of these user signals can be combined into one. Сигналы присутствия пользователя и намерения должны запрашиваться при каждом использовании.User presence and intent signals must be required on each use.

Регистрация и дальнейшая связь между компьютером и устройствами-компаньонами Windows HelloRegistration and future communication between a PC and Windows Hello companion devices

Перед подключением устройства-компаньона Windows Hello к платформе сопутствующих устройств Windows Hello его необходимо зарегистрировать на этой платформе.Before a Windows Hello companion device can be plugged into the Windows Hello companion device framework, it needs to be registered with the framework. Приложение устройства-компаньона Windows Hello управляет всеми этапами процесса регистрации.The experience for registration is completely owned by the Windows Hello companion device app.

Связь между устройством-компаньоном Windows Hello и настольным компьютером с Windows 10 может быть множественной (то есть одно устройство-компаньон можно использовать для нескольких настольных компьютеров с Windows 10).The relationship between the Windows Hello companion device and the Windows 10 desktop device can be one to many (i.e., one companion device can be used for many Windows 10 desktop devices). Однако каждое устройство-компаньон Windows Hello можно использовать только для одного пользователя на каждом настольном компьютере с Windows 10.However, each Windows Hello companion device can only be used for one user on each Windows 10 desktop device.

Прежде чем устройство-компаньон Windows Hello сможет обмениваться данными с компьютером, для устройства и компьютера необходимо выбрать общий способ передачи данных.Before a Windows Hello companion device can communicate with a PC, they need to agree on a transport to use. Этот способ выбирает приложение устройства-компаньона Windows Hello. Платформа сопутствующих устройств Windows Hello не накладывает какие-либо ограничения на способ передачи данных (через USB, NFC, Wi-Fi, Bluetooth, BLE и т. д.) или протокол, используемый между устройством-компаньоном Windows Hello и его приложением на настольном компьютере с Windows 10.Such choice is left to the Windows Hello companion device app; the Windows Hello companion device framework does not impose any limitations on transport type (USB, NFC, WiFi, BT, BLE, etc) or protocol being used between the Windows Hello companion device and the Windows Hello companion device app on the Windows 10 desktop device side. Однако платформа предлагает некоторые рекомендации по безопасности на транспортном уровне, которые описаны в разделе "Требования к безопасности" в этом документе.It does, however, suggest certain security considerations for the transport layer as outlined in the "Security Requirements" section of this document. За предоставление этих требований несет ответственность поставщик устройства.It is the device provider’s responsibility to provide those requirements. Платформа их не предоставляет.The framework does not provide them for you.

Модель взаимодействия с пользователемUser Interaction Model

Обнаружение, установка и первоначальная регистрация приложения устройства-компаньона Windows HelloWindows Hello companion device app discovery, installation, and first-time registration

Обычный рабочий процесс для пользователя выглядит следующим образом:A typical user workflow is as follows:

  • Пользователь настраивает PIN-код на каждом из целевых настольных компьютеров с Windows 10, которые требуется разблокировать с помощью устройства-компаньона Windows Hello.The user sets up the PIN on each of target Windows 10 desktop devices she wants to unlock with that Windows Hello companion device.
  • Пользователь запускает приложение устройства-компаньона Windows Hello на своем настольном компьютере с Windows 10, чтобы зарегистрировать на нем свое устройство-компаньон Windows Hello.The user runs the Windows Hello companion device app on their Windows 10 desktop device to register her Windows Hello companion device with Windows 10 desktop.

Примечания.Notes:

  • Мы рекомендуем выполнять обнаружение, загрузку и запуск приложения для устройства "помощник по Windows Hello", и, если это возможно, автоматически (например, можно загрузить приложение при касании устройства с Windows Hello на стороне устройства NFC на устройстве с Windows 10).We recommend the discovery, download, and launch of the Windows Hello companion device app is streamlined and, if possible, automated (for example, the app can be downloaded upon tapping the Windows Hello companion device on an NFC reader on Windows 10 desktop device side). Однако за выполнение этой процедуры отвечают устройство-компаньон Windows Hello и его приложение.This is, however, the responsibility of the Windows Hello companion device and Windows Hello companion device app.
  • В корпоративной среде приложение устройства-компаньона Windows Hello можно развернуть через систему MDM.In an enterprise environment, the Windows Hello companion device app can be deployed via MDM.
  • Приложение устройства-компаньона Windows Hello отвечает за отправку пользователю сообщений об ошибках в ходе регистрации.The Windows Hello companion device app is responsible for showing the user any error messages that happen as part of registration.

Протокол регистрации и ее отменыRegistration and de-registration protocol

На схеме ниже показано, как устройство-компаньон Windows Hello взаимодействует со службой проверки подлинности устройств-компаньонов при регистрации.The following diagram illustrates how the Windows Hello companion device interacts with Companion Authentication Service during registration.

Схема потока регистрации.

В нашем протоколе используются два ключа:There are two keys used in our protocol:

  • ключ устройства (devicekey) применяется для защиты маркеров разблокировки, используемых компьютером для разблокировки Windows;Device key (devicekey): used to protect unlock tokens that the PC needs to unlock Windows.
  • ключ проверки подлинности (authkey) используется для взаимной проверки подлинности устройства-компаньона Windows Hello и службы проверки подлинности устройств-компаньонов.The authentication key (authkey): used to mutually authenticate the Windows Hello companion device and Companion Authentication Service.

Устройство-компаньон Windows Hello и его приложение обмениваются этими ключами при регистрации.The device key and authentication keys are exchanged at registration time between the Windows Hello companion device app and Windows Hello companion device. В итоге устройство-компаньон Windows Hello и его приложение должны использовать безопасный способ транспортировки для защиты ключей.As a result, the Windows Hello companion device app and Windows Hello companion device must use a secure transport to protect keys.

Примечание. Несмотря на то, что на схеме выше представлен процесс создания двух ключей HMAC на устройстве-компаньоне Windows Hello, приложение также может создать их и отправить устройству-компаньону Windows Hello для хранения.Also, note that while the diagram above displays two HMAC keys generating on the Windows Hello companion device, it is also possible for the app to generate them and send them to the Windows Hello companion device for storage.

Начало процессов проверки подлинностиStarting authentication flows

Пользователь может начать процесс входа на настольном компьютере с Windows 10 с помощью платформы сопутствующих устройств Windows Hello (то есть отправить сигнал намерения) двумя способами:There are two ways for the user to start the signing in flow to Windows 10 desktop using Windows Hello companion device framework (i.e., provide intent signal):

  • открыть крышку ноутбука, нажать клавишу "ПРОБЕЛ" или провести пальцем вверх по экрану компьютера;Open up the lid on laptop, or hit the space bar or swipe up on PC.
  • выполнить жест или действие на устройстве-компаньоне Windows Hello.Perform a gesture or an action on the Windows Hello companion device side.

Выбор одного из этих способов в качестве начальной точки делает устройство-компаньон Windows Hello.It is the Windows Hello companion device's choice to select which one is the starting point. Платформа сопутствующих устройств Windows Hello сообщит приложению устройства-компаньона, если произойдет первое событие.The Windows Hello companion device framework will inform companion device app when option one happens. Чтобы узнать о захвате второго события, приложение устройства-компаньона Windows Hello должно отправить запрос на устройство-компаньон.For option two, the Windows Hello companion device app should query the companion device to see if that event has been captured. Это позволяет устройству-компаньону Windows Hello получать сигнал намерения, прежде чем произойдет разблокировка.This ensures the Windows Hello companion device collects the intent signal before the unlock succeeds.

Поставщик учетных данных для устройств-компаньонов Windows HelloWindows Hello companion device credential provider

В Windows 10 появился новый поставщик учетных данных, работающий со всеми устройствами-компаньонами Windows Hello.There is a new credential provider in Windows 10 that handles all Windows Hello companion devices.

Поставщик учетных данных для устройства-компаньона Windows Hello отвечает за запуск фоновой задачи устройства-компаньона путем активации триггера.The Windows Hello companion device credential provider is responsible for launching the companion device background task via activating a trigger. Первоначальная настройка триггера происходит при выходе компьютера из спящего режима и отображении экрана блокировки.The trigger is set the first time when the PC awakens and a lock screen is displayed. Вторая настройка происходит, когда на компьютере открывается пользовательский интерфейс входа и выбирается плитка поставщика учетных данных для устройства-компаньона Windows Hello.The second time is when the PC is entering logon UI and the Windows Hello companion device credential provider is the selected tile.

Вспомогательная библиотека приложения устройства-компаньона Windows Hello будет ожидать изменения состояния экрана блокировки и отправит событие, соответствующее фоновой задаче устройства-компаньона Windows Hello.The helper library for the Windows Hello companion device app will listen to the lock screen status change and send the event corresponding to the Windows Hello companion device background task.

При выполнении нескольких фоновых задач устройства-компаньона Windows Hello первая из этих задач, завершившая процесс проверки подлинности, разблокирует компьютер.If there are multiple Windows Hello companion device background tasks, the first background task that has finished the authentication process will unlock the PC. Служба проверки подлинности устройств-компаньонов проигнорирует остальные вызовы проверки подлинности.The companion device authentication service will ignore any remaining authentication calls.

Приложение устройства-компаньона Windows Hello управляет всеми этапами процесса на стороне устройства-компаньона Windows Hello.The experience on the Windows Hello companion device side is owned and managed by the Windows Hello companion device app. Платформа сопутствующих устройств Windows Hello не управляет этой частью процесса взаимодействия с пользователем.The Windows Hello companion device framework has no control over this part of the user experience. В частности, сопутствующий поставщик проверки подлинности информирует приложение-компаньон устройства Windows Hello (через фоновое приложение) об изменениях состояния в пользовательском интерфейсе входа (например, экран блокировки только что выводится, или пользователь только что заблокировал экран блокировки, нажав клавишу пробел), и он отвечает приложению-помощнику Windows Hello для создания такого интерфейса (например, при нажатии пользователем клавиши пробел и экран разблокировки с закреплением) , начните поиск устройства по USB.More specifically, the companion authentication provider informs the Windows Hello companion device app (via its background app) about state changes in logon UI (for example, lock screen just came down, or the user just dispelled lock screen by hitting spacebar), and it is the responsibility of the Windows Hello companion device app to build an experience around that (for example, upon user hitting spacebar and dispelling unlock screen, start looking for the device over USB).

Платформа сопутствующих устройств Windows Hello предоставит на выбор приложению устройства-компаньона Windows Hello набор (локализованных) текстовых сообщений и сообщений об ошибках.The Windows Hello companion device Framework will provide a stock of (localized) text and error messages for the Windows Hello companion device app to choose from. Эти сообщения будут отображаться поверх экрана блокировки (или в пользовательском интерфейсе входа).These will be displayed on top of lock screen (or in logon UI). Дополнительные сведения можно найти в разделе "Обработка сообщений и ошибок".See the Dealing with Messages and Errors section for more details.

Протокол аутентификацииAuthentication protocol

После запуска фоновой задачи, связанной с приложением устройства-компаньона Windows Hello, она отправляет устройству-компаньону Windows Hello запрос на выполнение проверки значения HMAC, вычисленного службой проверки подлинности устройств-компаньонов, а также запрос на расчет двух значений HMAC:Once the background task associated with a Windows Hello companion device app is trigger started, it is responsible for asking the Windows Hello companion device to validate an HMAC value computed by the Companion Authentication Service and help calculate two HMAC values:

  • Проверка значения HMAC от службы = HMAC (элемент nonce ключа проверки подлинности и службы || элемент nonce устройства || элемент nonce сеанса).Validate Service HMAC = HMAC(authentication key, service nonce || device nonce || session nonce).
  • Вычисление значения HMAC ключа устройства с элементом nonce.Calculate the HMAC of the device key with a nonce.
  • Вычисление значения HMAC ключа проверки подлинности с первым значением HMAC, объединенным с элементом nonce, который был сформирован службой проверки подлинности устройств-компаньонов.Calculate the HMAC of the authentication key with first HMAC value concatenated with a nonce generated by the Companion Authentication Service.

Служба использует второе вычисленное значение для проверки подлинности устройства и предотвращения атак с имитацией перехваченного трафика на транспортном канале.The second computed value is used by the service to authenticate the device and also prevent replay attack in transport channel.

Схема обновленного потока регистрации.

Управление жизненным цикломLifecycle management

Одна регистрация для повсеместного использованияRegister once, use everywhere

Без внутреннего сервера пользователям потребуется отдельно зарегистрировать свое устройство-компаньон Windows Hello на каждом настольном компьютере с Windows 10.Without a backend server, users must register their Windows Hello companion device with each Windows 10 desktop device separately.

Поставщик или изготовитель оборудования сопутствующего устройства может реализовать веб-службу для перемещения состояния регистрации между настольными компьютерами или мобильными устройствами с Windows 10.A companion device vendor or OEM can implement a web service to roam the registration state across user Windows 10 desktops or mobile devices. Дополнительные сведения можно найти в разделе "Служба роуминга, отзыва и фильтрации".For more details, see the Roaming, Revocation, and Filter Service section.

Управление ПИН-кодомPIN management

Перед использованием устройства-компаньона необходимо задать PIN-код на настольном компьютере с Windows 10.Before a companion device can be used, a PIN needs to be set up on Windows 10 desktop device. Это гарантия того, что в случае отказа устройства-компаньона Windows Hello у пользователя останется резервная копия.This ensures the user has a backup in case their Windows Hello companion device is not working. PIN-код скрыт от приложений — им управляет Windows.The PIN is something that Windows manages and that apps never see. Пользователь может изменить его в разделе "Параметры" > "Учетные записи" > "Параметры входа".To change it, the user navigates to Settings > Accounts > Sign-in options.

Управление и политикаManagement and policy

Пользователи могут удалить устройство-компаньон Windows Hello с настольного компьютера с Windows 10, запустив приложение устройства-компаньона Windows Hello на этом компьютере.Users can remove a Windows Hello companion device from a Windows 10 desktops by running the Windows Hello companion device app on that desktop device.

У предприятий есть два способа управления платформой сопутствующих устройств Windows Hello:Enterprises have two options for controlling the Windows Hello companion device framework:

  • включение или отключение этой функции;Turn the feature on or off
  • определение списка разрешений устройств-компаньонов Windows Hello, которым разрешено использовать хранилище приложений для Windows.Define the whitelist of Windows Hello companion devices allowed using Windows app locker

Платформа сопутствующих устройств Windows Hello не предоставляет централизованного способа ведения учета доступных устройств-компаньонов или метода расширенной фильтрации разрешенных экземпляров устройств-компаньонов Windows Hello определенного типа (например, разрешено использование только устройств-компаньонов с серийным номером от X до Y).The Windows Hello companion device framework does not support any centralized way to keep inventory of available companion devices, or a method to further filter which instances of a Windows Hello companion device type is allowed (for example, only a companion device with a serial number between X and Y are allowed). Однако разработчики приложений могут создать службу с поддержкой этих функций.Apps developers can, however, build a service to provide such functionality. Дополнительные сведения можно найти в разделе "Служба роуминга, отзыва и фильтрации".For more details, see the Roaming, Revocation, and Filter Service section.

Запрет доступаRevocation

Платформа сопутствующих устройств Windows Hello не поддерживает удаление устройства-компаньона с конкретного настольного компьютера с Windows 10 в удаленном режиме.The Windows Hello companion device framework does not support removing a companion device from a specific Windows 10 desktop device remotely. Вместо этого пользователи могут удалить устройство-компаньон Windows Hello через приложение устройства-компаньона Windows Hello на соответствующем настольном компьютере с Windows 10.Instead, users can remove the Windows Hello companion device via the Windows Hello companion device app running on that Windows 10 desktop.

Однако поставщики сопутствующих устройств могут создать службу с поддержкой функции удаленного отзыва.Companion device vendors, however, can build a service to provide remote revocation functionality. Дополнительные сведения можно найти в разделе "Служба роуминга, отзыва и фильтрации".For more details, see Roaming, Revocation, and Filter Service section.

Службы роуминга и фильтрацииRoaming and filter services

Поставщики сопутствующих устройств могут реализовать веб-службу для использования в следующих сценариях:Companion device vendors can implement a web service that can be used for the following scenarios:

  • Служба фильтрации для предприятия: предприятие может ограничить набор устройств-компаньонов Windows Hello, которым разрешено работать в корпоративной среде, до нескольких устройств от определенного поставщика.A filter service for enterprise: An enterprise can limit the set of Windows Hello companion devices that can work in their environment to a select few from a specific vendor. Например, компания Contoso может заказать 10 000 сопутствующих устройств модели Y от поставщика X и разрешить только этим устройствам работать на домене Contoso (запрет также распространяется на все остальные модели устройств от поставщика X).For example, the company Contoso could order 10,000 Model Y companion devices from Vendor X and ensure only those devices will work in the Contoso domain (and not any other device model from Vendor X).
  • Данные инвентаризации. Предприятие может определить список существующих сопутствующих устройств, используемых в корпоративной среде.Inventory: An enterprise can determine the list of existing companion devices used in an enterprise environment.
  • Отзыв в реальном времени. Если сотрудник сообщит об утере или краже своего сопутствующего устройства, это устройство можно отозвать с помощью веб-службы.Real time revocation: If an employee reports that his companion device is lost or stolen, the web service can be used to revoke that device.
  • Роуминг: пользователю нужно лишь однажды пройти процедуру регистрации устройства, после чего оно будет работать со всеми настольными компьютерами и мобильными устройствами с Windows 10 этого пользователя.Roaming: A user only has to register his companion device once and it works on all of his Windows 10 desktops and Mobile.

Для реализации этих функций необходимо, чтобы приложение устройства-компаньона Windows Hello сверялось с веб-службой при регистрации и использовании.Implementing these features requires the Windows Hello companion device app to check with the web service at registration and usage time. Приложение устройства-компаньона Windows Hello может выполнять оптимизацию для сценариев с использованием кэшированных данных о входе, например запрашивать сверку с веб-службой только один раз в день (при этом время отзыва может увеличиться до одного дня).The Windows Hello companion device app can optimize for cached logon scenarios like requiring checking with web service only once a day (at the cost of extending the revocation time to up to one day).

Модель API платформы сопутствующих устройств Windows HelloWindows Hello companion device framework API model

ОбзорOverview

Приложение устройства-компаньона Windows Hello должно состоять из двух компонентов: внешнего приложения с пользовательским интерфейсом для регистрации устройства и ее отмены, а также фоновой задачи для выполнения проверки подлинности.A Windows Hello companion device app should contain two components: a foregroud app with UI responsible for registering and unregistering the device, and a background task that handles authentication.

Общий процесс API выглядит следующим образом:The overall API flow is as follows:

  1. Регистрация устройства-компаньона Windows HelloRegister the Windows Hello companion device
    • убедитесь, что устройство находится поблизости и отправьте запрос для определения его доступности (если необходимо);Make sure the device is nearby and query its capability (if required)
    • создайте два ключа HMAC (на стороне устройства-компаньона или его приложения);Generate two HMAC keys (either on the companion device side or the app side)
    • вызовите метод RequestStartRegisteringDeviceAsync;Call RequestStartRegisteringDeviceAsync
    • вызовите метод FinishRegisteringDeviceAsync;Call FinishRegisteringDeviceAsync
    • убедитесь, что приложение устройства-компаньона Windows Hello сохранило ключи HMAC (если такая функция поддерживается) и удалило их копии.Make sure Windows Hello companion device app stores HMAC keys (if supported) and Windows Hello companion device app discards its copies
  2. Регистрация фоновой задачиRegister your background task
  3. Ожидание нужного события фоновой задачиWait for the right event in the background task
    • WaitingForUserConfirmation: дождитесь возникновения этого события, если для запуска процесса проверки подлинности пользователь должен выполнить действие или жест на стороне устройства-компаньона Windows Hello;WaitingForUserConfirmation: Wait for this event if the user action/gesture on the Windows Hello companion device side is required to start authentication flow
    • Коллектингкредентиал. Дождитесь этого события, если устройство-компаньон Windows Hello использует действие или жест пользователя на стороне ПК для запуска потока проверки подлинности (например, нажатием клавиши пробел).CollectingCredential: Wait for this event if the Windows Hello companion device relies on user action/gesture on the PC side to start authentication flow (for example, by hitting spacebar)
    • другой триггер, например смарт-карта: отправьте запрос текущего состояния проверки подлинности для вызова нужных API.Other trigger, like a smartcard: Make sure to query for current authentication state to call the right APIs.
  4. Уведомление пользователя об ошибках или дальнейших действиях путем вызова ShowNotificationMessageAsync.Keep user informed about error messages or required next steps by calling ShowNotificationMessageAsync. Этот API следует вызывать только после получения сигнала о намеренииOnly call this API once an intent signal is collected
  5. UnlockUnlock
    • убедитесь, что сигналы намерения и присутствия пользователя получены;Make sure intent and user presence signals were collected
    • вызовите StartAuthenticationAsync;Call StartAuthenticationAsync
    • свяжитесь с устройством-компаньоном, чтобы выполнить необходимые действия HMAC;Communicate with the companion device to perform required HMAC operations
    • вызовите метод FinishAuthenticationAsync.Call FinishAuthenticationAsync
  6. Отмена регистрации устройства-компаньона Windows Hello по запросу пользователя (например, при утере устройства-компаньона)Un-register a Windows Hello companion device when the user requests it (for example, if they've lost their companion device)
    • перечислите устройство-компаньон Windows Hello для выполнившего вход пользователя с помощью FindAllRegisteredDeviceInfoAsync;Enumerate the Windows Hello companion device for logged in user via FindAllRegisteredDeviceInfoAsync
    • отмените его регистрацию с помощью UnregisterDeviceAsync.Un-register it using UnregisterDeviceAsync

Регистрация и ее отменаRegistration and de-registration

Для осуществления регистрации требуется выполнить два вызова API в адрес службы проверки подлинности устройств-компаньонов: RequestStartRegisteringDeviceAsync и FinishRegisteringDeviceAsync.Registration requires two API calls to the Companion Authentication Service: RequestStartRegisteringDeviceAsync and FinishRegisteringDeviceAsync.

Перед выполнением этих вызовов приложение устройства-компаньона Windows Hello должно убедиться в доступности устройства-компаньона Windows Hello.Before any of these calls are made, the Windows Hello companion device app must make sure that the Windows Hello companion device is available. Если устройство-компаньон Windows Hello отвечает за создание ключей HMAC (ключи устройства и проверки подлинности), его приложение должно также запросить у устройства их создание перед совершением любого из указанных выше вызовов.If the Windows Hello companion device is responsible for generating HMAC keys (authentication and device keys), then the Windows Hello companion device app should also ask the companion device to generate them before making any of the above two calls. Если приложение устройства-компаньона Windows Hello отвечает за создание ключей HMAC, оно должно создать их перед выполнением указанных выше вызовов.If the Windows Hello companion device app is responsible for generating HMAC keys, then it should do so before calling the above two calls.

Кроме того, в рамках вызова первого API (RequestStartRegisteringDeviceAsync) приложение устройства-компаньона Windows Hello должно определить возможности устройства (например, поддерживает ли оно безопасное хранилище для ключей HMAC) и подготовиться к его передаче в составе вызова API.Additionally, as part of first API call (RequestStartRegisteringDeviceAsync), the Windows Hello companion device app must decide on device capability and be prepared to pass it as part of the API call; for example, whether the Windows Hello companion device supports secure storage for HMAC keys. Если одно и то же приложение устройства-компаньона Windows Hello используется для управления несколькими версиями одного и того же устройства-компаньона, а возможности устройства изменяются (и для их определения требуется отправка запроса устройству), рекомендуется отправить эти запросы до вызова первого API.If the same Windows Hello companion device app is used to manage multiple versions of the same companion device and those capabilities change (and requires a device query to decide), we recommend this queries occurs before first API call is made.

Первый API (RequestStartRegisteringDeviceAsync) вернет дескриптор, используемый вторым API (FinishRegisteringDeviceAsync).The first API (RequestStartRegisteringDeviceAsync) will return a handle used by the second API (FinishRegisteringDeviceAsync). Первый вызов для регистрации запустит запрос на PIN-код, чтобы проверить присутствие пользователя.The first call for registration will launch the PIN prompt to make sure user is present. Если PIN-код не настроен, вызов завершится с ошибкой.If no PIN is set up, this call will fail. Приложение устройства-компаньона Windows Hello может также отправить запрос на проверку наличия PIN-кода через вызов KeyCredentialManager.IsSupportedAsync.The Windows Hello companion device app can query whether PIN is set up or not via KeyCredentialManager.IsSupportedAsync call as well. Вызов RequestStartRegisteringDeviceAsync также может завершиться с ошибкой, если использование устройств-компаньонов Windows Hello отключено в рамках политики.RequestStartRegisteringDeviceAsync call can also fail if policy has disabled the usage of the Windows Hello companion device.

Результат первого вызова возвращается через перечисление SecondaryAuthenticationFactorRegistrationStatus:The result of first call is returned via SecondaryAuthenticationFactorRegistrationStatus enum:

{
    Failed = 0,         // Something went wrong in the underlying components
    Started,            // First call succeeded
    CanceledByUser,     // User cancelled PIN prompt
    PinSetupRequired,   // PIN is not set up
    DisabledByPolicy,   // Companion device framework or this app is disabled
}

Второй вызов (FinishRegisteringDeviceAsync) завершает регистрацию.The second call (FinishRegisteringDeviceAsync) finishes the registration. В рамках процесса регистрации приложение устройства-компаньона Windows Hello может хранить данные конфигурации сопутствующего устройства в службе проверки подлинности устройств-компаньонов.As part of registration process, the Windows Hello companion device app can store companion device configuration data with Companion Authentication Service. Размер этих данных не может превышать 4 КБ.There is a 4K size limit for this data. Эти данные будут доступны приложению устройства-компаньона Windows Hello при проверке подлинности.This data will be available to the Windows Hello companion device app at authentication time. Помимо прочего, эти данные можно использовать для подключения к устройству-компаньону Windows Hello, например по MAC-адресу. Также данные конфигурации можно использовать, если в устройстве-компаньоне Windows Hello нет хранилища и ему требуется хранить данные на компьютере.This data can be used, as an example, to connect to the Windows Hello companion device like a MAC address, or if the Windows Hello companion device does not have storage and companion device wants to use PC for storage, then configuration data can be used. Обратите внимание, что любые конфиденциальные данные, хранящиеся в составе данных конфигурации, должны быть зашифрованы с помощью ключа, известного только устройству-компаньону Windows Hello.Note that any sensitive data stored as part of configuration data must be encrypted with a key that only the Windows Hello companion device knows. Также с учетом того, что данные конфигурации хранятся в службе Windows, они доступны приложению устройства-компаньона Windows Hello во всех профилях пользователя.Also, given that configuration data is stored by a Windows service, it is available to the Windows Hello companion device app across user profiles.

Приложение устройства-компаньона Windows Hello может вызвать AbortRegisteringDeviceAsync для отмены регистрации и передачи кода ошибки.The Windows Hello companion device app can call AbortRegisteringDeviceAsync to cancel the registration and pass in an error code. Служба проверки подлинности сопутствующих устройств занесет ошибку в журнал данных телеметрии.The Companion Authentication Service will log the error in the telemetry data. Хорошим примером для этого вызова является то, что что-то пошло не так с помощником по Windows Hello, и ему не удалось завершить регистрацию (например, не удается сохранить ключи HMAC или BT-подключение было потеряно).A good example for this call would be when something went wrong with the Windows Hello companion device and it could not finish registration (for example, it cannot store HMAC keys or BT connection was lost).

Приложение для устройства с поддержкой Windows Hello должно предоставить пользователю возможность отменить регистрацию своего устройства-компаньона Windows Hello на рабочем столе Windows 10 (например, если они потеряют сопутствующее устройство или приобрели более новую версию).The Windows Hello companion device app must provide an option for the user to de-register their Windows Hello companion device from their Windows 10 desktop (for example, if they lost their companion device or bought a newer version). Если пользователь выбирает этот вариант, приложение устройства-компаньона Windows Hello должно вызвать UnregisterDeviceAsync.When the user selects that option, then the Windows Hello companion device app must call UnregisterDeviceAsync. Этот вызов от приложения устройства-компаньона Windows Hello приведет к тому, что служба проверки подлинности устройств-компаньонов удалит все данные (включая ключи HMAC), связанные с определенным кодом устройства и идентификатором приложения, совершившего вызов на стороне компьютера.This call by the Windows Hello companion device app will trigger the companion device authentication service to delete all data (including HMAC keys) corresponding to the specific device Id and AppId of the caller app from PC side. Этот API не пытается удалить ключи HMAC на стороне устройства-компаньона Windows Hello или его приложения.This API call does not attempt to delete HMAC keys from either the Windows Hello companion device app or companion device side. Их удаляет приложение устройства-компаньона Windows Hello.That is left for the Windows Hello companion device app to implement.

Приложение устройства-компаньона Windows Hello отвечает за отображение сообщений об ошибках в ходе регистрации и ее отмены.The Windows Hello companion device app is responsible for showing any error messages that happen in registration and de-registration phase.

using System;
using Windows.Security.Authentication.Identity.Provider;
using Windows.Storage.Streams;
using Windows.Security.Cryptography;
using Windows.UI.Popups;

namespace SecondaryAuthFactorSample
{
    public class DeviceRegistration
    {

        public void async OnRegisterButtonClick()
        {
            //
            // Pseudo function, the deviceId should be retrieved by the application from the device
            //
            string deviceId = await ReadSerialNumberFromDevice();

            IBuffer deviceKey = CryptographicBuffer.GenerateRandom(256/8);
            IBuffer mutualAuthenticationKey = CryptographicBuffer.GenerateRandom(256/8);

            SecondaryAuthenticationFactorRegistration registrationResult =
                await SecondaryAuthenticationFactorRegistration.RequestStartRegisteringDeviceAsync(
                    deviceId,  // deviceId: max 40 wide characters. For example, serial number of the device
                    SecondaryAuthenticationFactorDeviceCapabilities.SecureStorage |
                        SecondaryAuthenticationFactorDeviceCapabilities.HMacSha256 |
                        SecondaryAuthenticationFactorDeviceCapabilities.StoreKeys,
                    "My test device 1", // deviceFriendlyName: max 64 wide characters. For example: John's card
                    "SAMPLE-001", // deviceModelNumber: max 32 wide characters. The app should read the model number from device.
                    deviceKey,
                    mutualAuthenticationKey);

            switch(registerResult.Status)
            {
            case SecondaryAuthenticationFactorRegistrationStatus.Started:
                //
                // Pseudo function:
                // The app needs to retrieve the value from device and set into opaqueBlob
                //
                IBuffer deviceConfigData = ReadConfigurationDataFromDevice();

                if (deviceConfigData != null)
                {
                    await registrationResult.Registration.FinishRegisteringDeviceAsync(deviceConfigData); //config data limited to 4096 bytes
                    MessageDialog dialog = new MessageDialog("The device is registered correctly.");
                    await dialog.ShowAsync();
                }
                else
                {
                    await registrationResult.Registration.AbortRegisteringDeviceAsync("Failed to connect to the device");
                    MessageDialog dialog = new MessageDialog("Failed to connect to the device.");
                    await dialog.ShowAsync();
                }
                break;

            case SecondaryAuthenticationFactorRegistrationStatus.CanceledByUser:
                MessageDialog dialog = new MessageDialog("You didn't enter your PIN.");
                await dialog.ShowAsync();
                break;

            case SecondaryAuthenticationFactorRegistrationStatus.PinSetupRequired:
                MessageDialog dialog = new MessageDialog("Please setup PIN in settings.");
                await dialog.ShowAsync();
                break;

            case SecondaryAuthenticationFactorRegistrationStatus.DisabledByPolicy:
                MessageDialog dialog = new MessageDialog("Your enterprise prevents using this device to sign in.");
                await dialog.ShowAsync();
                break;
            }
        }

        public void async UpdateDeviceList()
        {
            IReadOnlyList<SecondaryAuthenticationFactorInfo> deviceInfoList =
                await SecondaryAuthenticationFactorRegistration.FindAllRegisteredDeviceInfoAsync(
                    SecondaryAuthenticationFactorDeviceFindScope.User);

            if (deviceInfoList.Count > 0)
            {
                foreach (SecondaryAuthenticationFactorInfo deviceInfo in deviceInfoList)
                {
                    //
                    // Add deviceInfo.FriendlyName and deviceInfo.DeviceId into a combo box
                    //
                }
            }
        }

        public void async OnUnregisterButtonClick()
        {
            string deviceId;
            //
            // Read the deviceId from the selected item in the combo box
            //
            await SecondaryAuthenticationFactorRegistration.UnregisterDeviceAsync(deviceId);
        }
    }
}

АутентификацияAuthentication

Для проверки подлинности требуется совершить два вызова API в адрес службы проверки подлинности сопутствующих устройств: StartAuthenticationAsync и FinishAuthencationAsync.Authentication requires two API calls to the Companion Authentication Service: StartAuthenticationAsync and FinishAuthencationAsync.

Первый API инициирования возвращает дескриптор, используемый вторым API.The first initiation API will return a handle used by the second API. Помимо прочего, первый вызов возвращает код nonce, для которого (после объединения с другими элементами) необходимо создать код HMAC в соответствии с кодом устройства, хранящимся на устройстве-компаньоне Windows Hello.The first call returns, among other things, a nonce that – once concatenated with other things - needs to be HMAC'ed with the device key stored on the Windows Hello companion device. Второй вызов возвращает результаты создания HMAC на основе ключа устройства и может привести к успешной проверке подлинности (то есть пользователь увидит свой рабочий стол).The second call returns the results of HMAC with device key and can potentially end in successful authentication (i.e., the user will see their desktop).

Первый API инициации (StartAuthenticationAsync) может завершиться с ошибкой, если после первоначальной регистрации это устройство-компаньон Windows Hello было отключено политикой.The first initiation API (StartAuthenticationAsync) can fail if policy has disabled that Windows Hello companion device after initial registration. Он также может завершиться с ошибкой, если вызов API был выполнен за пределами состояний WaitingForUserConfirmation или CollectingCredential (об этом подробнее рассказывается далее в этом разделе).It can also fail if the API call was made outside WaitingForUserConfirmation or CollectingCredential states (more on this later in this section). К тому же исходу может привести совершение этого вызова через приложение незарегистрированного сопутствующего устройства.It can also fail if an unregistered companion device app calls it. Перечисление SecondaryAuthenticationFactorAuthenticationStatus указывает все возможные результаты:SecondaryAuthenticationFactorAuthenticationStatus Enum summarizes the possible outcomes:

{
    Failed = 0,                     // Something went wrong in the underlying components
    Started,
    UnknownDevice,                  // Companion device app is not registered with framework
    DisabledByPolicy,               // Policy disabled this device after registration
    InvalidAuthenticationStage,     // Companion device framework is not currently accepting
                                    // incoming authentication requests
}

Вызов второго API (FinishAuthencationAsync) может завершиться с ошибкой, если срок действия кода nonce, предоставленного после первого вызова, истек (20 секунд).The second API call (FinishAuthencationAsync) can fail if the nonce that was provided in the first call is expired (20 seconds). Перечисление SecondaryAuthenticationFactorFinishAuthenticationStatus указывает все возможные результаты:SecondaryAuthenticationFactorFinishAuthenticationStatus enum captures possible outcomes.

{
    Failed = 0,     // Something went wrong in the underlying components
    Completed,      // Success
    NonceExpired,   // Nonce is expired
}

Время выполнения этих двух вызовов API (StartAuthenticationAsync и FinishAuthencationAsync) должно соответствовать получению устройством-компаньоном Windows Hello сигналов намерения, присутствия пользователя и уточнения (дополнительные сведения см. в разделе "Сигналы пользователя".The timing of two API calls (StartAuthenticationAsync and FinishAuthencationAsync) needs to align with how the Windows Hello companion device collects intent, user presence, and disambiguation signals (see User Signals for more details). Например, второй вызов следует отправлять только после получения сигнала намерения.For example, the second call must not be submitted until intent signal is available. Другими словами, компьютер не должен разблокироваться, если пользователь не выразил соответствующее намерение.In other words, the PC should not unlock if the user has not expressed intent for it. Пояснение. Предположим, что для разблокировки компьютера устройство должно находиться в радиусе действия подключения Bluetooth. В этом случае явный сигнал намерения должен отправляться иным образом, иначе компьютер разблокируется, если пользователь пройдет мимо него по пути на кухню.To make this more clear, assume that Bluetooth proximity is used for PC unlock, then an explicit intent signal must be collected, otherwise, as soon as user walks by his PC on the way to kitchen, the PC will unlock. Кроме того, срок действия кода nonce, возвращенного после первого вызова, ограничен 20 секундами и истечет по прошествии этого времени.Also, the nonce returned from the first call is time bound (20 seconds) and will expire after certain period. В результате первый вызов следует выполнить только в том случае, если приложение Windows Hello Companion имеет хорошее представление о присутствии сопутствующего устройства, например, если устройство было вставлено в USB-порт или прикосновено к модулю NFC.As a result, the first call only should be made when the Windows Hello companion device app has good indication of companion device presence, for example, the companion device is inserted into USB port, or tapped on NFC reader. При использовании Bluetooth необходимо проявлять осторожность, чтобы не разрядить аккумулятор компьютера и не помешать другим процессам, использующим Bluetooth, в момент проверки присутствия устройства-компаньона Windows Hello.With Bluetooth, care must be taken to avoid affecting battery on PC side or affecting other Bluetooth activities going on at that point when checking for Windows Hello companion device presence. Кроме того, если необходимо предоставить сигнал о присутствии пользователя (например, введя ПИН-код), рекомендуется выполнить первый вызов проверки подлинности только после сбора этого сигнала.Also, if a user presence signal needs to be provided (for example, by typing in PIN), it is recommended that the first authentication call is only made after that signal is collected.

Платформа сопутствующих устройств Windows Hello помогает приложению устройства-компаньона Windows Hello принять обоснованное решение о времени выполнения двух указанных вызовов, предоставляя точные данные о расположении пользователя в процессе проверки подлинности.The Windows Hello companion device framework helps the Windows Hello companion device app to make informed decision on when to make above two calls by providing a complete picture of where user is in authentication flow. Платформа сопутствующих устройств Windows Hello предоставляет эту возможность, отправляя фоновой задаче приложения уведомление об изменении состояния блокировки.Windows Hello companion device framework provides this functionality by providing lock state change notification to app background task.

процесс на сопутствующем устройстве

Ниже указано подробное описание каждого из этих состояний:Details of each of these states are as follows:

СостояниеState ОписаниеDescription
WaitingForUserConfirmationWaitingForUserConfirmation Это событие уведомления об изменении состояния срабатывает, когда появляется экран блокировки (например, пользователь нажал на Windows + L).This state change notification event is fired when the lock screen comes down (for example, user pressed Windows + L). Не рекомендуется запрашивать сообщения об ошибках в случае возникновения проблем с поиском устройства при этом состоянии.We recommend not to request any error messages relating to having difficulty finding a device in this state. Как правило, рекомендуется отображать сообщения только при наличии сигнала намерения.In general, we recommend to only show messages when intent signal is available. Приложение устройства "помощник Windows Hello" должно сделать первый вызов API для проверки подлинности в этом состоянии, если сопутствующее устройство собирает сигнал намерения (например, коснуться NFC-сканера, нажать кнопку на сопровождающем устройстве или специальный жест, например аплодисменты), и фоновая задача приложения устройства Windows Hello получит указание от устройства-компаньона, на котором обнаружен сигнал намерения.The Windows Hello companion device app should make the first API call for authentication in this state if the companion device collects the intent signal (for example, tapping on NFC reader, press of a button on the companion device or a specific gesture, like clapping), and the Windows Hello companion device app background task receives indication from the companion device that intent signal was detected. В противном случае, если при запуске процесса проверки подлинности приложению устройства-компаньона Windows Hello требуется компьютер (пользователю необходимо провести пальцем вверх по экрану блокировки или нажать клавишу "ПРОБЕЛ"), приложение устройства-компаньона Windows Hello должно дождаться возникновения следующего состояния (CollectingCredential).Otherwise, if the Windows Hello companion device app relies on the PC to start authentication flow (by having user swipe up the unlock screen or hitting space bar), then the Windows Hello companion device app needs to wait for the next state (CollectingCredential).
CollectingCredentialCollectingCredential Это событие уведомления об изменении состояния активируется, если пользователь открывает крышку ноутбука, нажимает любую клавишу на клавиатуре или проводит пальцем вверх по экрану блокировки.This state change notification event is fired when the user either opens their laptop lid, hits any key on their keyboard, or swipes up to the unlock screen. Если устройство-компаньон Windows Hello использует описанные выше действия для начала сбора сигнала намерения, то приложение-помощник Windows Hello должно начать сбор данных (например, через всплывающее устройство на вспомогательном устройстве с вопросом, требуется ли пользователю разблокировать компьютер).If the Windows Hello companion device relies on the above actions to start collecting the intent signal, then the Windows Hello companion device app should start collecting it (for example, via a pop up on the companion device asking whether user wants to unlock the PC). Это подходящий момент для отображения сообщений об ошибках, если приложению устройства-компаньона Windows Hello требуется, чтобы пользователь отправил сигнал своего присутствия с устройства-компаньона (например, путем ввода PIN-кода на этом устройстве).This would be a good time to provide error cases if the Windows Hello companion device app needs the user to provide a user presence signal on the companion device (like typing in PIN on the Windows Hello companion device).
SuspendingAuthenticationSuspendingAuthentication Если приложение устройства-компаньона Windows Hello получает это состояние, значит служба проверки подлинности устройств-компаньонов перестала принимать запросы на проверку подлинности.When the Windows Hello companion device app receives this state, it means that the Companion Authentication Service has stopped accepting authentication requests.
CredentialCollectedCredentialCollected Это состояние означает, что другое приложение устройства-компаньона Windows Hello вызвало второй API, и служба проверки подлинности устройств-компаньонов проверяет отправленные данные.This means that another Windows Hello companion device app has called the second API and that the Companion Authentication Service is verifying what was submitted. На этом этапе служба проверки подлинности устройств-компаньонов не принимает другие запросы на проверку подлинности, если только проверка текущего запроса не завершится с ошибкой.At this point, the Companion Authentication Service is not accepting any other authentication requests unless the currently submitted one does not pass verification. Приложение устройства-компаньона Windows Hello должно оставаться на связи, пока не будет достигнуто следующее состояние.The Windows Hello companion device app should stay tuned until next state is reached.
CredentialAuthenticatedCredentialAuthenticated Это состояние означает, что отправленные учетные данные подошли.This means that the submitted credential worked. Состояние credentialAuthenticated содержит код устройства-компаньона Windows Hello, успешно прошедшего проверку.The credentialAuthenticated has the device ID of the Windows Hello companion device that succeeded. Приложение устройства-компаньона Windows Hello обязательно должно проверить этот код и подтвердить, что он принадлежит связанному с ним устройству.The Windows Hello companion device app should make sure to check on that to see if its associated device was the winner. В противном случае приложение устройства-компаньона Windows Hello не должно показывать процессы, следующие за проверкой подлинности (например, сообщение об успешной проверке на устройстве-компаньоне или, возможно, вибрация этого устройства).If not, then the Windows Hello companion device app should avoid showing any post authentication flows (like success message on the companion device or perhaps a vibration on that device). Обратите внимание, что если отправленные учетные данные не подошли, состояние изменится на CollectingCredential.Note that if the submitted credential did not work, the state will change to CollectingCredential state.
StoppingAuthenticationStoppingAuthentication Проверка подлинности пройдена успешно и пользователь увидел рабочий стол.Authentication succeeded and user saw the desktop. Пора завершить фоновую задачу.Time to kill your background task. Прежде чем выходить из фоновой задачи, необходимо явно отменить регистрацию обработчика StageEvent.Before exiting the backround task, explicitly unregister the StageEvent handler. Это поможет быстро выйти из фоновой задачи.This will help the background task exit quickly.

Приложения устройств-компаньонов Windows Hello должны вызывать первые два API проверки подлинности только при первых двух состояниях.Windows Hello companion device apps should only call the two authentication APIs in the first two states. Приложения устройств-компаньонов Windows Hello должны проверять, в какой ситуации активируется это событие.Windows Hello companion device apps should check for what scenario this event is being fired. Есть два варианта: разблокировка или следующие за ней процессы.There are two possibilities: unlock or post unlock. На текущий момент поддерживается только разблокировка.Currently, only unlock is supported. В следующих выпусках может быть реализована поддержка сценариев после разблокировки.In upcoming releases, post unlock scenarios may be supported. Перечисление SecondaryAuthenticationFactorAuthenticationScenario включает оба этих варианта:The SecondaryAuthenticationFactorAuthenticationScenario enum captures these two options:

{
    SignIn = 0,         // Running under lock screen mode
    CredentialPrompt,   // Running post unlock
}

Пример полного кода:Complete code sample:

using System;
using Windows.Security.Authentication.Identity.Provider;
using Windows.Storage.Streams;
using Windows.Security.Cryptography;
using System.Threading;
using Windows.ApplicationModel.Background;

namespace SecondaryAuthFactorSample
{
    public sealed class AuthenticationTask : IBackgroundTask
    {
        private string _deviceId;
        private static AutoResetEvent _exitTaskEvent = new AutoResetEvent(false);
        private static IBackgroundTaskInstance _taskInstance;
        private BackgroundTaskDeferral _deferral;

        private void Authenticate()
        {
            int retryCount = 0;

            while (retryCount < 3)
            {
                //
                // Pseudo code, the svcAuthNonce should be passed to device or generated from device
                //
                IBuffer svcAuthNonce = CryptographicBuffer.GenerateRandom(256/8);

                SecondaryAuthenticationFactorAuthenticationResult authResult = await
                    SecondaryAuthenticationFactorAuthentication.StartAuthenticationAsync(
                        _deviceId,
                        svcAuthNonce);
                if (authResult.Status != SecondaryAuthenticationFactorAuthenticationStatus.Started)
                {
                    SecondaryAuthenticationFactorAuthenticationMessage message;
                    switch (authResult.Status)
                    {
                        case SecondaryAuthenticationFactorAuthenticationStatus.DisabledByPolicy:
                            message = SecondaryAuthenticationFactorAuthenticationMessage.DisabledByPolicy;
                            break;
                        case SecondaryAuthenticationFactorAuthenticationStatus.InvalidAuthenticationStage:
                            // The task might need to wait for a SecondaryAuthenticationFactorAuthenticationStageChangedEvent
                            break;
                        default:
                            return;
                    }

                    // Show error message. Limited to 512 characters wide
                    await SecondaryAuthenticationFactorAuthentication.ShowNotificationMessageAsync(null, message);
                    return;
                }

                //
                // Pseudo function:
                // The device calculates and returns sessionHmac and deviceHmac
                //
                await GetHmacsFromDevice(
                    authResult.Authentication.ServiceAuthenticationHmac,
                    authResult.Authentication.DeviceNonce,
                    authResult.Authentication.SessionNonce,
                    out deviceHmac,
                    out sessionHmac);
                if (sessionHmac == null ||
                    deviceHmac == null)
                {
                    await authResult.Authentication.AbortAuthenticationAsync(
                        "Failed to read data from device");
                    return;
                }

                SecondaryAuthenticationFactorFinishAuthenticationStatus status =
                    await authResult.Authentication.FinishAuthencationAsync(deviceHmac, sessionHmac);
                if (status == SecondaryAuthenticationFactorFinishAuthenticationStatus.NonceExpired)
                {
                    retryCount++;
                    continue;
                }
                else if (status == SecondaryAuthenticationFactorFinishAuthenticationStatus.Completed)
                {
                    // The credential data is collected and ready for unlock
                    return;
                }
            }
        }

        public void OnAuthenticationStageChanged(
            object sender,
            SecondaryAuthenticationFactorAuthenticationStageChangedEventArgs args)
        {
            // The application should check the args.StageInfo.Stage to determine what to do in next. Note that args.StageInfo.Scenario will have the scenario information (SignIn vs CredentialPrompt).

            switch(args.StageInfo.Stage)
            {
            case SecondaryAuthenticationFactorAuthenticationStage.WaitingForUserConfirmation:
                // Show welcome message
                await SecondaryAuthenticationFactorAuthentication.ShowNotificationMessageAsync(
                    null,
                    SecondaryAuthenticationFactorAuthenticationMessage.WelcomeMessageSwipeUp);
                break;

            case SecondaryAuthenticationFactorAuthenticationStage.CollectingCredential:
                // Authenticate device
                Authenticate();
                break;

            case SecondaryAuthenticationFactorAuthenticationStage.CredentialAuthenticated:
                if (args.StageInfo.DeviceId = _deviceId)
                {
                    // Show notification on device about PC unlock
                }
                break;

            case SecondaryAuthenticationFactorAuthenticationStage.StoppingAuthentication:
                // Quit from background task
                _exitTaskEvent.Set();
                break;
            }

            Debug.WriteLine("Authentication Stage = " + args.StageInfo.AuthenticationStage.ToString());
        }

        //
        // The Run method is the entry point of a background task.
        //
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            _taskInstance = taskInstance;
            _deferral = taskInstance.GetDeferral();

            // Register canceled event for this task
            taskInstance.Canceled += TaskInstanceCanceled;

            // Find all device registred by this application
            IReadOnlyList<SecondaryAuthenticationFactorInfo> deviceInfoList =
                await SecondaryAuthenticationFactorRegistration.FindAllRegisteredDeviceInfoAsync(
                    SecondaryAuthenticationFactorDeviceFindScope.AllUsers);

            if (deviceInfoList.Count == 0)
            {
                // Quit the task silently
                return;
            }
            _deviceId = deviceInfoList[0].DeviceId;
            Debug.WriteLine("Use first device '" + _deviceId + "' in the list to signin");

            // Register AuthenticationStageChanged event
            SecondaryAuthenticationFactorRegistration.AuthenticationStageChanged += OnAuthenticationStageChanged;

            // Wait the task exit event
            _exitTaskEvent.WaitOne();

            _deferral.Complete();
        }

        void TaskInstanceCanceled(IBackgroundTaskInstance sender, BackgroundTaskCancellationReason reason)
        {
            _exitTaskEvent.Set();
        }
    }
}

Регистрация фоновой задачиRegister a background task

При регистрации первого устройства-компаньона Windows Hello приложение сопутствующего устройства должно также зарегистрировать его компонент фоновой задачи, обеспечивающий передачу сведений о проверке подлинности между устройством и службой проверки подлинности устройств-компаньонов.When the Windows Hello companion device app registers the first companion device, it should also register its background task component which will pass authentication information between device and companion device authentication service.

using System;
using Windows.Security.Authentication.Identity.Provider;
using Windows.Storage.Streams;
using Windows.ApplicationModel.Background;

namespace SecondaryAuthFactorSample
{
    public class BackgroundTaskManager
    {
        // Register background task
        public static async Task<IBackgroundTaskRegistration> GetOrRegisterBackgroundTaskAsync(
            string bgTaskName,
            string taskEntryPoint)
        {
            // Check if there's an existing background task already registered
            var bgTask = (from t in BackgroundTaskRegistration.AllTasks
                          where t.Value.Name.Equals(bgTaskName)
                          select t.Value).SingleOrDefault();
            if (bgTask == null)
            {
                BackgroundAccessStatus status =
                    BackgroundExecutionManager.RequestAccessAsync().AsTask().GetAwaiter().GetResult();

                if (status == BackgroundAccessStatus.Denied)
                {
                    Debug.WriteLine("Background Execution is denied.");
                    return null;
                }

                var taskBuilder = new BackgroundTaskBuilder();
                taskBuilder.Name = bgTaskName;
                taskBuilder.TaskEntryPoint = taskEntryPoint;
                taskBuilder.SetTrigger(new SecondaryAuthenticationFactorAuthenticationTrigger());
                bgTask = taskBuilder.Register();
                // Background task is registered
            }

            bgTask.Completed += BgTask_Completed;
            bgTask.Progress += BgTask_Progress;

            return bgTask;
        }
    }
}

Ошибки и сообщенияErrors and messages

Платформа сопутствующих устройств Windows Hello отвечает за оповещение пользователя об успешном входе или сбое при входе.The Windows Hello companion device framework is responsible for providing feedback to the user about success or failure of signing in. Платформа сопутствующих устройств Windows Hello предоставит на выбор приложению устройства-компаньона Windows Hello набор (локализованных) текстовых сообщений и сообщений об ошибках.The Windows Hello companion device framework will provide a stock of (localized) text and error messages for the Windows Hello companion device app to choose from. Они отображаются в пользовательском интерфейсе входа.These will be displayed in the logon UI.

ошибка устройства-компаньона

Приложения устройств-компаньонов Windows Hello могут использовать ShowNotificationMessageAsync для отправки сообщений пользователю в рамках пользовательского интерфейса входа.Windows Hello companion device apps can use ShowNotificationMessageAsync to show messages to user as part of the logon UI. Этот API следует вызвать при наличии сигнала намерения.Call this API when an intent signal is available. Обратите внимание, что сигнал намерения всегда должен поступать с устройства-компаньона Windows Hello.Note that an intent signal must always be collected on the Windows Hello companion device side.

Существует два типа сообщений: руководство и ошибки.There are two types of messages: guidance and errors.

Сообщения с руководством предназначены для того, чтобы помочь пользователю начать процесс разблокировки.Guidance messages are designed to show the user how to start the unlock process. Эти сообщения отображаются для пользователя только один раз на экране блокировки — при первоначальной регистрации устройства.These messages are only shown to the user once on the lock screen, upon first device registration, and never shown there again. Эти сообщения будут отображаться под экраном блокировки.These messages will continue to be shown under the lock screen.

Сообщения об ошибках отображаются всегда и будут отображаться после получения сигнала о намерении.Error messages are always shown and will be shown after an intent signal is provided. С учетом того, что перед отображением сообщений должен быть получен сигнал намерения, а пользователь отправит этот сигнал только с помощью одного из своих устройств-компаньонов, недопустима ситуация, в которой несколько устройств-компаньонов Windows Hello конкурируют с целью отображения сообщений об ошибках.Given that an intent signal must be collected before showing messages to the user, and the user will provide that intent only using one of the Windows Hello companion devices, there must not be a situation where multiple Windows Hello companion devices race for showing error messages. Как следствие, платформа сопутствующих устройств Windows Hello не поддерживает постановку сообщений в какую-либо очередь на отображение.As a result, the Windows Hello companion device framework does not maintain any queue. Когда вызывающая сторона запрашивает сообщение об ошибке, оно отображается в течение 5 секунд, а все остальные запросы на отображение сообщений об ошибке в течение этого времени отклоняются.When a caller asks for an error message, it will be shown for 5 seconds and all other requests for showing an error message in that 5 seconds are dropped. По прошествии 5 секунд другая вызывающая сторона получает возможность отобразить сообщение об ошибке.Once 5 seconds has passed, then the opportunity arises for another caller to show an error message. Мы не позволяем вызывающим сторонам блокировать канал ошибок.We prohibit any caller from jamming the error channel.

Сообщения с руководством и сообщения об ошибках выглядят следующим образом.Guidance and error messages are as follows. Имя устройства — это параметр, передаваемый приложением устройства-компаньона в составе ShowNotificationMessageAsync.Device name is a parameter passed by the companion device app as part of ShowNotificationMessageAsync.

РуководствоGuidance

  • "Проведите пальцем вверх или нажмите клавишу "ПРОБЕЛ", чтобы войти с помощью имя устройства"."Swipe up or press space bar to sign in with device name."
  • "Выполняется настройка сопутствующего устройства."Setting up your companion device. Подождите или используйте другой способ входа."Please wait or use another sign-in option."
  • "Приложите имя устройства к NFC-сканеру, чтобы войти"."Tap device name to the NFC reader to sign in."
  • "Поиск имя устройства...""Looking for device name ..."
  • "Подключите имя устройства к USB-порту, чтобы войти"."Plug device name into a USB port to sign in."

ошибкиErrors

  • "Инструкции по входу можно найти на имя устройства"."See device name for sign-in instructions."
  • "Включите Bluetooth, чтобы использовать имя устройства для входа"."Turn on Bluetooth to use device name to sign in."
  • "Включите NFC, чтобы использовать имя устройства для входа"."Turn on NFC to use device name to sign in."
  • "Подключитесь к сети Wi-Fi, чтобы использовать имя устройства для входа"."Connect to a Wi-Fi network to use device name to sign in."
  • "Коснитесь имя устройства еще раз"."Tap device name again."
  • "Ваше предприятие запрещает вход с помощью имя устройства."Your enterprise prevents sign in with device name. Используйте другой способ входа."Use another sign-in option."
  • "Коснитесь имя устройства, чтобы войти"."Tap device name to sign in."
  • "Коснитесь и удерживайте имя устройства, чтобы войти"."Rest your finger on device name to sign in."
  • "Проведите пальцем по имя устройства, чтобы войти"."Swipe your finger on device name to sign in."
  • "Не удается войти с помощью имя устройства."Couldn’t sign in with device name. Используйте другой способ входа."Use another sign-in option."
  • "Произошла ошибка."Something went wrong. Используйте другой способ входа, а затем снова настройте имя устройства."Use another sign-in option, and then set up device name again."
  • "Повторите попытку"."Try again."
  • "Произнесите свою устную парольную фразу в микрофон имя устройства"."Say your Spoken Passphrase into device name."
  • "Все готово ко входу с помощью имя устройства"."Ready to sign in with device name."
  • "Используйте другой способ входа. После этого вы сможете использовать для входа имя устройства"."Use another sign-in option first, then you can use device name to sign in."

Перечисление зарегистрированных устройствEnumerating registered devices

Приложение устройства-компаньона Windows Hello может перечислить список зарегистрированных устройств-компаньонов с помощью вызова FindAllRegisteredDeviceInfoAsync.The Windows Hello companion device app can enumerate the list of registered companion devices via FindAllRegisteredDeviceInfoAsync call. Этот API поддерживает два типа запросов, определенных через перечисление SecondaryAuthenticaitonFactorDeviceFindScope:This API supports two query types defined via enum SecondaryAuthenticationFactorDeviceFindScope:

{
    User = 0,
    AllUsers,
}

Первая область возвращает список устройств для выполнившего вход пользователя.The first scope returns the list of devices for the logged on user. Вторая возвращает список всех пользователей на этом компьютере.The second one returns the list for all users on that PC. Первую область следует использовать при отмене регистрации, чтобы избежать отмены регистрации устройства-компаньона Windows Hello другого пользователя.The first scope must be used at un-registration time to avoid un-registering another user's Windows Hello companion device. Вторую область следует использовать при проверке подлинности или регистрации. При регистрации это перечисление поможет приложению не допустить повторной регистрации одного и того же устройства-компаньона Windows Hello.The second one must be used at authentication or registration time: at registration time, this enumeration can help the app avoid trying to register the same Windows Hello companion device twice.

Обратите внимание, что даже если приложение не выполнит эту проверку, компьютер проведет ее и не позволит зарегистрировать одно и то же устройство-компаньон Windows Hello несколько раз.Note that even if the app does not perform this check, the PC does and will reject the same Windows Hello companion device from being registered more than once. Использование области AllUsers при проверке подлинности позволяет приложению устройства-компаньона Windows Hello поддерживать процесс переключения пользователей: выполняется вход для пользователя А во время сеанса входа пользователя Б (для этого необходимо, чтобы у обоих пользователей было установлено приложение устройства-компаньона Windows Hello, устройства-компаньоны пользователя А были зарегистрированы на компьютере и на компьютере отображался экран блокировки или входа).At authentication time, using the AllUsers scope helps the Windows Hello companion device app support switch user flow: log on user A when user B is logged in (this requires that both users have installed the Windows Hello companion device app and user A has registered their companion devices with the PC and the PC is sitting on lock screen (or logon screen)).

Требования безопасностиSecurity requirements

Служба проверки подлинности устройств-компаньонов предоставляет следующие средства обеспечения безопасности.The Companion Authentication Service provides the following security protections.

  • Вредоносная программа на настольном компьютере с Windows 10, работающем в качестве пользователя со средней активностью или контейнера приложений, не может использовать устройство-компаньон Windows Hello для незаметного получения доступа к ключам учетных данных пользователя (хранящимся в составе Windows Hello) на компьютере.Malware on a Windows 10 desktop device running as a medium user or app container cannot use the Windows Hello companion device to access user credential keys (stored as part of Windows Hello) on a PC silently.
  • Злоумышленник на настольном компьютере с Windows 10 не может использовать устройство-компаньон Windows Hello другого пользователя на этом компьютере для незаметного получения доступа к ключам учетных данных этого пользователя (на том же настольном компьютере с Windows 10).A malicious user on a Windows 10 desktop device cannot use the Windows Hello companion device that belongs to another user on that Windows 10 desktop device to get silent access to his user credential keys (on the same Windows 10 desktop device).
  • Вредоносная программа на устройстве-компаньоне Windows Hello не может незаметно получить доступ к ключам учетных данных пользователя на настольном компьютере с Windows 10, в том числе использовать функции или код, разработанные специально для платформы сопутствующих устройств Windows Hello.Malware on the Windows Hello companion device cannot silently get access to user credential keys on a Windows 10 desktop device, including leveraging functionality or code developed specifically for the Windows Hello companion device framework.
  • Злоумышленник не может разблокировать настольный компьютер с Windows 10 путем перехвата трафика между устройством-компаньоном Windows Hello и этим компьютером с последующей имитацией перехваченного трафика.A malicious user cannot unlock a Windows 10 desktop device by capturing traffic between the Windows Hello companion device and the Windows 10 desktop device and replaying it later. Использование nonce, authkey и HMAC в нашем протоколе обеспечивает надежную защиту от атак с имитацией перехваченного трафика.Usage of nonce, authkey, and HMAC in our protocol guarantees protection against a replay attack.
  • Вредоносная программа или злоумышленник на взломанном компьютере не может использовать устройство-компаньон Windows Hello для получения доступа к компьютеру авторизованного пользователя.Malware or a malicious user on a rouge PC cannot use Windows Hello companion device to get access to honest user PC. Это обеспечивается благодаря взаимной проверке подлинности между службой устройств-компаньонов и устройством-компаньоном Windows Hello с использованием authkey и HMAC в нашем протоколе.This is achieved through mutual authentication between Companion Authentication Service and Windows Hello companion device through usage of authkey and HMAC in our protocol.

Основное условие эффективности указанных средств обеспечения безопасности заключается в защите ключей HMAC от несанкционированного доступа и проверке присутствия пользователя.The key to achieve the security protections enumerated above is to protect HMAC keys from unauthorized access and also verifying user presence. В частности, должны выполняться следующие требования:More specifically, it must satisfy these requirements:

  • обеспечение защиты от клонирования устройства-компаньона Windows Hello;Provide protection against cloning the Windows Hello companion device
  • обеспечение защиты от перехвата при отправке ключей HMAC на компьютер во время регистрации;Provide protection against eavesdropping when sending HMAC keys at registration time to the PC
  • проверка наличия сигнала присутствия пользователя.Make sure that user presence signal is available