191 lines
7.2 KiB
C
191 lines
7.2 KiB
C
// Copyright (c) 2015-2019 The HomeKit ADK Contributors
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the “License”);
|
|
// you may not use this file except in compliance with the License.
|
|
// See [CONTRIBUTORS.md] for the list of HomeKit ADK project authors.
|
|
|
|
#ifndef HAP_PLATFORM_ACCESSORY_SETUP_H
|
|
#define HAP_PLATFORM_ACCESSORY_SETUP_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include "HAPPlatform.h"
|
|
|
|
#if __has_feature(nullability)
|
|
#pragma clang assume_nonnull begin
|
|
#endif
|
|
|
|
/**
|
|
* @file
|
|
*
|
|
* Each accessory must be provisioned for use with HomeKit during manufacturing.
|
|
* This platform module must be implemented to provide access to the provisioned information.
|
|
*
|
|
*
|
|
* Setup code:
|
|
*
|
|
* During HomeKit pairing, a setup code is used by the controller to set up an encrypted link with the accessory.
|
|
* - If the accessory has a display that supports showing a setup code, a random setup code is used while pairing.
|
|
* - Otherwise, a static setup code has to be generated during manufacturing that is deployed to the accessory.
|
|
*
|
|
* If a static setup code is used, the following steps must be followed for each accessory:
|
|
*
|
|
* 1. A random setup code in format "XXX-XX-XXX" with X being a digit from 0-9 must be generated.
|
|
* - The setup code must be generated from a cryptographically secure random number generator.
|
|
* - Setup codes that only consist of a repeating digit are not allowed.
|
|
* - 123-45-678 and 876-54-321 are not allowed.
|
|
*
|
|
* 2. A random SRP salt (16 random bytes) must be generated.
|
|
* - The SRP salt must be generated from a cryptographically secure random number generator.
|
|
*
|
|
* 3. The corresponding SRP verifier is derived from the setup code and the SRP salt.
|
|
*
|
|
* 4. The SRP salt and SRP verifier are deployed to the accessory.
|
|
*
|
|
* 5. If the accessory has a programmable NFC tag, the setup code must also be deployed.
|
|
* Otherwise, the raw setup code must not be deployed.
|
|
*
|
|
*
|
|
* Setup ID:
|
|
*
|
|
* To improve the setup experience, a random setup ID is generated and deployed to each accessory during manufacturing.
|
|
* During pairing, the setup ID is used to identify the accessory to which a scanned label belongs.
|
|
*
|
|
* The following steps must be followed for each accessory:
|
|
*
|
|
* 1. A random setup ID in format "XXXX" with X being a digit from 0-9 or a character from A-Z must be generated.
|
|
* - The setup ID must be generated from a cryptographically secure random number generator.
|
|
* - Lowercase characters are not allowed.
|
|
*
|
|
* 2. The setup ID is deployed to the accessory.
|
|
*
|
|
* - If no setup ID is deployed, certain features like QR code displays or programmable NFC are unavailable.
|
|
*
|
|
*
|
|
* Labels:
|
|
*
|
|
* If the accessory has a static setup code, a label must be affixed to the accessory and its packaging.
|
|
* Labels are based on the setup payload that is derived from the setup ID and the setup code.
|
|
*
|
|
* There are different kinds of labels:
|
|
* - Labels consisting of a QR code that encodes the setup payload, and containing the setup code.
|
|
* - Labels with an embedded NFC tag that provides the setup payload when read, and containing the setup code.
|
|
* - Legacy labels containing only the setup code.
|
|
*
|
|
* If an accessory has a programmable NFC tag, only QR code labels should be used.
|
|
* If the accessory is a security class device and uses NFC pairing, it must have a programmable NFC tag.
|
|
*/
|
|
|
|
/**
|
|
* Accessory setup manager.
|
|
*/
|
|
typedef struct HAPPlatformAccessorySetup HAPPlatformAccessorySetup;
|
|
typedef struct HAPPlatformAccessorySetup* HAPPlatformAccessorySetupRef;
|
|
HAP_NONNULL_SUPPORT(HAPPlatformAccessorySetup)
|
|
|
|
/**
|
|
* Loads SRP salt and verifier of a static setup code.
|
|
*
|
|
* - If the accessory can display a dynamic setup code, implementation is not required.
|
|
*
|
|
* @param accessorySetup Accessory setup manager.
|
|
* @param[out] setupInfo Setup info.
|
|
*/
|
|
void HAPPlatformAccessorySetupLoadSetupInfo(HAPPlatformAccessorySetupRef accessorySetup, HAPSetupInfo* setupInfo);
|
|
|
|
/**
|
|
* Loads statically provisioned setup code in plaintext.
|
|
*
|
|
* - Must only be implemented if the accessory is connected to a programmable NFC tag
|
|
* but can't display a dynamic setup code.
|
|
*
|
|
* - The static setup info must be loadable and must be compatible with the setup code.
|
|
*
|
|
* @param accessorySetup Accessory setup manager.
|
|
* @param[out] setupCode Setup code.
|
|
*/
|
|
void HAPPlatformAccessorySetupLoadSetupCode(HAPPlatformAccessorySetupRef accessorySetup, HAPSetupCode* setupCode);
|
|
|
|
/**
|
|
* Loads statically provisioned setup ID.
|
|
*
|
|
* - Required to display QR codes and to use programmable NFC tags.
|
|
*
|
|
* @param accessorySetup Accessory setup manager.
|
|
* @param[out] valid True if a setup ID is available. False otherwise.
|
|
* @param[out] setupID Setup ID, if available.
|
|
*/
|
|
void HAPPlatformAccessorySetupLoadSetupID(
|
|
HAPPlatformAccessorySetupRef accessorySetup,
|
|
bool* valid,
|
|
HAPSetupID* setupID);
|
|
|
|
//----------------------------------------------------------------------------------------------------------------------
|
|
// Deprecated APIs.
|
|
|
|
/**
|
|
* Accessory setup capabilities.
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* Whether the accessory can display a dynamic 8-digit setup code.
|
|
*
|
|
* - A QR code may optionally be displayed to simplify scanning by the controller.
|
|
*
|
|
* - If the accessory cannot display a dynamic setup code, static setup info must be loadable.
|
|
*/
|
|
bool supportsDisplay : 1;
|
|
|
|
/**
|
|
* Whether the accessory is connected to a programmable NFC tag that supports NDEF records.
|
|
*
|
|
* - NFC tag types must be Type 2 or greater and must support payload lengths of 30 bytes.
|
|
*/
|
|
bool supportsProgrammableNFC : 1;
|
|
} HAPPlatformAccessorySetupCapabilities;
|
|
|
|
/**
|
|
* Returns the accessory setup capabilities.
|
|
*
|
|
* @param accessorySetup Accessory setup manager.
|
|
*
|
|
* @return Accessory setup capabilities.
|
|
*/
|
|
HAP_DEPRECATED_MSG("Return false and use HAPPlatformAccessorySetupDisplay / HAPPlatformAccessorySetupNFC instead.")
|
|
HAP_RESULT_USE_CHECK
|
|
HAPPlatformAccessorySetupCapabilities
|
|
HAPPlatformAccessorySetupGetCapabilities(HAPPlatformAccessorySetupRef accessorySetup);
|
|
|
|
/**
|
|
* Updates the setup payload and setup code for displays and programmable NFC tags.
|
|
*
|
|
* Display:
|
|
* - If setupCode is NULL, the display must stop showing setup information.
|
|
* - If setupCode is set, the display must show the given setup code.
|
|
* If setupPayload is also set, a scannable QR code describing the setup payload may be presented instead.
|
|
*
|
|
* Programmable NFC:
|
|
* - If setupPayload is set, the programmable NFC tag must be reprogrammed using the updated setup payload.
|
|
*
|
|
* @param accessorySetup Accessory setup manager.
|
|
* @param setupPayload Setup payload, if available.
|
|
* @param setupCode Setup code to display, if available.
|
|
*/
|
|
HAP_DEPRECATED_MSG("Use HAPPlatformAccessorySetupDisplay / HAPPlatformAccessorySetupNFC instead.")
|
|
void HAPPlatformAccessorySetupUpdateSetupPayload(
|
|
HAPPlatformAccessorySetupRef accessorySetup,
|
|
const HAPSetupPayload* _Nullable setupPayload,
|
|
const HAPSetupCode* _Nullable setupCode);
|
|
|
|
#if __has_feature(nullability)
|
|
#pragma clang assume_nonnull end
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|