1wpa_supplicant and Wi-Fi P2P 2============================ 3 4This document describes how the Wi-Fi P2P implementation in 5wpa_supplicant can be configured and how an external component on the 6client (e.g., management GUI) is used to enable WPS enrollment and 7registrar registration. 8 9 10Introduction to Wi-Fi P2P 11------------------------- 12 13TODO 14 15More information about Wi-Fi P2P is available from Wi-Fi Alliance: 16http://www.wi-fi.org/Wi-Fi_Direct.php 17 18 19wpa_supplicant implementation 20----------------------------- 21 22TODO 23 24 25wpa_supplicant configuration 26---------------------------- 27 28Wi-Fi P2P is an optional component that needs to be enabled in the 29wpa_supplicant build configuration (.config). Here is an example 30configuration that includes Wi-Fi P2P support and Linux nl80211 31-based driver interface: 32 33CONFIG_DRIVER_NL80211=y 34CONFIG_CTRL_IFACE=y 35CONFIG_P2P=y 36CONFIG_AP=y 37CONFIG_WPS=y 38 39 40In run-time configuration file (wpa_supplicant.conf), some parameters 41for P2P may be set. In order to make the devices easier to recognize, 42device_name and device_type should be specified. For example, 43something like this should be included: 44 45ctrl_interface=/var/run/wpa_supplicant 46device_name=My P2P Device 47device_type=1-0050F204-1 48 49 50wpa_cli 51------- 52 53Actual Wi-Fi P2P operations are requested during runtime. These can be 54done for example using wpa_cli (which is described below) or a GUI 55like wpa_gui-qt4. 56 57 58wpa_cli starts in interactive mode if no command string is included on 59the command line. By default, it will select the first network interface 60that it can find (and that wpa_supplicant controls). If more than one 61interface is in use, it may be necessary to select one of the explicitly 62by adding -i argument on the command line (e.g., 'wpa_cli -i wlan1'). 63 64Most of the P2P operations are done on the main interface (e.g., the 65interface that is automatically added when the driver is loaded, e.g., 66wlan0). When using a separate virtual interface for group operations 67(e.g., wlan1), the control interface for that group interface may need 68to be used for some operations (mainly WPS activation in GO). This may 69change in the future so that all the needed operations could be done 70over the main control interface. 71 72Device Discovery 73 74p2p_find [timeout in seconds] [type=<social|progressive>] \ 75 [dev_id=<addr>] [dev_type=<device type>] \ 76 [delay=<search delay in ms>] 77 78The default behavior is to run a single full scan in the beginning and 79then scan only social channels. type=social will scan only social 80channels, i.e., it skips the initial full scan. type=progressive is 81like the default behavior, but it will scan through all the channels 82progressively one channel at the time in the Search state rounds. This 83will help in finding new groups or groups missed during the initial 84full scan. 85 86The optional dev_id option can be used to specify a single P2P peer to 87search for. The optional delay parameter can be used to request an extra 88delay to be used between search iterations (e.g., to free up radio 89resources for concurrent operations). 90 91The optional dev_type option can be used to specify a single device type 92(primary or secondary) to search for, e.g., 93"p2p_find dev_type=1-0050F204-1". 94 95p2p_listen [timeout in seconds] 96 97Start Listen-only state (become discoverable without searching for 98other devices). Optional parameter can be used to specify the duration 99for the Listen operation in seconds. This command may not be of that 100much use during normal operations and is mainly designed for 101testing. It can also be used to keep the device discoverable without 102having to maintain a group. 103 104p2p_stop_find 105 106Stop ongoing P2P device discovery or other operation (connect, listen 107mode). 108 109p2p_flush 110 111Flush P2P peer table and state. 112 113Group Formation 114 115p2p_prov_disc <peer device address> <display|keypad|pbc> [join|auto] 116 117Send P2P provision discovery request to the specified peer. The 118parameters for this command are the P2P device address of the peer and 119the desired configuration method. For example, "p2p_prov_disc 12002:01:02:03:04:05 display" would request the peer to display a PIN for 121us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer 122to enter a PIN that we display. 123 124The optional "join" parameter can be used to indicate that this command 125is requesting an already running GO to prepare for a new client. This is 126mainly used with "display" to request it to display a PIN. The "auto" 127parameter can be used to request wpa_supplicant to automatically figure 128out whether the peer device is operating as a GO and if so, use 129join-a-group style PD instead of GO Negotiation style PD. 130 131p2p_connect <peer device address> <pbc|pin|PIN#> [display|keypad] 132 [persistent|persistent=<network id>] [join|auth] 133 [go_intent=<0..15>] [freq=<in MHz>] [ht40] [vht] [provdisc] 134 135Start P2P group formation with a discovered P2P peer. This includes 136optional group owner negotiation, group interface setup, provisioning, 137and establishing data connection. 138 139The <pbc|pin|PIN#> parameter specifies the WPS provisioning 140method. "pbc" string starts pushbutton method, "pin" string start PIN 141method using an automatically generated PIN (which will be returned as 142the command return code), PIN# means that a pre-selected PIN can be 143used (e.g., 12345670). [display|keypad] is used with PIN method 144to specify which PIN is used (display=dynamically generated random PIN 145from local display, keypad=PIN entered from peer display). "persistent" 146parameter can be used to request a persistent group to be formed. The 147"persistent=<network id>" alternative can be used to pre-populate 148SSID/passphrase configuration based on a previously used persistent 149group where this device was the GO. The previously used parameters will 150then be used if the local end becomes the GO in GO Negotiation (which 151can be forced with go_intent=15). 152 153"join" indicates that this is a command to join an existing group as a 154client. It skips the GO Negotiation part. This will send a Provision 155Discovery Request message to the target GO before associating for WPS 156provisioning. 157 158"auth" indicates that the WPS parameters are authorized for the peer 159device without actually starting GO Negotiation (i.e., the peer is 160expected to initiate GO Negotiation). This is mainly for testing 161purposes. 162 163"go_intent" can be used to override the default GO Intent for this GO 164Negotiation. 165 166"freq" can be used to set a forced operating channel (e.g., freq=2412 167to select 2.4 GHz channel 1). 168 169"provdisc" can be used to request a Provision Discovery exchange to be 170used prior to starting GO Negotiation as a workaround with some deployed 171P2P implementations that require this to allow the user to accept the 172connection. 173 174p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>] 175 [ht40] [vht] 176 177Set up a P2P group owner manually (i.e., without group owner 178negotiation with a specific peer). This is also known as autonomous 179GO. Optional persistent=<network id> can be used to specify restart of 180a persistent group. Optional freq=<freq in MHz> can be used to force 181the GO to be started on a specific frequency. Special freq=2 or freq=5 182options can be used to request the best 2.4 GHz or 5 GHz band channel 183to be selected automatically. 184 185p2p_reject <peer device address> 186 187Reject connection attempt from a peer (specified with a device 188address). This is a mechanism to reject a pending GO Negotiation with 189a peer and request to automatically block any further connection or 190discovery of the peer. 191 192p2p_group_remove <group interface> 193 194Terminate a P2P group. If a new virtual network interface was used for 195the group, it will also be removed. The network interface name of the 196group interface is used as a parameter for this command. 197 198p2p_cancel 199 200Cancel an ongoing P2P group formation and joining-a-group related 201operation. This operations unauthorizes the specific peer device (if any 202had been authorized to start group formation), stops P2P find (if in 203progress), stops pending operations for join-a-group, and removes the 204P2P group interface (if one was used) that is in the WPS provisioning 205step. If the WPS provisioning step has been completed, the group is not 206terminated. 207 208p2p_remove_client <peer's P2P Device Address|iface=<interface address>> 209 210This command can be used to remove the specified client from all groups 211(operating and persistent) from the local GO. Note that the peer device 212can rejoin the group if it is in possession of a valid key. See p2p_set 213per_sta_psk command below for more details on how the peer can be 214removed securely. 215 216Service Discovery 217 218p2p_serv_disc_req 219 220Schedule a P2P service discovery request. The parameters for this 221command are the device address of the peer device (or 00:00:00:00:00:00 222for wildcard query that is sent to every discovered P2P peer that 223supports service discovery) and P2P Service Query TLV(s) as hexdump. For 224example, 225 226p2p_serv_disc_req 00:00:00:00:00:00 02000001 227 228schedules a request for listing all available services of all service 229discovery protocols and requests this to be sent to all discovered 230peers (note: this can result in long response frames). The pending 231requests are sent during device discovery (see p2p_find). 232 233There can be multiple pending peer device specific queries (each will be 234sent in sequence whenever the peer is found). 235 236This command returns an identifier for the pending query (e.g., 237"1f77628") that can be used to cancel the request. Directed requests 238will be automatically removed when the specified peer has replied to 239it. 240 241Service Query TLV has following format: 242Length (2 octets, little endian) - length of following data 243Service Protocol Type (1 octet) - see the table below 244Service Transaction ID (1 octet) - nonzero identifier for the TLV 245Query Data (Length - 2 octets of data) - service protocol specific data 246 247Service Protocol Types: 2480 = All service protocols 2491 = Bonjour 2502 = UPnP 2513 = WS-Discovery 2524 = Wi-Fi Display 253 254For UPnP, an alternative command format can be used to specify a 255single query TLV (i.e., a service discovery for a specific UPnP 256service): 257 258p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH> 259 260For example: 261 262p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 263 264Additional examples for queries: 265 266# list of all Bonjour services 267p2p_serv_disc_req 00:00:00:00:00:00 02000101 268 269# list of all UPnP services 270p2p_serv_disc_req 00:00:00:00:00:00 02000201 271 272# list of all WS-Discovery services 273p2p_serv_disc_req 00:00:00:00:00:00 02000301 274 275# list of all Bonjour and UPnP services 276p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202 277 278# Apple File Sharing over TCP 279p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01 280 281# Bonjour SSTH (supported service type hash) 282p2p_serv_disc_req 00:00:00:00:00:00 05000101000000 283 284# UPnP examples 285p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all 286p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice 287p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2 288p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012 289p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 290 291# Wi-Fi Display examples 292# format: wifi-display <list of roles> <list of subelements> 293p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source] 2,3,4,5 294p2p_serv_disc_req 02:01:02:03:04:05 wifi-display [pri-sink] 3 295p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [sec-source] 2 296p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source+sink] 2,3,4,5 297p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source][pri-sink] 2,3,4,5 298 299p2p_serv_disc_cancel_req <query identifier> 300 301Cancel a pending P2P service discovery request. This command takes a 302single parameter: identifier for the pending query (the value returned 303by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628". 304 305p2p_serv_disc_resp 306 307Reply to a service discovery query. This command takes following 308parameters: frequency in MHz, destination address, dialog token, 309response TLV(s). The first three parameters are copied from the 310request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7 3111 0300000101". This command is used only if external program is used 312to process the request (see p2p_serv_disc_external). 313 314p2p_service_update 315 316Indicate that local services have changed. This is used to increment 317the P2P service indicator value so that peers know when previously 318cached information may have changed. This is only needed when external 319service discovery processing is enabled since the commands to 320pre-configure services for internal processing will increment the 321indicator automatically. 322 323p2p_serv_disc_external <0|1> 324 325Configure external processing of P2P service requests: 0 (default) = 326no external processing of requests (i.e., internal code will process 327each request based on pre-configured services), 1 = external 328processing of requests (external program is responsible for replying 329to service discovery requests with p2p_serv_disc_resp). Please note 330that there is quite strict limit on how quickly the response needs to 331be transmitted, so use of the internal processing is strongly 332recommended. 333 334p2p_service_add bonjour <query hexdump> <RDATA hexdump> 335 336Add a local Bonjour service for internal SD query processing. 337 338Examples: 339 340# AFP Over TCP (PTR) 341p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027 342# AFP Over TCP (TXT) (RDATA=null) 343p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00 344 345# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.) 346p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027 347# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript) 348p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074 349 350# Supported Service Type Hash (SSTH) 351p2p_service_add bonjour 000000 <32-byte bitfield as hexdump> 352(note: see P2P spec Annex E.4 for information on how to construct the bitfield) 353 354p2p_service_del bonjour <query hexdump> 355 356Remove a local Bonjour service from internal SD query processing. 357 358p2p_service_add upnp <version hex> <service> 359 360Add a local UPnP service for internal SD query processing. 361 362Examples: 363 364p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice 365p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice 366p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2 367p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2 368p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1 369 370p2p_service_del upnp <version hex> <service> 371 372Remove a local UPnP service from internal SD query processing. 373 374p2p_service_flush 375 376Remove all local services from internal SD query processing. 377 378Invitation 379 380p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address] 381 [go_dev_addr=address] [freq=<freq in MHz>] [ht40] [vht] 382 [pref=<MHz>] 383 384Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a 385persistent group (e.g., persistent=4). If the peer device is the GO of 386the persistent group, the peer parameter is not needed. Otherwise it is 387used to specify which device to invite. go_dev_addr parameter can be 388used to override the GO device address for Invitation Request should 389it be not known for some reason (this should not be needed in most 390cases). When reinvoking a persistent group, the GO device can specify 391the frequency for the group with the freq parameter. When reinvoking a 392persistent group, the P2P client device can use freq parameter to force 393a specific operating channel (or invitation failure if GO rejects that) 394or pref parameter to request a specific channel (while allowing GO to 395select to use another channel, if needed). 396 397Group Operations 398 399(These are used on the group interface.) 400 401wps_pin <any|address> <PIN> 402 403Start WPS PIN method. This allows a single WPS Enrollee to connect to 404the AP/GO. This is used on the GO when a P2P client joins an existing 405group. The second parameter is the address of the Enrollee or a string 406"any" to allow any station to use the entered PIN (which will restrict 407the PIN for one-time-use). PIN is the Enrollee PIN read either from a 408label or display on the P2P Client/WPS Enrollee. 409 410wps_pbc 411 412Start WPS PBC method (i.e., push the button). This allows a single WPS 413Enrollee to connect to the AP/GO. This is used on the GO when a P2P 414client joins an existing group. 415 416p2p_get_passphrase 417 418Get the passphrase for a group (only available when acting as a GO). 419 420p2p_presence_req [<duration> <interval>] [<duration> <interval>] 421 422Send a P2P Presence Request to the GO (this is only available when 423acting as a P2P client). If no duration/interval pairs are given, the 424request indicates that this client has no special needs for GO 425presence. The first parameter pair gives the preferred duration and 426interval values in microseconds. If the second pair is included, that 427indicates which value would be acceptable. This command returns OK 428immediately and the response from the GO is indicated in a 429P2P-PRESENCE-RESPONSE event message. 430 431Parameters 432 433p2p_ext_listen [<period> <interval>] 434 435Configure Extended Listen Timing. If the parameters are omitted, this 436feature is disabled. If the parameters are included, Listen State will 437be entered every interval msec for at least period msec. Both values 438have acceptable range of 1-65535 (with interval obviously having to be 439larger than or equal to duration). If the P2P module is not idle at 440the time the Extended Listen Timing timeout occurs, the Listen State 441operation will be skipped. 442 443The configured values will also be advertised to other P2P Devices. The 444received values are available in the p2p_peer command output: 445 446ext_listen_period=100 ext_listen_interval=5000 447 448p2p_set <field> <value> 449 450Change dynamic P2P parameters 451 452p2p_set discoverability <0/1> 453 454Disable/enable advertisement of client discoverability. This is 455enabled by default and this parameter is mainly used to allow testing 456of device discoverability. 457 458p2p_set managed <0/1> 459 460Disable/enable managed P2P Device operations. This is disabled by 461default. 462 463p2p_set listen_channel <1/6/11> 464 465Set P2P Listen channel. This is mainly meant for testing purposes and 466changing the Listen channel during normal operations can result in 467protocol failures. 468 469p2p_set ssid_postfix <postfix> 470 471Set postfix string to be added to the automatically generated P2P SSID 472(DIRECT-<two random characters>). For example, postfix of "-testing" 473could result in the SSID becoming DIRECT-ab-testing. 474 475p2p_set per_sta_psk <0/1> 476 477Disabled(default)/enables use of per-client PSK in the P2P groups. This 478can be used to request GO to assign a unique PSK for each client during 479WPS provisioning. When enabled, this allow clients to be removed from 480the group securily with p2p_remove_client command since that client's 481PSK is removed at the same time to prevent it from connecting back using 482the old PSK. When per-client PSK is not used, the client can still be 483disconnected, but it will be able to re-join the group since the PSK it 484learned previously is still valid. It should be noted that the default 485passphrase on the GO that is normally used to allow legacy stations to 486connect through manual configuration does not change here, so if that is 487shared, devices with knowledge of that passphrase can still connect. 488 489set <field> <value> 490 491Set global configuration parameters which may also affect P2P 492operations. The format on these parameters is same as is used in 493wpa_supplicant.conf. Only the parameters listen here should be 494changed. Modifying other parameters may result in incorrect behavior 495since not all existing users of the parameters are updated. 496 497set uuid <UUID> 498 499Set WPS UUID (by default, this is generated based on the MAC address). 500 501set device_name <device name> 502 503Set WPS Device Name (also included in some P2P messages). 504 505set manufacturer <manufacturer> 506 507Set WPS Manufacturer. 508 509set model_name <model name> 510 511Set WPS Model Name. 512 513set model_number <model number> 514 515Set WPS Model Number. 516 517set serial_number <serial number> 518 519Set WPS Serial Number. 520 521set device_type <device type> 522 523Set WPS Device Type. 524 525set os_version <OS version> 526 527Set WPS OS Version. 528 529set config_methods <config methods> 530 531Set WPS Configuration Methods. 532 533set sec_device_type <device type> 534 535Add a new Secondary Device Type. 536 537set p2p_go_intent <GO intent> 538 539Set the default P2P GO Intent. Note: This value can be overridden in 540p2p_connect command and as such, there should be no need to change the 541default value here during normal operations. 542 543set p2p_ssid_postfix <P2P SSID postfix> 544 545Set P2P SSID postfix. 546 547set persistent_reconnect <0/1> 548 549Disable/enabled persistent reconnect for reinvocation of persistent 550groups. If enabled, invitations to reinvoke a persistent group will be 551accepted without separate authorization (e.g., user interaction). 552 553set country <two character country code> 554 555Set country code (this is included in some P2P messages). 556 557set p2p_search_delay <delay> 558 559Set p2p_search_delay which adds extra delay in milliseconds between 560concurrent search iterations to make p2p_find friendlier to concurrent 561operations by avoiding it from taking 100% of radio resources. The 562default value is 500 ms. 563 564Status 565 566p2p_peers [discovered] 567 568List P2P Device Addresses of all the P2P peers we know. The optional 569"discovered" parameter filters out the peers that we have not fully 570discovered, i.e., which we have only seen in a received Probe Request 571frame. 572 573p2p_peer <P2P Device Address> 574 575Fetch information about a known P2P peer. 576 577Group Status 578 579(These are used on the group interface.) 580 581status 582 583Show status information (connection state, role, use encryption 584parameters, IP address, etc.). 585 586sta 587 588Show information about an associated station (when acting in AP/GO role). 589 590all_sta 591 592Lists the currently associated stations. 593 594Configuration data 595 596list_networks 597 598Lists the configured networks, including stored information for 599persistent groups. The identifier in this list is used with 600p2p_group_add and p2p_invite to indicate which persistent group is to 601be reinvoked. 602 603remove_network <network id> 604 605Remove a network entry from configuration. 606 607 608wpa_cli action script 609--------------------- 610 611See examples/p2p-action.sh 612 613TODO: describe DHCP/DNS setup 614TODO: cross-connection 615