# design-principles.h

Go to the documentation of this file.
00001 /*
00002  * design-principles.h
00003  *
00004  * Bogus header file for doxygen documentation.
00005  *
00006  * Don't use this file!
00007  */
00008
00009 ////////////////////////////////////////////////////////////////////////////////
00010 ///
00011 /// \ingroup aesop_lib
00012 /// \defgroup princip General Design Principles
00013 ///
00014 /// These are the general principles guiding the design and implemenetation of
00015 /// the AESOP framework.
00016 ///
00017 /// \n
00018 /// For general principles (and coding standards), see the Wavepacket Library.
00019 /// http://wavepacket-lib.sourceforge.net/group__princip__guide.html
00020 ///
00021 ////////////////////////////////////////////////////////////////////////////////
00022
00023
00024 ////////////////////////////////////////////////////////////////////////////////
00025 ///
00026 /// \ingroup princip
00027 /// \defgroup network_principles Networking Principles
00028 ///
00029 /// These are the principles around networking.
00030 ///
00031 /// \n
00032 /// These are general principles to keep in mind when thinking about the
00033 /// networking layer.  These guided the existing design.
00034 ///
00035 /// <b>Networking Principles:</b>
00036 ///
00037 /// - Do not assume long-lived connections.  Instead, assume that the network
00038 ///     is busy and flaky.  You won't get much bandwidth, and any connections
00039 ///     you do make will be dropped frequently.  Don't build any component that
00040 ///     relies on long-lived connections.  Connection dropping and re-
00041 ///     establishment should be transparent to the player.
00042 ///
00043 /// - Assume messages will be lost.  The client and server will do their best
00044 ///     to deliver messages, but software and hardware layers along with other
00045 ///     factors such as competing traffic will mean that many messages will
00046 ///     be lost.  Never assume that if you send a message that the other party
00047 ///     will hear it!  Protocols and behaviors should ensure that the
00048 ///     system (server and all clients) catch up eventually.
00049 ///
00050 /// - Assume messages will arrive out of order.  We already mentioned that
00051 ///     many messages will be lost.  For those that do arrive, assume that some
00052 ///     of them will arrive in a different order than they were sent.
00053 ///
00054 /// - Assume the network is being inspected.  That is, there are people
00055 ///     watching all packets going in and out of the client and server.  No
00056 ///     personal or private information should be sent in clear text.
00057 ///
00058 /// - Assume clients are malicious.  In practice, I doubt this is a system
00059 ///     worth hacking.  But any code reading data off the network should
00060 ///     assume that a hacker is trying to take advantage of the system.  For
00061 ///     example, you should assume that remote hosts:
00062 ///   - will attempt to cheat (this only applies to clients).  For instance,
00063 ///       clients will attempt to provide inaccurate position information,
00064 ///       or claim they always have more ammunition, etc.  Never allow a
00065 ///       client to be able to cheat about anything.
00066 ///   - will spawn Denial of Service (DOS) attacks by sending many commands
00067 ///       that are expensive for the local host to deal with.
00068 ///   - will send malformed requests to the local host in order to crash it.
00069 ///   - will send malformed requests to hack into the local computer.
00070 ///       This includes:
00071 ///      - attempting to read/write the local filesystem
00072 ///      - attempting to execute local binaries or shell commands
00073 ///      - attempting to cause malicious behavior by buffer overflow
00074 ///
00075 /// The AESOP client and server code is intended to be running on people's
00076 /// machines.  This could include corporate, university, and home networks.
00077 /// This software sends and receives UDP packets, and opens TCP ports.  As such,
00078 /// it is a potential target for hackers and should be extremely secure.  See
00079 /// the security notes at
00080 /// http://wavepacket-lib.sourceforge.net/group__principles.html
00081 ///
00082 /// \n
00083 /// <b>Design Consequences of the Above:</b>
00084 /// - Use UDP datagrams for all state exchanges.  UDP has no connection, so
00085 ///     there isn't a worry about dealing with dropped connections, and we
00086 ///     typically don't need the overhead that comes with a guaranteed
00087 ///     protocol such as TCP.  But this has a consequence:
00088 ///
00089 /// - All state exchange messages should fit in a single physical network
00090 ///     packet.  No message should ever span multiple UDP packets.  The size
00091 ///     of physical network packets can vary (see
00092 ///     http://en.wikipedia.org/wiki/Maximum_transmission_unit) but we
00093 ///     assume a maximum size of 1500 bytes or less.
00094 ///
00095 /// - Any message that needs to span multiple packets (that is, any
00096 ///     message larger than 1500 bytes) should use TCP.  The AESOP
00097 ///     framework will set up TCP connections between the client and
00098 ///     server as a convenience, but these should be rarely used.  At
00099 ///     the moment, these are only used by Conversations (see
00100 ///     \ref conversation).  Any code using TCP should expect the
00101 ///     connection to fail often, and deal with it gracefully.
00102 ///
00103 /// - To deal with dropped messages, no component relies on guaranteed
00104 ///     messages (not even TCP-based components, since the connection could
00105 ///     fail!).  The server holds authoritative state for practicaly
00106 ///     everything, and the client does its best to stay in sync.  The
00107 ///     client is responsible for requesting updated data.  The server is
00108 ///     under no obligation to report interesting state changes.  The client
00109 ///     should occasionally poll etc. to make sure it converges to the
00110 ///     correct state over time.  Put another way: there are no responses
00111 ///     to messages.  If you fire a request or command at a remote host, it
00112 ///     may or may not receive it, and may or may not update its state as a
00113 ///     result, and it certainly won't reply.  If you care about the updated
00114 ///     state, you'll need to poll for
00115 ///     it or wait for a regularly scheduled state update.
00116 ///
00117 /// - To deal with out-of-order messages, all UDP messages have a sequence
00118 ///     number.  When a component (client or server) receives a message
00119 ///     with an older sequence number, the message is simply dropped.  This
00120 ///     happens right away in message processing, so downstream message
00121 ///     parsing code can safely assume they are working on the most recent
00123 ///
00124 /// - To protect against network sniffers (people watching all data
00125 ///     crossing the wire), all sensitive data is encrypted using
00126 ///     standard encryption (see the Wavepacket library cryptography
00127 ///     routines at
00128 ///     http://wavepacket-lib.sourceforge.net/group__crypto.html).  Each host
00129 ///     has its own cryptographic key that is not persisted, so hosts cannot
00130 ///     eavesdrop on traffic
00131 ///     meant for other hosts.
00132 ///
00133 /// - To protect against malicious attacks, these are some of the common
00134 ///     defensive techniques.  These are common to all networked games and
00135 ///     software in general:
00136 ///   - The client is never allowed to be authoritative for interesting
00137 ///       data, and therefore can never "cheat".  The client can only make
00138 ///       requests to the server to change state.  The server is responsible
00139 ///       for taking in requests from client, and making only legitimate
00140 ///       state changes.
00141 ///   - The client and server use network request queues (see
00142 ///       http://wavepacket-lib.sourceforge.net/group__netrq.html) to avoid
00143 ///       having repetitive messages or requests result in excessive
00144 ///       work.  This helps guard against DOS attacks (which will probably be
00145 ///       due to misbehaving clients rather than real DOS hackers).
00146 ///   - All code should carefully inspect incoming messages and aggressively
00147 ///       verify that the data is syntactically or semantically
00148 ///       incorrect.  If invalid, the message should be ignored, or if that
00149 ///       isn't convenient or appropriate, an exception should be thrown.
00150 ///       This way malformed network packets won't cause crashes etc.  In
00151 ///       general, assume every message is malformed or corrupted and parsing
00152 ///       code should be very defensive!
00153 ///   - Use standard security defenses to block hackers.  These include but are
00154 ///       not limited to:
00155 ///       - Not allowing the client to get access to local files/directories.
00156 ///       - Not allowing the client to execute code or get access to a shell.
00157 ///       - Providing a strict, limited vocabulary for all communications and
00158 ///          enforcing it rigorously.
00159 ///       - Always check the size of incoming data (for instance, float or
00160 ///          string arrays) and make sure you can receive it safely.
00161 ///
00162 /// \n
00163 /// There are a lot of good resources out on the Internet about how to build
00164 /// networked games that are fast and secure.  Here are some links that I put
00165 /// together quickly:
00166 ///  - Valve Software commenting on how they did it:
00167 ///     http://developer.valvesoftware.com/wiki/Latency_Compensating_Methods_in_Client/Server_In-game_Protocol_Design_and_Optimization