wpa_supplicant/README-DPP

   1 Device Provisioning Protocol (DPP)
   2 ==================================
   3
   4 This document describes how the Device Provisioning Protocol (DPP)
   5 implementation in wpa_supplicant and hostapd can be configured and how
   6 the STA device and AP can be configured to connect each other using DPP
   7 Connector mechanism.
   8
   9 Introduction to DPP
  10 -------------------
  11
  12 Device provisioning Protocol allows enrolling of interface-less devices
  13 in a secure Wi-Fi network using many methods like QR code based
  14 authentication( detailed below ), PKEX based authentication etc. In DPP
  15 a Configurator is used to provide network credentials to the devices.
  16 The three phases of DPP connection are authentication, configuration and
  17 network introduction.
  18
  19 Build config setup
  20 ------------------
  21
  22 The following changes must go in the config file used to compile hostapd
  23 and wpa_supplicant.
  24
  25 wpa_supplicant build config
  26 ---------------------------
  27
  28 Enable DPP and protected management frame in wpa_supplicant build config
  29 file
  30
  31 CONFIG_DPP=y
  32
  33 hostapd build config
  34 --------------------
  35
  36 Enable DPP and protected management frame in hostapd build config file
  37
  38 CONFIG_DPP=y
  39
  40 Configurator build config
  41 -------------------------
  42
  43 Any STA or AP device can act as a Configurator. Enable DPP and protected
  44 managment frames in build config. For an AP to act as Configurator,
  45 Interworking needs to be enabled. For wpa_supplicant it is not required.
  46
  47 CONFIG_INTERWORKING=y
  48
  49
  50 Sample supplicant config file before provisioning
  51 -------------------------------------------------
  52
  53 ctrl_interface=DIR=/var/run/wpa_supplicant
  54 ctrl_interface_group=0
  55 update_config=1
  56 pmf=2
  57 dpp_config_processing=2
  58
  59 Sample hostapd config file before provisioning
  60 ----------------------------------------------
  61
  62 interface=wlan0
  63 driver=nl80211
  64 ctrl_interface=/var/run/hostapd
  65 ssid=test
  66 channel=1
  67 wpa=2
  68 wpa_key_mgmt=DPP
  69 ieee80211w=1
  70 wpa_pairwise=CCMP
  71 rsn_pairwise=CCMP
  72
  73
  74 Pre-requisites
  75 --------------
  76
  77 It is assumed that an AP and client station are up by running hostapd
  78 and wpa_supplicant using respective config files.
  79
  80
  81 Creating Configurator
  82 ---------------------
  83
  84 Add a Configurator over the control interface (wpa_cli/hostapd_cli)
  85
  86 > dpp_configurator_add
  87 (returns id)
  88
  89 To get key of Configurator
  90 > dpp_configurator_get_key <id>
  91
  92
  93 How to configure an enrollee using Configurator
  94 -----------------------------------------------
  95
  96 On enrollee side:
  97
  98 Generate QR code for the device. Store the qr code id returned by the
  99 command.
 100
 101 > dpp_bootstrap_gen type=qrcode mac=<mac-address-of-device> chan=<operating-class/operating-channel> key=<key of the device>
 102 (returns bootstrapping info id)
 103
 104 Get QR Code of device using the bootstrap info id.
 105 > dpp_bootstrap_get_uri <bootstrap-id>
 106
 107 Make device listen to DPP request (The central frequency of channel 1 is
 108 2412) in case if enrollee is a client device.
 109
 110 > dpp_listen <frequency>
 111
 112 On Configurator side:
 113
 114 Enter the QR Code in the Configurator.
 115 > dpp_qr_code "<QR-Code-read-from-enrollee>"
 116
 117 On successfully adding QR Code, a bootstrapping info id is returned.
 118
 119 Send provisioning request to enrollee. (conf is ap-dpp if enrollee is an
 120 AP. conf is sta-dpp if enrollee is a client)
 121 > dpp_auth_init peer=<qr-code-id> conf=<ap-dpp|sta-dpp> ssid=<SSID hexdump> configurator=<configurator-id>
 122 or for legacy (PSK/SAE) provisioning for a station Enrollee:
 123 > dpp_auth_init peer=<qr-code-id> conf=sta-psk ssid=<SSID hexdump> pass=<passphrase hexdump>
 124
 125 The DPP values will be printed in the console. Save this values into the
 126 config file. If the enrollee is an AP, we need to manually write these
 127 values to the hostapd config file. If the enrollee is a client device,
 128 these details can be automatically saved to config file using the
 129 following command.
 130
 131 > save_config
 132
 133 To set values in runtime for AP enrollees
 134
 135 > set dpp_connector <Connector-value-printed-on-console>
 136 > set dpp_csign <csign-value-on-console>
 137 > set dpp_netaccesskey <netaccess-value-on-console>
 138
 139 To set values in runtime for client enrollees, set dpp_config_processing
 140 to 2 in wpa_supplicant conf file.
 141
 142 Once the values are set in run-time (if not set in run-time, but saved
 143 in config files, they are taken up in next restart), the client device
 144 will automatically connect to the already provisioned AP and connection
 145 will be established.
 146
 147
 148 Self-configuring a device
 149 -------------------------
 150
 151 It is possible for a device to configure itself if it is the
 152 Configurator for the network.
 153
 154 Create a Configurator in the device and use the dpp_configurator_sign
 155 command to get DPP credentials.
 156
 157 > dpp_configurator_add
 158 (returns configurator id)
 159 > dpp_configurator_sign conf=<ap-dpp|sta-dpp> configurator=<configurator-id>
 160
 161
 162 Sample AP configuration files after provisioning
 163 ------------------------------------------------
 164
 165 interface=wlan0
 166 driver=nl80211
 167 ctrl_interface=/var/run/hostapd
 168 ssid=test
 169 channel=1
 170 wpa=2
 171 wpa_key_mgmt=DPP
 172 ieee80211w=1
 173 wpa_pairwise=CCMP
 174 rsn_pairwise=CCMP
 175 dpp_connector=<Connector value provided by Configurator>
 176 dpp_csign=<C-Sign-Key value provided by Configurator>
 177 dpp_netaccesskey=<Net access key provided by Configurator>
 178
 179
 180 Sample station configuration file after provisioning
 181 ----------------------------------------------------
 182
 183 ctrl_interface=DIR=/var/run/wpa_supplicant
 184 ctrl_interface_group=0
 185 update_config=1
 186 pmf=2
 187 dpp_config_processing=2
 188 network={
 189         ssid="test"
 190         key_mgmt=DPP
 191         ieee80211w=2
 192         dpp_connector="<Connector value provided by Configurator>"
 193         dpp_netaccesskey=<Net access key provided by Configurator>
 194         dpp_csign=<C-sign-key value provided by Configurator>
 195 }