#
# Copyright (C) 2009, 2010 by orange <orange@piranha.pwnz.org>
#
# This is free software, licensed under the GNU General Public License v2 as published by
# the Free Software Foundation, http://www.gnu.org/licenses/gpl-2.0.html
#

### Notice ###
This documentation applies to AAP 2.0 snapshot releases only. AAP legacy isn't maintained any longer.
AAP is exclusively distributed as part of the Piranha firmware.

### Definition ###
AAP (aka AutoAP) is a script that enables users of OpenWrt Kamikaze to automatically log into
different wireless access points that provide internet access. The access points can be automatically
searched and/or set in a whitelist (/aap/aap_wlst). Beyond that AAP is capable in defining a blacklist
of undesired access points while connecting (/aap/aap_blst). AAP supports the client connection of
an OpenWrt Kamikaze device to open, wep, wpa-psk and wpa2-psk encrypted access points. AAP selects
surrounding access points utilizing their MAC addresses. This ensures a high level of differentiation
between access points in contrast to a SSID-based selection. MAC spoofing of valid client MACs upon
connection attempts to APs with enabled MAC filtering is supported by utilizing /aap/aap_mlst. As of
AAP 2.0 100227, AAP is capable to connect to hidden SSIDs utilizing /aap/aap_hlst.

### Whitelist/Blacklist ###
/aap/aap_wlst is a newline-separated whitelist of preferred access points.
Definition is as follows:
00:11:22:33:44:55 for APs without encryption
00:11:22:33:44:55	key for APs with wep, wpa-psk or wpa2-psk encryption (tab delimiter)

/aap/aap_blst is a newline-separated blacklist of undesired access points.
Definition is as follows:
00:11:22:33:44:55 for open, wep, wpa-psk and wpa2-psk encrypted APs

### MAC Spoofing ###
/aap/aap_mlst is a newline-separated list of access points with enabled MAC filtering and valid client MACs.
You may define one valid client MAC per AP:
00:11:22:33:44:55	00:11:22:33:44:55 (format: apmac	clientmac, tab delimiter)

### Hidden SSIDs (as of AAP 2.0 100227) ###
/aap/aap_hlst is a newline-separated list of access points with hidden SSIDs
You may define one BSSID, SSID pair per AP:
00:11:22:33:44:55	foobar (format: apmac	ssid, tab delimiter)

### Configuration Variables ###
/aap/aap.sh provides configuration variables and toggles (with default values) at the top of the script:
# Connection check frequency in seconds
aap_checkfreq=60

# Length of time in seconds to wait for a DHCP request to succeed
aap_dhcptimeout=60 (30 prior AAP 2.0 100217)

# Internet URL or IP address used to ping (to ensure internet access is working)
aap_ineturl=www.google.com

# Defines the access point refresh scan delay in seconds (divisible by 5)
aap_rescandelay=43200

# Defines the refresh scan delay in seconds between empty (re-)scan results (no APs found in range)
aap_warndelay=120

# Defines whether or not logging to syslog is enabled. "1"=YES, "0"=NO
toggle_logenable=1

# Defines the search mode. Whether AAP tries to connect to open access points not defined in /aap/aap_wlst
or not. "0"=YES, "1"=NO
toggle_prefonly=0

# Defines whether to ping aap_ineturl (or alternatively the local WAN Gateway). "1"=YES, "0"=NO
toggle_watchinet=1

### Usage ###
Daily usage of AAP is as simple as:
root@OpenWrt:~# aap {start|stop|restart|log|list|skip} (list/skip as of AAP 2.0 100227)
To enable/disable autostart of AAP, you need to (un-)comment "/aap/aap.sh &" in /etc/rc.local

### Known Issues ###
/aap/aap_wlst, /aap/aap_blst, /aap/aap_mlst and /aap/aap_hlst need to be non-empty files due to the behaviour
of the busybox builtin grep. Thus, please leave these files as provided (if you don't use particular features)
and just append your custom newline-separated entries if actually in use.

### Warning ###
Use AAP at your own risk! If you brick your device using AAP, nobody is to blame but yourself.