1 files changed, 315 insertions, 0 deletions
diff --git a/doc/code_structure.doxygen b/doc/code_structure.doxygen
new file mode 100644
index 000000000000..454f179753d3
--- /dev/null
+++ b/doc/code_structure.doxygen
@@ -0,0 +1,315 @@
+/**
+\page code_structure Structure of the source code
+
+[ \ref _wpa_supplicant_core "wpa_supplicant core functionality" |
+\ref generic_helper_func "Generic helper functions" |
+\ref crypto_func "Cryptographic functions" |
+\ref tls_func "TLS library" |
+\ref configuration "Configuration" |
+\ref ctrl_iface "Control interface" |
+\ref wpa_code "WPA supplicant" |
+\ref eap_peer "EAP peer" |
+\ref eapol_supp "EAPOL supplicant" |
+\ref win_port "Windows port" |
+\ref test_programs "Test programs" ]
+
+wpa_supplicant implementation is divided into number of independent
+modules. Core code includes functionality for controlling the network
+selection, association, and configuration. Independent modules include
+WPA code (key handshake, PMKSA caching, pre-authentication), EAPOL
+state machine, and EAP state machine and methods. In addition, there
+are number of separate files for generic helper functions.
+
+Both WPA and EAPOL/EAP state machines can be used separately in other
+programs than wpa_supplicant. As an example, the included test
+programs eapol_test and preauth_test are using these modules.
+
+\ref driver_wrapper "Driver interface API" is defined in \ref driver.h and
+all hardware/driver dependent functionality is implemented in
+driver_*.c.
+
+
+\section _wpa_supplicant_core wpa_supplicant core functionality
+
+\ref wpa_supplicant.c
+	Program initialization, main control loop
+
+\ref wpa_supplicant/main.c
+	main() for UNIX-like operating systems and MinGW (Windows); this
+	uses command line arguments to configure wpa_supplicant
+
+\ref events.c
+	Driver event processing; \ref wpa_supplicant_event() and related functions
+
+\ref wpa_supplicant_i.h
+	Internal definitions for wpa_supplicant core; should not be
+	included into independent modules
+
+
+\section generic_helper_func Generic helper functions
+
+wpa_supplicant uses generic helper functions some of which are shared
+with with hostapd. The following C files are currently used:
+
+\ref eloop.c and \ref eloop.h
+	Event loop (select() loop with registerable timeouts, socket read
+	callbacks, and signal callbacks)
+
+\ref common.c and \ref common.h
+	Common helper functions
+
+\ref defs.h
+	Definitions shared by multiple files
+
+\ref l2_packet.h, \ref l2_packet_linux.c, and \ref l2_packet_pcap.c
+	Layer 2 (link) access wrapper (includes native Linux implementation
+	and wrappers for libdnet/libpcap). A new l2_packet implementation
+	may need to be added when porting to new operating systems that are
+	not supported by libdnet/libpcap. Makefile can be used to select which
+	l2_packet implementation is included. \ref l2_packet_linux.c uses Linux
+	packet sockets and \ref l2_packet_pcap.c has a more portable version using
+	libpcap and libdnet.
+
+\ref pcsc_funcs.c and \ref pcsc_funcs.h
+	Wrapper for PC/SC lite SIM and smart card readers
+
+\ref priv_netlink.h
+	Private version of netlink definitions from Linux kernel header files;
+	this could be replaced with C library header file once suitable
+	version becomes commonly available
+
+\ref version.h
+	Version number definitions
+
+
+\section crypto_func Cryptographic functions
+
+\ref md5.c and \ref md5.h
+	MD5 (replaced with a crypto library if TLS support is included)
+	HMAC-MD5 (keyed checksum for message authenticity validation)
+
+\ref rc4.c and \ref rc4.h
+	RC4 (broadcast/default key encryption)
+
+\ref sha1.c and \ref sha1.h
+	SHA-1 (replaced with a crypto library if TLS support is included)
+	HMAC-SHA-1 (keyed checksum for message authenticity validation)
+	PRF-SHA-1 (pseudorandom (key/nonce generation) function)
+	PBKDF2-SHA-1 (ASCII passphrase to shared secret)
+	T-PRF (for EAP-FAST)
+	TLS-PRF (RFC 2246)
+
+\ref sha256.c and \ref sha256.h
+	SHA-256 (replaced with a crypto library if TLS support is included)
+
+\ref aes-wrap.c, \ref aes_wrap.h, \ref aes.c
+	AES (replaced with a crypto library if TLS support is included),
+	AES Key Wrap Algorithm with 128-bit KEK, RFC3394 (broadcast/default
+	key encryption),
+	One-Key CBC MAC (OMAC1) hash with AES-128,
+	AES-128 CTR mode encryption,
+	AES-128 EAX mode encryption/decryption,
+	AES-128 CBC
+
+\ref crypto.h
+	Definition of crypto library wrapper
+
+\ref crypto_openssl.c
+	Wrapper functions for libcrypto (OpenSSL)
+
+\ref crypto_internal.c
+	Wrapper functions for internal crypto implementation
+
+\ref crypto_gnutls.c
+	Wrapper functions for libgcrypt (used by GnuTLS)
+
+\ref ms_funcs.c and \ref ms_funcs.h
+	Helper functions for MSCHAPV2 and LEAP
+
+\ref tls.h
+	Definition of TLS library wrapper
+
+\ref tls_none.c
+	Dummy implementation of TLS library wrapper for cases where TLS
+	functionality is not included.
+
+\ref tls_openssl.c
+	TLS library wrapper for openssl
+
+\ref tls_internal.c
+	TLS library for internal TLS implementation
+
+\ref tls_gnutls.c
+	TLS library wrapper for GnuTLS
+
+
+\section tls_func TLS library
+
+\ref asn1.c and \ref asn1.h
+	ASN.1 DER parsing
+
+\ref bignum.c and \ref bignum.h
+	Big number math
+
+\ref rsa.c and \ref rsa.h
+	RSA
+
+\ref x509v3.c and \ref x509v3.h
+	X.509v3 certificate parsing and processing
+
+\ref tlsv1_client.c, \ref tlsv1_client.h
+	TLSv1 client (RFC 2246)
+
+\ref tlsv1_client_i.h
+	Internal structures for TLSv1 client
+
+\ref tlsv1_client_read.c
+	TLSv1 client: read handshake messages
+
+\ref tlsv1_client_write.c
+	TLSv1 client: write handshake messages
+
+\ref tlsv1_common.c and \ref tlsv1_common.h
+	Common TLSv1 routines and definitions
+
+\ref tlsv1_cred.c and \ref tlsv1_cred.h
+	TLSv1 credentials
+
+\ref tlsv1_record.c and \ref tlsv1_record.h
+	TLSv1 record protocol
+
+
+\section configuration Configuration
+
+\ref config_ssid.h
+	Definition of per network configuration items
+
+\ref config.h
+	Definition of the wpa_supplicant configuration
+
+\ref config.c
+	Configuration parser and common functions
+
+\ref wpa_supplicant/config_file.c
+	Configuration backend for text files (e.g., wpa_supplicant.conf)
+
+\ref config_winreg.c
+	Configuration backend for Windows registry
+
+
+\section ctrl_iface Control interface
+
+wpa_supplicant has a \ref ctrl_iface_page "control interface"
+that can be used to get status
+information and manage operations from external programs. An example
+command line interface (wpa_cli) and GUI (wpa_gui) for this interface
+are included in the wpa_supplicant distribution.
+
+\ref wpa_supplicant/ctrl_iface.c and \ref wpa_supplicant/ctrl_iface.h
+	wpa_supplicant-side of the control interface
+
+\ref ctrl_iface_unix.c
+	UNIX domain sockets -based control interface backend
+
+\ref ctrl_iface_udp.c
+	UDP sockets -based control interface backend
+
+\ref ctrl_iface_named_pipe.c
+	Windows named pipes -based control interface backend
+
+\ref wpa_ctrl.c and \ref wpa_ctrl.h
+	Library functions for external programs to provide access to the
+	wpa_supplicant control interface
+
+\ref wpa_cli.c
+	Example program for using wpa_supplicant control interface
+
+
+\section wpa_code WPA supplicant
+
+\ref wpa.c and \ref wpa.h
+	WPA state machine and 4-Way/Group Key Handshake processing
+
+\ref preauth.c and \ref preauth.h
+	PMKSA caching and pre-authentication (RSN/WPA2)
+
+\ref wpa_i.h
+	Internal definitions for WPA code; not to be included to other modules.
+
+\section eap_peer EAP peer
+
+\ref eap_peer_module "EAP peer implementation" is a separate module that
+can be used by other programs than just wpa_supplicant.
+
+\ref eap.c and \ref eap.h
+	EAP state machine and method interface
+
+\ref eap_defs.h
+	Common EAP definitions
+
+\ref eap_i.h
+	Internal definitions for EAP state machine and EAP methods; not to be
+	included in other modules
+
+\ref eap_sim_common.c and \ref eap_sim_common.h
+	Common code for EAP-SIM and EAP-AKA
+
+\ref eap_tls_common.c and \ref eap_tls_common.h
+	Common code for EAP-PEAP, EAP-TTLS, and EAP-FAST
+
+\ref eap_ttls.c and \ref eap_ttls.h
+	EAP-TTLS
+
+\ref eap_pax.c, \ref eap_pax_common.h, \ref eap_pax_common.c
+	EAP-PAX
+
+\ref eap_psk.c, \ref eap_psk_common.h, \ref eap_psk_common.c
+	EAP-PSK (note: this is not needed for WPA-PSK)
+
+\ref eap_sake.c, \ref eap_sake_common.h, \ref eap_sake_common.c
+	EAP-SAKE
+
+\ref eap_gpsk.c, \ref eap_gpsk_common.h, \ref eap_gpsk_common.c
+	EAP-GPSK
+
+\ref eap_aka.c, \ref eap_fast.c, \ref eap_gtc.c, \ref eap_leap.c,
+\ref eap_md5.c, \ref eap_mschapv2.c, \ref eap_otp.c, \ref eap_peap.c,
+\ref eap_sim.c, \ref eap_tls.c
+	Other EAP method implementations
+
+
+\section eapol_supp EAPOL supplicant
+
+\ref eapol_supp_sm.c and \ref eapol_supp_sm.h
+	EAPOL supplicant state machine and IEEE 802.1X processing
+
+
+\section win_port Windows port
+
+\ref ndis_events.c
+	Code for receiving NdisMIndicateStatus() events and delivering them to
+	wpa_supplicant \ref driver_ndis.c in more easier to use form
+
+\ref win_if_list.c
+	External program for listing current network interface
+
+
+\section test_programs Test programs
+
+\ref radius_client.c and \ref radius_client.h
+	RADIUS authentication client implementation for eapol_test
+
+\ref radius.c and \ref radius.h
+	RADIUS message processing for eapol_test
+
+\ref eapol_test.c
+	Standalone EAP testing tool with integrated RADIUS authentication
+	client
+
+\ref preauth_test.c
+	Standalone RSN pre-authentication tool
+
+\ref wpa_passphrase.c
+	WPA ASCII passphrase to PSK conversion
+
+*/