diff options
Diffstat (limited to 'contrib/wpa/wpa_supplicant/README-P2P')
| -rw-r--r-- | contrib/wpa/wpa_supplicant/README-P2P | 560 |
1 files changed, 560 insertions, 0 deletions
diff --git a/contrib/wpa/wpa_supplicant/README-P2P b/contrib/wpa/wpa_supplicant/README-P2P new file mode 100644 index 0000000..5e98c95 --- /dev/null +++ b/contrib/wpa/wpa_supplicant/README-P2P @@ -0,0 +1,560 @@ +wpa_supplicant and Wi-Fi P2P +============================ + +This document describes how the Wi-Fi P2P implementation in +wpa_supplicant can be configured and how an external component on the +client (e.g., management GUI) is used to enable WPS enrollment and +registrar registration. + + +Introduction to Wi-Fi P2P +------------------------- + +TODO + +More information about Wi-Fi P2P is available from Wi-Fi Alliance: +http://www.wi-fi.org/Wi-Fi_Direct.php + + +wpa_supplicant implementation +----------------------------- + +TODO + + +wpa_supplicant configuration +---------------------------- + +Wi-Fi P2P is an optional component that needs to be enabled in the +wpa_supplicant build configuration (.config). Here is an example +configuration that includes Wi-Fi P2P support and Linux nl80211 +-based driver interface: + +CONFIG_DRIVER_NL80211=y +CONFIG_CTRL_IFACE=y +CONFIG_P2P=y +CONFIG_AP=y +CONFIG_WPS=y + + +In run-time configuration file (wpa_supplicant.conf), some parameters +for P2P may be set. In order to make the devices easier to recognize, +device_name and device_type should be specified. For example, +something like this should be included: + +ctrl_interface=/var/run/wpa_supplicant +device_name=My P2P Device +device_type=1-0050F204-1 + + +wpa_cli +------- + +Actual Wi-Fi P2P operations are requested during runtime. These can be +done for example using wpa_cli (which is described below) or a GUI +like wpa_gui-qt4. + + +wpa_cli starts in interactive mode if no command string is included on +the command line. By default, it will select the first network interface +that it can find (and that wpa_supplicant controls). If more than one +interface is in use, it may be necessary to select one of the explicitly +by adding -i argument on the command line (e.g., 'wpa_cli -i wlan1'). + +Most of the P2P operations are done on the main interface (e.g., the +interface that is automatically added when the driver is loaded, e.g., +wlan0). When using a separate virtual interface for group operations +(e.g., wlan1), the control interface for that group interface may need +to be used for some operations (mainly WPS activation in GO). This may +change in the future so that all the needed operations could be done +over the main control interface. + +Device Discovery + +p2p_find [timeout in seconds] [type=<social|progressive>] \ + [dev_id=<addr>] [delay=<search delay in ms>] + +The default behavior is to run a single full scan in the beginning and +then scan only social channels. type=social will scan only social +channels, i.e., it skips the initial full scan. type=progressive is +like the default behavior, but it will scan through all the channels +progressively one channel at the time in the Search state rounds. This +will help in finding new groups or groups missed during the initial +full scan. + +The optional dev_id option can be used to specify a single P2P peer to +search for. The optional delay parameter can be used to request an extra +delay to be used between search iterations (e.g., to free up radio +resources for concurrent operations). + +p2p_listen [timeout in seconds] + +Start Listen-only state (become discoverable without searching for +other devices). Optional parameter can be used to specify the duration +for the Listen operation in seconds. This command may not be of that +much use during normal operations and is mainly designed for +testing. It can also be used to keep the device discoverable without +having to maintain a group. + +p2p_stop_find + +Stop ongoing P2P device discovery or other operation (connect, listen +mode). + +p2p_flush + +Flush P2P peer table and state. + +Group Formation + +p2p_prov_disc <peer device address> <display|keypad|pbc> [join|auto] + +Send P2P provision discovery request to the specified peer. The +parameters for this command are the P2P device address of the peer and +the desired configuration method. For example, "p2p_prov_disc +02:01:02:03:04:05 display" would request the peer to display a PIN for +us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer +to enter a PIN that we display. + +The optional "join" parameter can be used to indicate that this command +is requesting an already running GO to prepare for a new client. This is +mainly used with "display" to request it to display a PIN. The "auto" +parameter can be used to request wpa_supplicant to automatically figure +out whether the peer device is operating as a GO and if so, use +join-a-group style PD instead of GO Negotiation style PD. + +p2p_connect <peer device address> <pbc|pin|PIN#> [display|keypad] + [persistent|persistent=<network id>] [join|auth] + [go_intent=<0..15>] [freq=<in MHz>] [ht40] [provdisc] + +Start P2P group formation with a discovered P2P peer. This includes +optional group owner negotiation, group interface setup, provisioning, +and establishing data connection. + +The <pbc|pin|PIN#> parameter specifies the WPS provisioning +method. "pbc" string starts pushbutton method, "pin" string start PIN +method using an automatically generated PIN (which will be returned as +the command return code), PIN# means that a pre-selected PIN can be +used (e.g., 12345670). [display|keypad] is used with PIN method +to specify which PIN is used (display=dynamically generated random PIN +from local display, keypad=PIN entered from peer display). "persistent" +parameter can be used to request a persistent group to be formed. The +"persistent=<network id>" alternative can be used to pre-populate +SSID/passphrase configuration based on a previously used persistent +group where this device was the GO. The previously used parameters will +then be used if the local end becomes the GO in GO Negotiation (which +can be forced with go_intent=15). + +"join" indicates that this is a command to join an existing group as a +client. It skips the GO Negotiation part. This will send a Provision +Discovery Request message to the target GO before associating for WPS +provisioning. + +"auth" indicates that the WPS parameters are authorized for the peer +device without actually starting GO Negotiation (i.e., the peer is +expected to initiate GO Negotiation). This is mainly for testing +purposes. + +"go_intent" can be used to override the default GO Intent for this GO +Negotiation. + +"freq" can be used to set a forced operating channel (e.g., freq=2412 +to select 2.4 GHz channel 1). + +"provdisc" can be used to request a Provision Discovery exchange to be +used prior to starting GO Negotiation as a workaround with some deployed +P2P implementations that require this to allow the user to accept the +connection. + +p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>] [ht40] + +Set up a P2P group owner manually (i.e., without group owner +negotiation with a specific peer). This is also known as autonomous +GO. Optional persistent=<network id> can be used to specify restart of +a persistent group. Optional freq=<freq in MHz> can be used to force +the GO to be started on a specific frequency. Special freq=2 or freq=5 +options can be used to request the best 2.4 GHz or 5 GHz band channel +to be selected automatically. + +p2p_reject <peer device address> + +Reject connection attempt from a peer (specified with a device +address). This is a mechanism to reject a pending GO Negotiation with +a peer and request to automatically block any further connection or +discovery of the peer. + +p2p_group_remove <group interface> + +Terminate a P2P group. If a new virtual network interface was used for +the group, it will also be removed. The network interface name of the +group interface is used as a parameter for this command. + +p2p_cancel + +Cancel an ongoing P2P group formation and joining-a-group related +operation. This operations unauthorizes the specific peer device (if any +had been authorized to start group formation), stops P2P find (if in +progress), stops pending operations for join-a-group, and removes the +P2P group interface (if one was used) that is in the WPS provisioning +step. If the WPS provisioning step has been completed, the group is not +terminated. + +Service Discovery + +p2p_serv_disc_req + +Schedule a P2P service discovery request. The parameters for this +command are the device address of the peer device (or 00:00:00:00:00:00 +for wildcard query that is sent to every discovered P2P peer that +supports service discovery) and P2P Service Query TLV(s) as hexdump. For +example, + +p2p_serv_disc_req 00:00:00:00:00:00 02000001 + +schedules a request for listing all available services of all service +discovery protocols and requests this to be sent to all discovered +peers (note: this can result in long response frames). The pending +requests are sent during device discovery (see p2p_find). + +Only a single pending wildcard query is supported, but there can be +multiple pending peer device specific queries (each will be sent in +sequence whenever the peer is found). + +This command returns an identifier for the pending query (e.g., +"1f77628") that can be used to cancel the request. Directed requests +will be automatically removed when the specified peer has replied to +it. + +For UPnP, an alternative command format can be used to specify a +single query TLV (i.e., a service discovery for a specific UPnP +service): + +p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH> + +For example: + +p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 + +Additional examples for queries: + +# list of all Bonjour services +p2p_serv_disc_req 00:00:00:00:00:00 02000101 + +# list of all UPnP services +p2p_serv_disc_req 00:00:00:00:00:00 02000201 + +# list of all WS-Discovery services +p2p_serv_disc_req 00:00:00:00:00:00 02000301 + +# list of all Bonjour and UPnP services +p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202 + +# Apple File Sharing over TCP +p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01 + +# Bonjour SSTH (supported service type hash) +p2p_serv_disc_req 00:00:00:00:00:00 05000101000000 + +# UPnP examples +p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all +p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice +p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2 +p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012 +p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 + +# Wi-Fi Display examples +# format: wifi-display <list of roles> <list of subelements> +p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source] 2,3,4,5 +p2p_serv_disc_req 02:01:02:03:04:05 wifi-display [pri-sink] 3 +p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [sec-source] 2 +p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source+sink] 2,3,4,5 +p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source][pri-sink] 2,3,4,5 + +p2p_serv_disc_cancel_req <query identifier> + +Cancel a pending P2P service discovery request. This command takes a +single parameter: identifier for the pending query (the value returned +by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628". + +p2p_serv_disc_resp + +Reply to a service discovery query. This command takes following +parameters: frequency in MHz, destination address, dialog token, +response TLV(s). The first three parameters are copied from the +request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7 +1 0300000101". This command is used only if external program is used +to process the request (see p2p_serv_disc_external). + +p2p_service_update + +Indicate that local services have changed. This is used to increment +the P2P service indicator value so that peers know when previously +cached information may have changed. This is only needed when external +service discovery processing is enabled since the commands to +pre-configure services for internal processing will increment the +indicator automatically. + +p2p_serv_disc_external <0|1> + +Configure external processing of P2P service requests: 0 (default) = +no external processing of requests (i.e., internal code will process +each request based on pre-configured services), 1 = external +processing of requests (external program is responsible for replying +to service discovery requests with p2p_serv_disc_resp). Please note +that there is quite strict limit on how quickly the response needs to +be transmitted, so use of the internal processing is strongly +recommended. + +p2p_service_add bonjour <query hexdump> <RDATA hexdump> + +Add a local Bonjour service for internal SD query processing. + +Examples: + +# AFP Over TCP (PTR) +p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027 +# AFP Over TCP (TXT) (RDATA=null) +p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00 + +# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.) +p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027 +# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript) +p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074 + +# Supported Service Type Hash (SSTH) +p2p_service_add bonjour 000000 <32-byte bitfield as hexdump> +(note: see P2P spec Annex E.4 for information on how to construct the bitfield) + +p2p_service_del bonjour <query hexdump> + +Remove a local Bonjour service from internal SD query processing. + +p2p_service_add upnp <version hex> <service> + +Add a local UPnP service for internal SD query processing. + +Examples: + +p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice +p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice +p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2 +p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2 +p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1 + +p2p_service_del upnp <version hex> <service> + +Remove a local UPnP service from internal SD query processing. + +p2p_service_flush + +Remove all local services from internal SD query processing. + +Invitation + +p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address] + [go_dev_addr=address] [freq=<freq in MHz>] [ht40] + +Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a +persistent group (e.g., persistent=4). If the peer device is the GO of +the persistent group, the peer parameter is not needed. Otherwise it is +used to specify which device to invite. go_dev_addr parameter can be +used to override the GO device address for Invitation Request should +it be not known for some reason (this should not be needed in most +cases). When reinvoking a persistent group, the GO device can specify +the frequency for the group with the freq parameter. + +Group Operations + +(These are used on the group interface.) + +wps_pin <any|address> <PIN> + +Start WPS PIN method. This allows a single WPS Enrollee to connect to +the AP/GO. This is used on the GO when a P2P client joins an existing +group. The second parameter is the address of the Enrollee or a string +"any" to allow any station to use the entered PIN (which will restrict +the PIN for one-time-use). PIN is the Enrollee PIN read either from a +label or display on the P2P Client/WPS Enrollee. + +wps_pbc + +Start WPS PBC method (i.e., push the button). This allows a single WPS +Enrollee to connect to the AP/GO. This is used on the GO when a P2P +client joins an existing group. + +p2p_get_passphrase + +Get the passphrase for a group (only available when acting as a GO). + +p2p_presence_req [<duration> <interval>] [<duration> <interval>] + +Send a P2P Presence Request to the GO (this is only available when +acting as a P2P client). If no duration/interval pairs are given, the +request indicates that this client has no special needs for GO +presence. the first parameter pair gives the preferred duration and +interval values in microseconds. If the second pair is included, that +indicates which value would be acceptable. + +Parameters + +p2p_ext_listen [<period> <interval>] + +Configure Extended Listen Timing. If the parameters are omitted, this +feature is disabled. If the parameters are included, Listen State will +be entered every interval msec for at least period msec. Both values +have acceptable range of 1-65535 (with interval obviously having to be +larger than or equal to duration). If the P2P module is not idle at +the time the Extended Listen Timing timeout occurs, the Listen State +operation will be skipped. + +The configured values will also be advertised to other P2P Devices. The +received values are available in the p2p_peer command output: + +ext_listen_period=100 ext_listen_interval=5000 + +p2p_set <field> <value> + +Change dynamic P2P parameters + +p2p_set discoverability <0/1> + +Disable/enable advertisement of client discoverability. This is +enabled by default and this parameter is mainly used to allow testing +of device discoverability. + +p2p_set managed <0/1> + +Disable/enable managed P2P Device operations. This is disabled by +default. + +p2p_set listen_channel <1/6/11> + +Set P2P Listen channel. This is mainly meant for testing purposes and +changing the Listen channel during normal operations can result in +protocol failures. + +p2p_set ssid_postfix <postfix> + +Set postfix string to be added to the automatically generated P2P SSID +(DIRECT-<two random characters>). For example, postfix of "-testing" +could result in the SSID becoming DIRECT-ab-testing. + +set <field> <value> + +Set global configuration parameters which may also affect P2P +operations. The format on these parameters is same as is used in +wpa_supplicant.conf. Only the parameters listen here should be +changed. Modifying other parameters may result in incorrect behavior +since not all existing users of the parameters are updated. + +set uuid <UUID> + +Set WPS UUID (by default, this is generated based on the MAC address). + +set device_name <device name> + +Set WPS Device Name (also included in some P2P messages). + +set manufacturer <manufacturer> + +Set WPS Manufacturer. + +set model_name <model name> + +Set WPS Model Name. + +set model_number <model number> + +Set WPS Model Number. + +set serial_number <serial number> + +Set WPS Serial Number. + +set device_type <device type> + +Set WPS Device Type. + +set os_version <OS version> + +Set WPS OS Version. + +set config_methods <config methods> + +Set WPS Configuration Methods. + +set sec_device_type <device type> + +Add a new Secondary Device Type. + +set p2p_go_intent <GO intent> + +Set the default P2P GO Intent. Note: This value can be overridden in +p2p_connect command and as such, there should be no need to change the +default value here during normal operations. + +set p2p_ssid_postfix <P2P SSID postfix> + +Set P2P SSID postfix. + +set persistent_reconnect <0/1> + +Disable/enabled persistent reconnect for reinvocation of persistent +groups. If enabled, invitations to reinvoke a persistent group will be +accepted without separate authorization (e.g., user interaction). + +set country <two character country code> + +Set country code (this is included in some P2P messages). + +Status + +p2p_peers [discovered] + +List P2P Device Addresses of all the P2P peers we know. The optional +"discovered" parameter filters out the peers that we have not fully +discovered, i.e., which we have only seen in a received Probe Request +frame. + +p2p_peer <P2P Device Address> + +Fetch information about a known P2P peer. + +Group Status + +(These are used on the group interface.) + +status + +Show status information (connection state, role, use encryption +parameters, IP address, etc.). + +sta + +Show information about an associated station (when acting in AP/GO role). + +all_sta + +Lists the currently associated stations. + +Configuration data + +list_networks + +Lists the configured networks, including stored information for +persistent groups. The identifier in this list is used with +p2p_group_add and p2p_invite to indicate which persistent group is to +be reinvoked. + +remove_network <network id> + +Remove a network entry from configuration. + + +wpa_cli action script +--------------------- + +See examples/p2p-action.sh + +TODO: describe DHCP/DNS setup +TODO: cross-connection |
