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