EtherRaw.h

// EtherRaw.h
//
/// \mainpage EtherRaw library for Arduino
///
/// This is the EtherRaw library.
/// It provides an object-oriented interface for inspecting Ethernet, IP, ICMP, TCP, UDP and other packets
/// as delivered by Arduino Ethernet Shield, especially in MACRAW or IPRAW modes.
///
/// The latest version of this documentation can be downloaded from 
/// http://www.airspayce.com/mikem/arduino/EtherRaw
///
/// The version of the package that this documentation refers to can be downloaded 
/// from http://www.airspayce.com/mikem/arduino/EtherRaw/EtherRaw-1.0.zip
/// You can find the latest version at http://www.airspayce.com/mikem/arduino/EtherRaw
///
/// \par Installation
/// Install in the usual way: unzip the distribution zip file to the libraries
/// sub-folder of your sketchbook. 
///
/// This software is Copyright (C) 2012 Mike McCauley. Use is subject to license
/// conditions. The main licensing options available are GPL V2 or Commercial:
/// 
/// \par Open Source Licensing GPL V2
/// This is the appropriate option if you want to share the source code of your
/// application with everyone you distribute it to, and you also want to give them
/// the right to share who uses it. If you wish to use this software under Open
/// Source Licensing, you must contribute all your source code to the open source
/// community in accordance with the GPL Version 2 when your application is
/// distributed. See http://www.gnu.org/copyleft/gpl.html
/// 
/// \par Commercial Licensing
/// This is the appropriate option if you are creating proprietary applications
/// and you are not prepared to distribute and share the source code of your
/// application. Contact info@airspayce.com for details.
///
/// \par Revision History
/// \version 1.0 Initial release
/// \version 1.1 Updated author and distribution location details to airspayce.com
///
/// \author  Mike McCauley (mikem@airspayce.com)
// Copyright (C) 2012 Mike McCauley
// $Id: EtherRaw.h,v 1.1 2012/05/30 01:52:08 mikem Exp mikem $

#ifndef EtherRaw_h
#define EtherRaw_h

#include <stdlib.h>
#if ARDUINO >= 100
#include <Arduino.h>
#else
#include <WProgram.h>
#include <wiring.h>
#endif
#include <IPAddress.h>

/////////////////////////////////////////////////////////////////////
/// \class IPv4Address EtherRaw.h <EtherRaw.h>
/// \brief Support for IPv4 addresses
///
/// This class allows easy access to the contents of an IPv4 address
/// in on-the-wire format.
///
/// Sigh, the arduino IPAddress class inherits from Print, and is length 6, not 4
/// so we cant use it in on-the-wire structures. So we define our own similar structure
#define IPV4_ADDRESS_LENGTH 4
struct IPv4Address
{
public:
    /// Constructor.
    /// Clears the address to all zeros
    IPv4Address();

    /// Constructor
    /// Initialise the address from separate octets.
    /// \param[in] octet1 Value for octet 1
    /// \param[in] octet2 Value for octet 2
    /// \param[in] octet3 Value for octet 3
    /// \param[in] octet4 Value for octet 4
    IPv4Address(uint8_t octet1, uint8_t octet2, uint8_t octet3, uint8_t octet4);

    /// Constructor.
    /// Initialise the address from some other array or structure.
    /// \param [in] address Pointer to 4 octets of IPv4 address
    IPv4Address(const uint8_t *address);

    /// Equality operator.
    /// Tests whether 2 addresses are identical.
    /// \param [in] addr The other address
    /// \return true if address is identical to this address
    bool operator==(const IPv4Address& addr);

    /// Equality operator.
    /// Tests whether 2 addresses are identical.
    /// \param [in] addr The other address as some raw array or structure
    /// \return true if address is identical to this address
    bool operator==(const uint8_t* addr);

    /// Assignment operator.
    /// Copies the raw address pointed to by addr to this address.
    /// \param [in] addr The raw address to be used to initialise this address
    /// \return This address
    IPv4Address& operator=(const uint8_t *addr);

    /// Access the raw address 
    /// as an array of octets.
    /// \return The raw address
    const uint8_t* address() const;

private:
    /// The raw address
    uint8_t _address[IPV4_ADDRESS_LENGTH];

};


/////////////////////////////////////////////////////////////////////
/// \class IPv6Address EtherRaw.h <EtherRaw.h>
/// \brief Support for IPv6 addresses
///
/// This class allows easy access to the contents of an IPv6 address
/// in on-the-wire format.
///
#define IPV6_ADDRESS_LENGTH 16
struct IPv6Address
{
public:
    /// Constructor.
    /// Clears the address to all zeros
    IPv6Address();

    /// Constructor.
    /// Initialise the address from some other array or structure.
    /// \param [in] address Pointer to 4 octets of IPv4 address
    IPv6Address(const uint8_t *address);

    /// Equality operator.
    /// Tests whether 2 addresses are identical.
    /// \param [in] addr The other address
    /// \return true if address is identical to this address
    bool operator==(const IPv6Address& addr);

    /// Equality operator.
    /// Tests whether 2 addresses are identical.
    /// \param [in] addr The other address as some raw array or structure
    /// \return true if address is identical to this address
    bool operator==(const uint8_t* addr);

    /// Assignment operator.
    /// Copies the raw address pointed to by addr to this address.
    /// \param [in] addr The raw address to be used to initialise this address
    /// \return This address
    IPv6Address& operator=(const uint8_t *addr);

    /// Access the raw address 
    /// as an array of octets.
    /// \return The raw address
    const uint8_t* address() const;

private:
    /// The raw address
    uint8_t _address[IPV6_ADDRESS_LENGTH];


};

/////////////////////////////////////////////////////////////////////
/// \class MACAddress EtherRaw.h <EtherRaw.h>
/// \brief Support for IPv4 addresses
///
/// This class allows easy access to the contents of a MAC address
/// in on-the-wire format.
///
#define MAC_ADDRESS_LENGTH  6
struct MACAddress
{
public:
    /// Constructor.
    /// Clears the address to all zeros
    MACAddress();

    /// Constructor
    /// Initialise the address from separate octets.
    /// \param[in] octet1 Value for octet 1
    /// \param[in] octet2 Value for octet 2
    /// \param[in] octet3 Value for octet 3
    /// \param[in] octet4 Value for octet 4
    /// \param[in] octet5 Value for octet 5
    /// \param[in] octet6 Value for octet 6
    MACAddress(uint8_t octet1, uint8_t octet2, uint8_t octet3, uint8_t octet4, uint8_t octet5, uint8_t octet6);

    /// Constructor.
    /// Initialise the address from some other array or structure.
    /// \param [in] address Pointer to 6 octets of MAC address
    MACAddress(const uint8_t *address);

    /// Equality operator.
    /// Tests whether 2 addresses are identical.
    /// \param [in] addr The other address
    /// \return true if address is identical to this address
    bool operator==(const MACAddress& addr);

    /// Equality operator.
    /// Tests whether 2 addresses are identical.
    /// \param [in] addr The other address as some raw array or structure
    /// \return true if address is identical to this address
    bool operator==(const uint8_t* addr);

    /// Overloaded index operator.
    /// Allow getting and setting individual octets of the address
    /// \param [in] index The index of the octet to access
    /// \return The value of the indexed octet
    uint8_t operator[](int index) const;

    /// Overloaded index operator.
    /// Allow getting and setting individual octets of the address
    /// \param [in] index The index of the octet to access
    /// \return Reference to the value of the indexed octet
    uint8_t& operator[](int index);

    /// Assignment operator.
    /// Copies the raw address pointed to by addr to this address.
    /// \param [in] addr The raw address to be used to initialise this address
    /// \return This address
    MACAddress& operator=(const uint8_t *addr);

    /// Access the raw address 
    /// as an array of octets.
    /// \return The raw address
    uint8_t* address();

    /// Print.
    /// Prints an ASCII formatted version of the address to a Printable such as Serial.
    /// \return The number of characters printed
    size_t  printTo(Print& p) const;

private:
    /// The raw address
    uint8_t  _address[MAC_ADDRESS_LENGTH];

};

/////////////////////////////////////////////////////////////////////
/// \class EthernetHeader EtherRaw.h <EtherRaw.h>
/// \brief Support for Ethernet Headers
///
/// This class allows easy access to the contents of an Ethernet Header
/// in on-the-wire format.
///
struct EthernetHeader
{
public:
    /// Ethernet Protocol IDs for ethertype
    /// Based on /usr/include/linux/if_ether.h
    typedef enum
    {
        ETH_P_LOOP        = 0x0060,          /// Ethernet Loopback packet
        ETH_P_PUP         = 0x0200,          /// Xerox PUP packet 
        ETH_P_PUPAT       = 0x0201,          /// Xerox PUP Addr Trans packet  
        ETH_P_IP          = 0x0800,          /// Internet Protocol packet     
        ETH_P_X25         = 0x0805,          /// CCITT X.25                   
        ETH_P_ARP         = 0x0806,          /// Address Resolution packet    
        ETH_P_BPQ         = 0x08FF,          /// G8BPQ AX.25 Ethernet Packet
        ETH_P_IEEEPUP     = 0x0a00,          /// Xerox IEEE802.3 PUP packet 
        ETH_P_IEEEPUPAT   = 0x0a01,          /// Xerox IEEE802.3 PUP Addr Trans packet
        ETH_P_DEC         = 0x6000,          /// DEC Assigned proto           
        ETH_P_DNA_DL      = 0x6001,          /// DEC DNA Dump/Load            
        ETH_P_DNA_RC      = 0x6002,          /// DEC DNA Remote Console       
        ETH_P_DNA_RT      = 0x6003,          /// DEC DNA Routing              
        ETH_P_LAT         = 0x6004,          /// DEC LAT                      
        ETH_P_DIAG        = 0x6005,          /// DEC Diagnostics              
        ETH_P_CUST        = 0x6006,          /// DEC Customer use             
        ETH_P_SCA         = 0x6007,          /// DEC Systems Comms Arch       
        ETH_P_TEB         = 0x6558,          /// Trans Ether Bridging         
        ETH_P_RARP        = 0x8035,          /// Reverse Addr Res packet      
        ETH_P_ATALK       = 0x809B,          /// Appletalk DDP                
        ETH_P_AARP        = 0x80F3,          /// Appletalk AARP               
        ETH_P_8021Q       = 0x8100,          /// 802.1Q VLAN Extended Header  
        ETH_P_IPX         = 0x8137,          /// IPX over DIX                 
        ETH_P_IPV6        = 0x86DD,          /// IPv6 over bluebook           
        ETH_P_PAUSE       = 0x8808,          /// IEEE Pause frames. See 802.3 31B 
        ETH_P_SLOW        = 0x8809,          /// Slow Protocol. See 802.3ad 43B 
        ETH_P_WCCP        = 0x883E,          /// Web-cache coordination protocol 
        ETH_P_PPP_DISC    = 0x8863,          /// PPPoE discovery messages     
        ETH_P_PPP_SES     = 0x8864,          /// PPPoE session messages       
        ETH_P_MPLS_UC     = 0x8847,          /// MPLS Unicast traffic         
        ETH_P_MPLS_MC     = 0x8848,          /// MPLS Multicast traffic       
        ETH_P_ATMMPOA     = 0x884c,          /// MultiProtocol Over ATM       
        ETH_P_LINK_CTL    = 0x886c,          /// HPNA, wlan link local tunnel 
        ETH_P_ATMFATE     = 0x8884,          /// Frame-based ATM Transport over Ethernet
        ETH_P_PAE         = 0x888E,          /// Port Access Entity (IEEE 802.1X) 
        ETH_P_AOE         = 0x88A2,          /// ATA over Ethernet            
        ETH_P_8021AD      = 0x88A8,          /// 802.1ad Service VLAN         
        ETH_P_TIPC        = 0x88CA,          /// TIPC                         
        ETH_P_8021AH      = 0x88E7,          /// 802.1ah Backbone Service Tag 
        ETH_P_1588        = 0x88F7,          /// IEEE 1588 Timesync 
        ETH_P_FCOE        = 0x8906,          /// Fibre Channel over Ethernet  
        ETH_P_FIP         = 0x8914,          /// FCoE Initialization Protocol 
        ETH_P_QINQ1       = 0x9100,          /// deprecated QinQ VLAN
        ETH_P_QINQ2       = 0x9200,          /// deprecated QinQ VLAN
        ETH_P_QINQ3       = 0x9300,          /// deprecated QinQ VLAN
        ETH_P_EDSA        = 0xDADA           /// Ethertype DSA
    } EtherType;

    /// Access the source MAC address
    /// \return Reference to the source MAC address.
    MACAddress& source();

    /// Access the destination MAC address
    /// \return Reference to the destination MAC address.
    MACAddress& dest();

    /// Access the EtherType.
    /// \return one of EtherType values in native host endianness
    uint16_t  ethertype() const;

    /// Access the payload of the packet.
    /// \return Pointer to the payload data following the MAC Header
    uint8_t*  payload();

    /// Print.
    /// Prints an ASCII formatted version of the header to a Printable such as Serial.
    /// \return The number of characters printed
    size_t    printTo(Print& p) const;

private:
    /// Destination MAC address
    MACAddress  _dest;  

    /// Source MAC address
    MACAddress  _source;

    // Optional 802.1Q header here? 4 octets

    /// EtherType in network byte order
    uint16_t    _ethertype; 

    /// Following data
    uint8_t     _data[0];
};

/////////////////////////////////////////////////////////////////////
/// \class PacketICMP EtherRaw.h <EtherRaw.h>
/// \brief Support for ICMP Packet Headers
///
/// This class allows easy access to the contents of an ICMP Packet
/// in on-the-wire format.
///
/// This implementation is incomplete.
///
struct PacketICMP
{
public:

private:
    uint8_t      _type;
    uint8_t      _code;
    uint16_t     _checksum;
    uint16_t     _id;
    uint16_t     _seqnum;
    uint8_t      _data[0];
};

/////////////////////////////////////////////////////////////////////
/// \class PacketIPv4 EtherRaw.h <EtherRaw.h>
/// \brief Support for IP PAcket Headers
///
/// This class allows easy access to the contents of an IP Packet Header
/// in on-the-wire format.
///
struct PacketIPv4
{
public:

// Defines from /usr/include/linux/ip.h
#define IPTOS_TOS_MASK          0x1E
#define IPTOS_TOS(tos)          ((tos)&IPTOS_TOS_MASK)
#define IPTOS_LOWDELAY          0x10
#define IPTOS_THROUGHPUT        0x08
#define IPTOS_RELIABILITY       0x04
#define IPTOS_MINCOST           0x02

#define IPTOS_PREC_MASK         0xE0
#define IPTOS_PREC(tos)         ((tos)&IPTOS_PREC_MASK)
#define IPTOS_PREC_NETCONTROL           0xe0
#define IPTOS_PREC_INTERNETCONTROL      0xc0
#define IPTOS_PREC_CRITIC_ECP           0xa0
#define IPTOS_PREC_FLASHOVERRIDE        0x80
#define IPTOS_PREC_FLASH                0x60
#define IPTOS_PREC_IMMEDIATE            0x40
#define IPTOS_PREC_PRIORITY             0x20
#define IPTOS_PREC_ROUTINE              0x00

/* IP options */
#define IPOPT_COPY              0x80
#define IPOPT_CLASS_MASK        0x60
#define IPOPT_NUMBER_MASK       0x1f

#define IPOPT_COPIED(o)         ((o)&IPOPT_COPY)
#define IPOPT_CLASS(o)          ((o)&IPOPT_CLASS_MASK)
#define IPOPT_NUMBER(o)         ((o)&IPOPT_NUMBER_MASK)

#define IPOPT_CONTROL           0x00
#define IPOPT_RESERVED1         0x20
#define IPOPT_MEASUREMENT       0x40
#define IPOPT_RESERVED2         0x60

#define IPOPT_END       (0 |IPOPT_CONTROL)
#define IPOPT_NOOP      (1 |IPOPT_CONTROL)
#define IPOPT_SEC       (2 |IPOPT_CONTROL|IPOPT_COPY)
#define IPOPT_LSRR      (3 |IPOPT_CONTROL|IPOPT_COPY)
#define IPOPT_TIMESTAMP (4 |IPOPT_MEASUREMENT)
#define IPOPT_CIPSO     (6 |IPOPT_CONTROL|IPOPT_COPY)
#define IPOPT_RR        (7 |IPOPT_CONTROL)
#define IPOPT_SID       (8 |IPOPT_CONTROL|IPOPT_COPY)
#define IPOPT_SSRR      (9 |IPOPT_CONTROL|IPOPT_COPY)
#define IPOPT_RA        (20|IPOPT_CONTROL|IPOPT_COPY)

#define IPVERSION       4
#define MAXTTL          255
#define IPDEFTTL        64

#define IPOPT_OPTVAL 0
#define IPOPT_OLEN   1
#define IPOPT_OFFSET 2
#define IPOPT_MINOFF 4
#define MAX_IPOPTLEN 40
#define IPOPT_NOP IPOPT_NOOP
#define IPOPT_EOL IPOPT_END
#define IPOPT_TS  IPOPT_TIMESTAMP

#define IPOPT_TS_TSONLY         0               /// timestamps only
#define IPOPT_TS_TSANDADDR      1               /// timestamps and addresses
#define IPOPT_TS_PRESPEC        3               /// specified modules only

    /// Definitions of protocol number for protocol()
    typedef enum
    {
        IPPROTO_IP = 0,        /// Dummy protocol for TCP.  
        IPPROTO_HOPOPTS = 0,   /// IPv6 Hop-by-Hop options.  
        IPPROTO_ICMP = 1,      /// Internet Control Message Protocol.  
        IPPROTO_IGMP = 2,      /// Internet Group Management Protocol. 
        IPPROTO_IPIP = 4,      /// IPIP tunnels (older KA9Q tunnels use 94).  
        IPPROTO_TCP = 6,       /// Transmission Control Protocol.  
        IPPROTO_EGP = 8,       /// Exterior Gateway Protocol.  
        IPPROTO_PUP = 12,      /// PUP protocol.  
        IPPROTO_UDP = 17,      /// User Datagram Protocol.  
        IPPROTO_IDP = 22,      /// XNS IDP protocol.  
        IPPROTO_TP = 29,       /// SO Transport Protocol Class 4.  
        IPPROTO_DCCP = 33,     /// Datagram Congestion Control Protocol.  
        IPPROTO_IPV6 = 41,     /// IPv6 header.  
        IPPROTO_ROUTING = 43,  /// IPv6 routing header.  
        IPPROTO_FRAGMENT = 44, /// IPv6 fragmentation header.  
        IPPROTO_RSVP = 46,     /// Reservation Protocol.  
        IPPROTO_GRE = 47,      /// General Routing Encapsulation.  
        IPPROTO_ESP = 50,      /// encapsulating security payload.  
        IPPROTO_AH = 51,       /// authentication header.  
        IPPROTO_ICMPV6 = 58,   /// ICMPv6.  
        IPPROTO_NONE = 59,     /// IPv6 no next header.  
        IPPROTO_DSTOPTS = 60,  /// IPv6 destination options.  
        IPPROTO_MTP = 92,      /// Multicast Transport Protocol.  
        IPPROTO_ENCAP = 98,    /// Encapsulation Header.  
        IPPROTO_PIM = 103,     /// Protocol Independent Multicast.  
        IPPROTO_COMP = 108,    /// Compression Header Protocol.  
        IPPROTO_SCTP = 132,    /// Stream Control Transmission Protocol.  
        IPPROTO_UDPLITE = 136, /// UDP-Lite protocol.  
        IPPROTO_RAW = 255,     /// Raw IP packets.  
        IPPROTO_MAX
    } IPProto;
    
    /// Access the packet header version.
    /// \return The header version 
    uint8_t version() const;

    /// Access the packet header len.
    /// \return The header length in 32bit words
    uint8_t headerlen() const;

    /// Access the service type (also called TOS).
    /// \return The service type, one of IPTOS_*
    uint8_t service() const;

    /// Access the packet precendence.
    /// \return The precendence
    uint8_t precedence() const;

    /// Access the packet length
    /// \return The total packet length including payload and header in native byte order.
    uint16_t length() const;

    /// Access the packet ID.
    /// \return The packet ID in native byte order.
    uint16_t id() const;

    /// Access the packet flags
    /// \return The packet flags
    uint8_t flags() const;

    /// Access the packet fragment offset
    /// \return The packet fragment offset  in native byte order.
    uint16_t offset() const;

    /// Access the packet time-to-live.
    /// \return the packet time-to-live.
    uint8_t ttl() const;

    /// Access the packet protocol
    /// \return The packet protocol, one of IPProto.
    uint8_t protocol() const;

    /// Access the source IP address
    /// \return A reference to the source address
    const IPv4Address& source() const;

    /// Access the destination IP address
    /// \return A reference to the destination address
    const IPv4Address& dest() const;

    /// Access the packet checksum
    /// return the checksum in native byte order.
    uint16_t checksum() const;

    /// Access the packet payload
    /// \return A pointer to the packet payload data
    uint8_t*  payload();

    /// Print.
    /// Prints an ASCII formatted version of the header to a Printable such as Serial.
    /// \return The number of characters printed
    size_t    printTo(Print& p) const;

private:
    uint8_t      _verslen;
    uint8_t      _service;
    uint16_t     _length;
    uint16_t     _id;
    uint16_t     _flags_offset;
    uint8_t      _ttl;
    uint8_t      _protocol;
    uint16_t     _checksum;
    IPv4Address  _source;
    IPv4Address  _dest;
    uint8_t      _options[0]; // payload follows

};

/////////////////////////////////////////////////////////////////////
/// \class PacketTCP EtherRaw.h <EtherRaw.h>
/// \brief Support for TCP Packet Headers
///
/// This class allows easy access to the contents of a TCP Packet
/// in on-the-wire format.
///
struct PacketTCP
{
    /// Masks for code bits returned by code()
    typedef enum
    {
        URG = 0x20,
        ACK = 0x10,
        PSH = 0x08,
        RST = 0x04,
        SYN = 0x02,
        FIN = 0x01
    } TCPCode;

public:
    /// Access the source port number
    /// \return The source port number in native byte order.
    uint16_t  sourcePort() const;

    /// Access the destination port number
    /// \return The destination port number in native byte order.
    uint16_t  destPort() const;
    
    /// Access the TCP sequence number
    /// \return The TCP sequence number in native byte order.
    uint32_t  sequence() const;

    /// Access the TCP acknowledgement number
    /// \return The TCP acknowledgement number in native byte order.
    uint32_t  acknowledgement() const;

    /// Access the header length
    /// \return The header length in 32bit words
    uint8_t   headerlen() const;

    /// Access the packet code bits
    /// \return the code bits a mask of TCPCode
    uint8_t   code() const;

    /// Access the TCP window
    /// \return the window in native byte order.
    uint16_t  window() const;

    /// Access the TCP checksum
    /// \return the checksum in native byte order.
    uint16_t  checksum() const;

    /// Access the TCP urgent pointer
    /// \return the urgent pointer in native byte order.
    uint16_t  urgent() const;

    /// Access the packet payload
    /// \return A pointer to the TCP packet payload data
    uint8_t*  payload();

    /// Print.
    /// Prints an ASCII formatted version of the header to a Printable such as Serial.
    /// \return The number of characters printed
    size_t    printTo(Print& p) const;

private:
    uint16_t     _sourcePort;
    uint16_t     _destPort;
    uint32_t     _sequence;
    uint32_t     _acknowledgement;
    uint16_t     _hlen_code;
    uint16_t     _window;
    uint16_t     _checksum;
    uint16_t     _urgent;
    uint8_t      _options[0]; // payload follows

};

/////////////////////////////////////////////////////////////////////
/// \class PacketUDP EtherRaw.h <EtherRaw.h>
/// \brief Support for UDP Packet Headers
///
/// This class allows easy access to the contents of a UDP Packet
/// in on-the-wire format.
///
struct PacketUDP
{
    /// Access the source port number
    /// \return The source port number in native byte order.
    uint16_t sourcePort() const;

    /// Access the destination port number
    /// \return The destination port number in native byte order.
    uint16_t destPort() const;

    /// Access the packet length.
    /// \return The total packet length (including header and payload) in native byte order.
    uint16_t length() const;

    /// Access the UDP checksum
    /// \return the checksum in native byte order.
    uint16_t checksum() const;

    /// Access the packet payload
    /// \return A pointer to the TCP packet payload data
    uint8_t*  payload();

    /// Access thepayload length
    /// \return the payload length in native byte order.
    uint16_t  payload_length();

    /// Print.
    /// Prints an ASCII formatted version of the header to a Printable such as Serial.
    /// \return The number of characters printed
    size_t    printTo(Print& p) const;

private:
    uint16_t     _sourcePort;
    uint16_t     _destPort;
    uint16_t     _length;
    uint16_t     _checksum;
    uint8_t      _data[0];

};

#endif