ipaccess 0.0.2

data/Rakefile

@@ -0,0 +1,64 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require "rake"
+require "rake/clean"
+require 'spec/version'
+require 'spec/rake/spectask'
+
+require "fileutils"
+
+require 'rdoc'
+require "rake/rdoctask"
+
+task :default => :spec
+
+desc "install by setup.rb"
+task :install do
+  sh "sudo ruby setup.rb install"
+end
+
+### Docs
+
+desc "Generate documentation for the application"
+rd = Rake::RDocTask.new("appdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "IP Access Control"
+  rdoc.options += [ '-HN',
+                    '-f', 'darkfish',
+                    '--charset=utf-8',
+                    '--main=docs/WELCOME'
+                  ]
+  rdoc.rdoc_files.include('docs/DOWNLOAD')
+  rdoc.rdoc_files.include('docs/README')
+  rdoc.rdoc_files.include('docs/WELCOME')
+  rdoc.rdoc_files.include('docs/LGPL-LICENSE')
+  rdoc.rdoc_files.include('docs/LEGAL')
+  rdoc.rdoc_files.include('docs/COPYING')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+### Specs
+
+spec_opts = proc{File.read("spec/spec.opts").split}
+spec_core_files     = FileList['spec/core_spec.rb']
+spec_all_files      = spec_core_files
+
+desc "Run core specs"
+Spec::Rake::SpecTask.new("spec_core") do |t|
+  t.spec_files = spec_core_files
+  t.spec_opts  = spec_opts.call
+  t.libs << "lib"
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new("spec") do |t|
+  t.spec_files = spec_all_files
+  t.spec_opts  = spec_opts.call
+  t.libs << "lib"
+end
+
+desc "Check documentation coverage"
+task :dcov do
+  sh %{find lib -name '*.rb' | xargs dcov}
+end
+

data/docs/COPYING

@@ -0,0 +1,61 @@
+IPAccess is copyrighted free software owned by Paweł Wilk
+(pw@gnu.org). The Owner of this software permits you to
+redistribute and/or modify the software under either the terms of the LGPL
+version 3 (see the file {LGPL-LICENSE}[link:docs/LGPL-LICENSE.html]),
+or the conditions below ("Ruby License"):
+
+  1. You may make and give away verbatim copies of the source form of this
+     software without restriction, provided that you retain ALL of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the Owner.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in a manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the Owner.
+
+  4. You may modify and include parts of the software into any other
+     software (possibly commercial), provided you comply with the terms in
+     Sections 1, 2, and 3 above. But some files in the distribution
+     are not written by the Owner, so they may be made available to you
+     under different terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whoever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/docs/DOWNLOAD

@@ -0,0 +1,17 @@
+
+== Download IP Access Control
+
+=== Latest source code
+
+Latest sources tree can be viewed on https://github.com/siefca/IPAccess/tree
+
+Public Git repository is available, to clone it use:
+
+ 		git clone git://github.com/siefca/IPAccess.git
+
+=== Gem
+
+Gem can be downloaded from: http://rubyforge.org/projects/ipaccess/ or using Rubygems:
+
+ 		gem install ipaccess
+

data/docs/LEGAL

@@ -0,0 +1,11 @@
+LEGAL NOTICE INFORMATION
+------------------------
+
+IPAccess is Copyright (C) 2009 by Paweł Wilk.
+
+IPAccess is copyrighted software owned by Paweł Wilk
+(pw@gnu.org). You may redistribute and/or modify this
+software as long as you comply with either the terms of the LGPL
+(see the file {LGPL-LICENSE}[link:docs/LGPL-LICENSE.html]),
+or Ruby's license (see the file {COPYING}[link:docs/COPYING.html]).
+

data/docs/LGPL-LICENSE

@@ -0,0 +1,169 @@
+<tt>
+	
+			  GNU LESSER GENERAL PUBLIC LICENSE
+	                       Version 3, 29 June 2007
+	
+	 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+	 Everyone is permitted to copy and distribute verbatim copies
+	 of this license document, but changing it is not allowed.
+	
+	
+	  This version of the GNU Lesser General Public License incorporates
+	the terms and conditions of version 3 of the GNU General Public
+	License, supplemented by the additional permissions listed below.
+	
+	  0. Additional Definitions.
+	
+	  As used herein, "this License" refers to version 3 of the GNU Lesser
+	General Public License, and the "GNU GPL" refers to version 3 of the GNU
+	General Public License.
+	
+	  "The Library" refers to a covered work governed by this License,
+	other than an Application or a Combined Work as defined below.
+	
+	  An "Application" is any work that makes use of an interface provided
+	by the Library, but which is not otherwise based on the Library.
+	Defining a subclass of a class defined by the Library is deemed a mode
+	of using an interface provided by the Library.
+	
+	  A "Combined Work" is a work produced by combining or linking an
+	Application with the Library.  The particular version of the Library
+	with which the Combined Work was made is also called the "Linked
+	Version".
+	
+	  The "Minimal Corresponding Source" for a Combined Work means the
+	Corresponding Source for the Combined Work, excluding any source code
+	for portions of the Combined Work that, considered in isolation, are
+	based on the Application, and not on the Linked Version.
+	
+	  The "Corresponding Application Code" for a Combined Work means the
+	object code and/or source code for the Application, including any data
+	and utility programs needed for reproducing the Combined Work from the
+	Application, but excluding the System Libraries of the Combined Work.
+	
+	  1. Exception to Section 3 of the GNU GPL.
+	
+	  You may convey a covered work under sections 3 and 4 of this License
+	without being bound by section 3 of the GNU GPL.
+	
+	  2. Conveying Modified Versions.
+	
+	  If you modify a copy of the Library, and, in your modifications, a
+	facility refers to a function or data to be supplied by an Application
+	that uses the facility (other than as an argument passed when the
+	facility is invoked), then you may convey a copy of the modified
+	version:
+	
+	   a) under this License, provided that you make a good faith effort to
+	   ensure that, in the event an Application does not supply the
+	   function or data, the facility still operates, and performs
+	   whatever part of its purpose remains meaningful, or
+	
+	   b) under the GNU GPL, with none of the additional permissions of
+	   this License applicable to that copy.
+	
+	  3. Object Code Incorporating Material from Library Header Files.
+	
+	  The object code form of an Application may incorporate material from
+	a header file that is part of the Library.  You may convey such object
+	code under terms of your choice, provided that, if the incorporated
+	material is not limited to numerical parameters, data structure
+	layouts and accessors, or small macros, inline functions and templates
+	(ten or fewer lines in length), you do both of the following:
+	
+	   a) Give prominent notice with each copy of the object code that the
+	   Library is used in it and that the Library and its use are
+	   covered by this License.
+	
+	   b) Accompany the object code with a copy of the GNU GPL and this license
+	   document.
+	
+	  4. Combined Works.
+	
+	  You may convey a Combined Work under terms of your choice that,
+	taken together, effectively do not restrict modification of the
+	portions of the Library contained in the Combined Work and reverse
+	engineering for debugging such modifications, if you also do each of
+	the following:
+	
+	   a) Give prominent notice with each copy of the Combined Work that
+	   the Library is used in it and that the Library and its use are
+	   covered by this License.
+	
+	   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+	   document.
+	
+	   c) For a Combined Work that displays copyright notices during
+	   execution, include the copyright notice for the Library among
+	   these notices, as well as a reference directing the user to the
+	   copies of the GNU GPL and this license document.
+	
+	   d) Do one of the following:
+	
+	       0) Convey the Minimal Corresponding Source under the terms of this
+	       License, and the Corresponding Application Code in a form
+	       suitable for, and under terms that permit, the user to
+	       recombine or relink the Application with a modified version of
+	       the Linked Version to produce a modified Combined Work, in the
+	       manner specified by section 6 of the GNU GPL for conveying
+	       Corresponding Source.
+	
+	       1) Use a suitable shared library mechanism for linking with the
+	       Library.  A suitable mechanism is one that (a) uses at run time
+	       a copy of the Library already present on the user's computer
+	       system, and (b) will operate properly with a modified version
+	       of the Library that is interface-compatible with the Linked
+	       Version.
+	
+	   e) Provide Installation Information, but only if you would otherwise
+	   be required to provide such information under section 6 of the
+	   GNU GPL, and only to the extent that such information is
+	   necessary to install and execute a modified version of the
+	   Combined Work produced by recombining or relinking the
+	   Application with a modified version of the Linked Version. (If
+	   you use option 4d0, the Installation Information must accompany
+	   the Minimal Corresponding Source and Corresponding Application
+	   Code. If you use option 4d1, you must provide the Installation
+	   Information in the manner specified by section 6 of the GNU GPL
+	   for conveying Corresponding Source.)
+	
+	  5. Combined Libraries.
+	
+	  You may place library facilities that are a work based on the
+	Library side by side in a single library together with other library
+	facilities that are not Applications and are not covered by this
+	License, and convey such a combined library under terms of your
+	choice, if you do both of the following:
+	
+	   a) Accompany the combined library with a copy of the same work based
+	   on the Library, uncombined with any other library facilities,
+	   conveyed under the terms of this License.
+	
+	   b) Give prominent notice with the combined library that part of it
+	   is a work based on the Library, and explaining where to find the
+	   accompanying uncombined form of the same work.
+	
+	  6. Revised Versions of the GNU Lesser General Public License.
+	
+	  The Free Software Foundation may publish revised and/or new versions
+	of the GNU Lesser General Public License from time to time. Such new
+	versions will be similar in spirit to the present version, but may
+	differ in detail to address new problems or concerns.
+	
+	  Each version is given a distinguishing version number. If the
+	Library as you received it specifies that a certain numbered version
+	of the GNU Lesser General Public License "or any later version"
+	applies to it, you have the option of following the terms and
+	conditions either of that published version or of any later version
+	published by the Free Software Foundation. If the Library as you
+	received it does not specify a version number of the GNU Lesser
+	General Public License, you may choose any version of the GNU Lesser
+	General Public License ever published by the Free Software Foundation.
+	
+	  If the Library as you received it specifies that a proxy can decide
+	whether future versions of the GNU Lesser General Public License shall
+	apply, that proxy's public statement of acceptance of any version is
+	permanent authorization for you to choose that version for the
+	Library.
+
+</tt>

data/docs/README

@@ -0,0 +1,95 @@
+This library provides classes for controlling IP access
+in your programs. You can use it to build your own
+routines checking IP addresses against access lists
+or use altered sockets implementation with IP access
+control enabled that also comes with this library.
+
+There are two basic classes used to maintain access rules:
+IPAccessList and IPAccess.
+
+IP addresses used by all classes are internaly and interfacialy
+represented by NetAddr::CIDR objects (NetAddr::CIDRv4 and NetAddr::CIDRv6).
+
+=== IPAccessList Class
+
+This class maintains simple access list.
+
+Objects of IPAccessList class contain two lists of rules:
+white list and black list. You can add IP rules
+(both IPv4 and IPv6) to this lists and then manually
+check access for provided IP addresses against that
+lists using proper methods. Rules are IP addresses
+that can have netmasks.
+
+When doing access checking white list has precedence
+over black list. If an IP address doesn't match any list,
+methods evaluating access permit it. The default policy
+is to accept. To change the default policy you may want
+to add +:all+ rule to black list which would match all
+addresses and then just whitelist permitted.
+
+The class also provides methods for easy administration
+of lists and method IPAccessList.obj_to_cidr that
+"understands" most common IP representations including
+DNS names, sockets, file descriptors bound to sockets and more.
+
+=== IPAccess Class
+
+This class maintains access set.
+
+Objects of IPAccess class, called access sets, contain two access lists
+(IPAccessList objects) as accessible attributes: +input+ and +output+.
+First list is for maintaining incoming IP traffic and second for outgoing.
+Again, it is your free will to check IP addresses against input/output
+rules or not.
+
+To manage rules you may access attributes directly, using dot operator
+and calling certain methods of IPAccessList objects. To check access
+you may use methods of this class. There are two groups of such methods,
+one for incoming and one for outgoing access checking. There are also different
+variants of this methods for different IP representations. That's because speed
+is important here. If you have an IP address in some socket you should use method
+that checks socket, if your IP is in text format you may want to use method that
+checks IP addresses written as strings.
+
+Access checking methods throw exceptions that are kind of IPAccessDenied.
+These exceptions contain IP addresses, rules that matched and diagnostic message.
+You can distinguish between errors related to incoming and outgoing traffic
+because checking methods throw different kind of exceptions for them:
+IPAccessDenied::Input and IPAccessDenied::Output accordingly.
+
+=== IPAccess::Socket and Co.
+
+If you don't want to write your own access controlling routines
+you may want to use access controlled sockets. These are subclasses
+of Ruby's socket handling classes.
+
+Currently available classes are: IPAccess::Socket,
+IPAccess::TCPSocket, IPAccess::SOCKSSocket,
+IPAccess::UDPSocket, IPAccess::TCPServer and IPAccess::UDPServer.
+
+=== Patched Ruby Sockets
+
+If there is no other way to control access you may use this
+library to patch native socket handling classes of Ruby.
+To do that use special class method called IPAccess.arm 
+
+=== Download
+
+See {DOWNLOAD}[link:docs/DOWNLOAD.html] file for more
+info about obtaining IPAccess.
+
+=== Legal Notice
+
+IPAccess is Copyright (C) 2009 by Paweł Wilk.
+
+IPAccess is copyrighted software owned by Paweł Wilk (pw@gnu.org).
+You may redistribute and/or modify this software as long as you
+comply with either the terms of the LGPL (see the file {LGPL-LICENSE}[link:docs/LGPL-LICENSE.html]),
+or Ruby's license (see the file {COPYING}[link:docs/COPYING.html]).
+
+THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE.
+

data/docs/TODO

@@ -0,0 +1,18 @@
+
+Specification:
+
+- add missing rspec examples
+
+Ruby 1.9 sockets:
+
+- overload Ruby 1.9 socket methods
+
+Documentation:
+
+- add more documentation describing access checking workflow
+
+Other:
+
+- maybe some day: test input lists even if socket is a client socket - local socket address permit/deny
+- inspect methods?
+

data/docs/WELCOME

@@ -0,0 +1,8 @@
+This library provides classes for controlling IP access
+in your programs. You can use it to build your own
+routines checking IP addresses against access lists
+or use altered sockets implementation with IP access
+control enabled that also comes with this library.
+
+If you want to know more it's good idea to see the README file.
+