===============================================================================
    $Id: README,v 1.1.1.1 2002/05/02 21:27:16 root Exp $
    RADIATE 0.2 (c) 2002 Mike D. Schiffman <mike@infonexus.com>
                         Tim Newsham <tnewsham@stake.com>
===============================================================================

    RADIDATE README

    A C library for 802.11 frame reading, creation and injection.
 
    Radiate is a small C library designed read, build and write 802.11
    frames.  As of version 0.2, Radiate only works on linux based systems
    and needs the following:

    - A laptop with an 802.11b wireless card with an Intersil Prism 2
      chipset (SMC, D-link, etc).

    - A linux 2.4.x kernel (2.4.7 was verified to work, but later versions
      *should work*).  We also recommend redhat-7.x.

    - The ssh.com Prism2 host AP drivers (included).  If a new version
      is available from http://people.ssh.com/jkm/Prism2/ you might want
      to try that.

    * Libnet 1.1.x is optional but recommended.


    Follow the below instructions to get Radiate installed and working.

    1) Installing the Driver Module

    A copy of the driver is in the directory:

        ./kernel/Prism2-2002-04-24

    which is verbatim from the web site.  This driver should be built on a
    2.4.x kernel.

    The driver depends on some support from the kernel and the pcmcia
    subsystem.  We're using redhat 7.1 which has the pcmcia subsystem
    built into the kernel.  Additionally, the following kernel options
    need to be built:

        "Network device support" --> "Wireless LAN (non-hamradio)" -->
        "Wireless LAN"

        "Networking options" --> "Kernel/User netlink socket"

    Rebuild your kernel and reboot.

    Next, the kernel module for the device should be built and installed.
    Follow the instructions provided with the driver code.

    This should build and install the module in the proper directory.  If
    depmode reports there are unresolved symbols, you probably forgot to build
    your kernel with the correct options or you didn't boot to the new kernel.

    This also adds some config files to the /etc/pcmcia directory so you should
    restart the pcmcia subsystem:

        # /etc/init.d/pcmcia restart

    and then insert the prism2 card.  Make sure that the "prism2" driver gets 
    loaded:

        # lsmod
        Module                  Size  Used by
        hostap_cs              75664   0  (unused)

    If another older driver gets loaded instead, remove that driver from the 
    pcmcia config files in /etc/pcmcia.

    Once the driver is in place, make sure you can see the card:

        # iwconfig wlan0

    and test monitoring mode to make sure it works by running:

        # ./Libradiate-0.02/scripts/set_monitor.sh 1

    and building and running "wlansniff" in the "sniff" directory.


    2) Frame Injection and Reading

    Before using programs built on top of radiate, be sure to set the
    card into monitor mode with the "set_monitor" script (optionally you
    can use the radiate_set_mm() function -- see the manpage).

    The driver uses a common interface for reading and injecting frames.  
    First a netlink socket is created to communicate with the driver.
    Then, to monitor, read(), recv() or recvfrom() is used to get frames.  
    To inject, a write(), send() or sendto() is used.  Both of these 
    operations works on a buffer with a pseudo-header.

    When reading a frame, the following pseudo-header is attached to each 
    buffer by the card's firmware:

        /* HFA384X RX frame descriptor */
        u16 status __attribute__ ((packed));
        u32 time __attribute__ ((packed));
        u8 silence __attribute__ ((packed));
        u8 signal __attribute__ ((packed));
        u8 rate __attribute__ ((packed));
        u8 rxflow __attribute__ ((packed));
        u32 reserved __attribute__ ((packed));

        /* 802.11 */
        u16 frame_control __attribute__ ((packed));
        u16 duration_id __attribute__ ((packed));
        u8 addr1[6] __attribute__ ((packed));
        u8 addr2[6] __attribute__ ((packed));
        u8 addr3[6] __attribute__ ((packed));
        u16 seq_ctrl __attribute__ ((packed));
        u8 addr4[6] __attribute__ ((packed));
        u16 data_len __attribute__ ((packed));

        /* 802.3 */
        u8 dst_addr[6] __attribute__ ((packed));
        u8 src_addr[6] __attribute__ ((packed));
        u16 len __attribute__ ((packed));

    When transmitting a frame, the following pseudo-header should be
    prepended to the buffer:

        /* HFA384X TX frame descriptor */
        u16 status __attribute__ ((packed));
        u16 reserved1 __attribute__ ((packed));
        u16 reserved2 __attribute__ ((packed));
        u32 sw_support __attribute__ ((packed));
        u8 retry_count __attribute__ ((packed));
        u8 tx_rate __attribute__ ((packed));
        u16 tx_control __attribute__ ((packed));

        /* 802.11 */
        u16 frame_control __attribute__ ((packed)); /* parts not used */
        u16 duration_id __attribute__ ((packed));
        u8 addr1[6] __attribute__ ((packed));
        u8 addr2[6] __attribute__ ((packed));       /* not used */
        u8 addr3[6] __attribute__ ((packed));
        u16 seq_ctrl __attribute__ ((packed));      /* not used */
        u8 addr4[6] __attribute__ ((packed));
        u16 data_len __attribute__ ((packed));

        /* 802.2? */
        u8 dst_addr[6] __attribute__ ((packed));
        u8 src_addr[6] __attribute__ ((packed));
        u16 len __attribute__ ((packed));

    The buffer will contain any payload after the pseudo-header.  Note that
    these pseudo-headers contain all of the 802.11 header fields, but not 
    necessarily in the same format as it will appear when transmitted.
    In particular, it appears as though certain fields are set by the
    firmware and cannot be changed including sequence number and
    fragmentation information.

    Multi-precision fields should be represented in little-endian.

    The driver is picky about frames it will transmit.  If a malformed
    header is passed in, the driver may return success for writing, but the 
    driver wont actually transmit the frame.  When this happens, the driver 
    outputs debugging information to the kernel log, to check on this use
    "dmesg".  Also it appears that sometimes a frame that is queued for
    writing never gets written out.  Consider this library to be in early
    beta.  Sometimes it crashes my machine.  Duplicate frames can be sent
    as necessary.  Also take care to put all fields into little-endian
    order before calling these functions.  The macros:

        le_to_host16 
        le_to_host32

    and

        host_to_le16
        host_to_le32

    are provided for flipping endian to and from little endian.

EOF
