ipaccess 0.0.4 → 1.2.0

data/examples/imap.rb

@@ -0,0 +1,37 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/net/imap'
+
+# Add host's IP by to black list of global output access set
+IPAccess::Set::Global.output.blacklist 'randomseed.pl'
+
+# Create custom access set with one blacklisted IP
+acl = IPAccess::Set.new
+acl.output.blacklist 'randomseed.pl'
+acl.output.blacklist 'imap.heise.de'
+
+#===== Example cases
+
+# 1
+
+imap = IPAccess::Net::IMAP.new('randomseed.pl')
+  imap.authenticate('LOGIN', 'joe_user', 'joes_password')
+  imap.examine('INBOX')
+  imap.search(["RECENT"]).each do |message_id|
+    envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
+    puts "#{envelope.from[0].name}: \t#{envelope.subject}"
+  end
+
+# 2
+
+imap = Net::IMAP.new('imap.heise.de', 'imaps', true, nil, false)
+
+IPAccess.arm imap, acl
+  
+  imap.authenticate('LOGIN', 'joe_user', 'joes_password')
+  imap.examine('INBOX')
+  imap.search(["RECENT"]).each do |message_id|
+    envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
+    puts "#{envelope.from[0].name}: \t#{envelope.subject}"
+  end
+

data/examples/pop.rb

@@ -0,0 +1,31 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/net/pop'
+
+# Add host's IP by to black list of global output access set
+IPAccess::Set::Global.output.blacklist 'randomseed.pl'
+
+# Create custom access set with one blacklisted IP
+acl = IPAccess::Set.new
+acl.output.blacklist 'randomseed.pl'
+acl.output.blacklist 'gmail.com'
+
+#===== Example cases
+
+# 1
+
+i = 0
+IPAccess::Net::APOP.delete_all('randomseed.pl', 110,
+                     'YourAccount', 'YourPassword') do |m|
+  File.open("inbox/#{i}", 'w') do |f|
+    f.write m.pop
+  end
+  i += 1
+end
+
+# 2
+
+p = Net::POP3.new 'randomseed.pl'
+IPAccess.arm p, acl
+p.auth_only 'user', 'pass'
+

data/examples/smtp.rb

@@ -0,0 +1,26 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/net/smtp'
+
+# Add host's IP by to black list of global output access set
+IPAccess::Set::Global.output.blacklist 'randomseed.pl'
+
+# Create custom access set with one blacklisted IP
+acl = IPAccess::Set.new
+acl.output.blacklist 'randomseed.pl'
+acl.output.blacklist 'gmail.com'
+
+#===== Example cases
+
+# 1
+
+IPAccess::Net::SMTP.start('randomseed.pl', 25) do |smtp|
+  ;
+end
+
+# 2
+
+p = Net::SMTP.new 'randomseed.pl'
+IPAccess.arm p, acl
+p.start 'user', 'pass'
+

data/examples/tcp_server.rb

@@ -0,0 +1,32 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/socket'
+
+acl = IPAccess::Set.new
+acl.input.blacklist :strange
+
+# 0
+
+serv = IPAccess::TCPServer.new(31337)     # create listening TCP socket
+serv.acl = :private                       # create and use private access set
+serv.blacklist :local, :private           # block local and private IP addresses
+serv.permit '127.0.0.5'                   # make an exception
+
+puts serv.acl.show                        # show listed IP addresses
+sock = serv.sysaccept                     # accept connection
+
+
+# 1
+
+# Create and use the TCP socket
+
+s = IPAccess::TCPServer.new(31337, acl)
+#s = TCPServer.new(31337)
+
+# Arm object s
+#IPAccess.arm s, acl
+
+puts s.acl.show
+puts "\nissue in terminal: telnet 127.0.0.1 31337\n\n"
+g = s.accept
+

data/examples/tcp_socket.rb

@@ -1,9 +1,13 @@
 $:.unshift File.join(File.dirname(__FILE__), "..", "lib")
 
-require 'ipaccess'
+require 'ipaccess/socket'
 
-IPAccess::Global.output.blacklist 'randomseed.pl'
-IPAccess.arm TCPSocket
+# Add host's IP by to black list of global output access set
+IPAccess::Set::Global.output.blacklist '78.0.0.0/8'
+
+# Create and use the TCP socket
 s = TCPSocket.new('randomseed.pl', 80)
 
+# Arm object s
+IPAccess.arm s
 

data/examples/telnet.rb

@@ -0,0 +1,32 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/net/telnet'     # load Net::Telnet version and IPAccess.arm method
+
+opts = {}
+opts["Host"]  = 'randomseed.pl'
+opts["Port"]  = '80'
+
+t = Net::Telnet.new(opts)       # try to connect to remote host
+
+begin
+
+  IPAccess.arm t                  # arm single Telnet object (will use global access set)
+  t.blacklist! 'randomseed.pl'    # blacklist host while being connected
+
+rescue IPAccessDenied => e
+
+  puts "Message:\t#{e.message}"
+  puts
+  puts "ACL:\t\t#{e.acl}"
+  puts "Exception:\t#{e.inspect}"
+  puts "Remote IP:\t#{e.peer_ip}"
+  puts "Rule:\t\t#{e.rule}"
+  puts "Originator:\t#{e.originator}"
+  puts "CIDR's Origin:\t#{e.peer_ip.tag[:Originator]}\n\n"
+  puts "Session closed:\t#{t.closed?}"
+  
+end
+
+p t
+p "end"
+

data/examples/text_message.rb

@@ -0,0 +1,45 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require 'ipaccess/socket'
+
+begin
+  
+  # add some rules
+  acl = IPAccess::Set.new
+  acl.input.blacklist_reasonable "Local and private addresses aren't welcome here", :local, :private
+  acl.input.whitelist_reasonable "I like that system, it makes toasts", '172.16.0.10', '1234:1234:1234:1234:1234:1234:1234:1234'
+
+  # show the lists with reasons for entries
+  puts acl.show(true)
+
+  # create a server
+  s = IPAccess::TCPServer.new(31337, acl)
+  
+  # let it stays opened on access denied event
+  s.opened_on_deny = true
+
+  # listen for a connection
+  puts "\nnow use terminal and issue: telnet 127.0.0.1 31337\n\n"
+  n  = s.accept
+
+rescue IPAccessDenied => e
+
+  # show some stuff carried along with an exception
+  puts "Message: #{e.message}"
+  puts
+  puts "Exception: #{e.inspect}"
+  puts "Remote IP: #{e.peer_ip} (#{e.peer_ip_short})"
+  puts "Rule: #{e.rule} (#{e.rule_short})"
+  puts "Reason: #{e.reason}"
+  puts "Originator: #{e.originator}"
+  puts "Internal Originator in CIDR: #{e.peer_ip.tag[:Originator]}"
+  puts "ACL: #{e.acl}"
+  
+  # send a reason to our peer before closing connection
+  unless e.originator.closed?
+    e.originator.write(e.reason + "\n\r")
+    e.originator.close
+  end
+
+end
+

data/lib/ipaccess.rb

@@ -1,13 +1,13 @@
 # encoding: utf-8
 # 
 # Author::    Paweł Wilk (mailto:pw@gnu.org)
-# Copyright:: Copyright (c) 2009 Paweł Wilk
-# License::   This program is licensed under the terms of {GNU Lesser General Public License}[link:docs/LGPL-LICENSE.html] or {Ruby License}[link:docs/COPYING.html].
+# Copyright:: Copyright (c) 2009-2014 by Paweł Wilk
+# License::   This program is licensed under the terms of {GNU Lesser General Public License}[link:docs/LGPL.html] or {Ruby License}[link:docs/COPYING.html].
 # 
 # Classes contained in this library allow you to create
 # and manage IP access lists in an easy way. You may use
-# IPAccess class to maintain inpu/output traffic control.
-# You also may use IPAccessList class directly to build
+# IPAccess::Set class to maintain inpu/output traffic control.
+# You also may use IPAccess::List class directly to build
 # your own access sets based on black lists and white lists.
 # 
 #--
@@ -28,8 +28,558 @@ require 'socket'
 require 'resolv'
 require 'netaddr'
 
-require 'ipaccess/netaddr_patch'
+require 'ipaccess/patches/netaddr'
 require 'ipaccess/ip_access_list'
-require 'ipaccess/ip_access'
-require 'ipaccess/sockets'
+require 'ipaccess/ip_access_set'
 
+# This module contains classes that are
+# used to control IP access. There are
+# three major components you may need:
+# 
+# === IPAccess::List class
+# 
+# This class lets you create IP
+# access list with blacklisted
+# and whitelisted elements. It
+# also has methods for checking
+# whether given IP matches the
+# list.
+# 
+# === IPAccess::Set class
+# 
+# This class contains two
+# objects that are instances
+# of IPAccess::List class.
+# It allows you to create so
+# called access set. The access
+# set contains members named
+# +input+ and +output+. All methods
+# that validate IP access do it
+# against one of the lists. Input
+# access list is for incomming
+# and output for outgoing IP traffic.
+# In case of connection-oriented
+# sockets and other network objects
+# the convention is to use output access
+# list to validate connections that
+# we initiate. The incomming traffic
+# in that model means the connections
+# initiated by a remote peer.
+# 
+# === Patching engine
+# 
+# IPAccess was initialy considered as a
+# set of classes that you may use
+# in your own programs to control
+# IP access. That means your own classes
+# used for communication should use
+# access lists or sets before making any
+# real connections or sending any datagrams.
+# 
+# Fortunately there are many network classes,
+# including sockets, that Ruby ships with.
+# It would be waste of resources to not modify
+# them to support IP access control and automagically
+# throw exceptions when access should be denied.
+# 
+# And here the special module method called +IPAccess.arm+
+# comes in. It lets you patch most of Ruby's
+# networking classes and objects. Besides
+# equipping them in IPAccess::Set instance
+# it also adds some methods for doing quick
+# checks and changes in access lists.
+# 
+# The patching engine can arm network classes and
+# single network objects. It is not loaded by default
+# since you may not want extra code attached to a
+# program that uses access lists or sets with
+# own access checking code.
+# 
+# === Variants of popular classes
+# 
+# Sometimes you want to write a code that
+# uses standard Ruby's network objects
+# but you find it dirty to alter classes or objects.
+# In that case you may want to use static variants
+# of Ruby's network classes that are not patches
+# but derived classes.
+# 
+# === Exceptions
+# 
+# When you are dealing with patched (armed) versions
+# of classes and objects or when you are using
+# special variants of popular network classes, you have
+# to rely on exceptions as the only way for
+# access checking methods to tell your program
+# that an event (like access denied) happened.
+# 
+# Note that when exception is thrown
+# the communication session is closed in case
+# of connection-oriented network objects.
+# You may change it by switching +opened_on_deny+
+# attribute to +true+.
+# 
+# See IPAccess::Set#check_in to know more
+# about tracking original network object
+# that caused exception to happend. Note
+# that in case of armed versions of network
+# classes (or access-contolled variants)
+# an information about original network
+# object stored within an exception will be set to
+# +nil+ if access had been denied before
+# object was initialized. This shouldn't
+# happend often, since access checks are lazy
+# (they are performed only when connection
+# is going to be made).
+# 
+# See IPAccessDenied for more information
+# about what you can do with exceptions.
+# 
+# === Sockets in armed network objects
+# 
+# Specialized Ruby's network classes,
+# such as Net::HTTP or Net::Telnet
+# and their variants created by this library,
+# make use of socket objects. For example
+# Net::HTTP class uses TCPSocket instance to
+# create TCP connection. When versions
+# of these <tt>Net::</tt> objects with
+# enabled access control are used then
+# the internal routines of IPAccess
+# will also try to patch underlying sockets and assign
+# to them the same access set that is used by main
+# object. It is done to avoid access leaks.
+# However, such armed internal sockets will have
+# +opened_on_deny+ flag switched on since
+# closing session (and an eventual connection)
+# should be settled by main object.
+# 
+# === Ordination of elements
+# 
+# To properly understand what are the most important
+# structures mentioned above it's worth
+# to look at the diagram:
+# 
+# link:images/ipaccess_view.png
+#  
+# == Usage
+# 
+# === Handling access sets and access lists
+# 
+# If you need just IP access lists that you will handle in your own way
+# you may want to use two classes:
+# 
+# * IPAccess::Set to maintain access sets (containing input and output access lists),
+# * IPAccess::List to maintain single access list.
+# 
+# === Using socket classes
+# 
+# If you want standard sockets to have access control enabled
+# you may want to use:
+# 
+# * IPAccess::Socket (or issue <tt>IPAccess.arm Socket</tt>)
+# * IPAccess::TCPSocket (or issue <tt>IPAccess.arm TCPSocket</tt>)
+# * IPAccess::UDPSocket (or issue <tt>IPAccess.arm UDPSocket</tt>)
+# * IPAccess::SOCKSocket (or issue <tt>IPAccess.arm SOCKSocket</tt>)
+# * IPAccess::TCPServer (or issue <tt>IPAccess.arm TCPServer</tt>)
+# 
+# Before using any of them you must issue:
+# 
+# * <tt>require 'ipaccess/socket'</tt>
+# 
+# Using the IPAccess.arm causes standard socket class to be altered,
+# while \IPAccess:: classes are just new variants of socket
+# handling classes.
+# 
+# ==== Using other supported network classes
+# 
+# If you want some working objects to have access control enabled
+# you may want to use:
+# 
+# * IPAccess::Net::Telnet (or issue <tt>IPAccess.arm Net::Telnet</tt>)
+# * IPAccess::Net::HTTP (or issue <tt>IPAccess.arm Net::HTTP</tt>)
+# * IPAccess::Net::FTP (or issue <tt>IPAccess.arm Net::FTP</tt>)
+# * IPAccess::Net::POP3 (or issue <tt>IPAccess.arm Net::POP3</tt>)
+# * IPAccess::Net::IMAP (or issue <tt>IPAccess.arm Net::IMAP</tt>)
+# * IPAccess::Net::SMTP (or issue <tt>IPAccess.arm Net::SMTP</tt>)
+# 
+# ==== Using single network objects
+# 
+# If you want to enable access control for single network
+# object from the list shown above you may issue:
+# 
+# 	require 'ipaccess/net/http'
+# 	obj = Net::HTTP.new(host, port)
+# 	IPAccess.arm obj
+# 
+# or
+# 
+# 	require 'ipaccess/socket'
+# 	socket = IPAccess::TCPServer.new(31337)
+# 	IPAccess.arm socket
+# 	
+# ..and so on.
+# 
+# === Structures
+# 
+# IP addresses used by the classes are internaly and interfacialy
+# represented by NetAddr::CIDR[http://netaddr.rubyforge.org/classes/NetAddr/CIDR.html]
+# objects (NetAddr::CIDRv4[http://netaddr.rubyforge.org/classes/NetAddr/CIDRv4.html] and
+# NetAddr::CIDRv6[http://netaddr.rubyforge.org/classes/NetAddr/CIDRv6.html]). Due to
+# performance reasons any access list internally is represented as a tree
+# (slightly modified NetAddr::Tree[http://netaddr.rubyforge.org/classes/NetAddr/Tree.html])
+# with special tags assigning rules to virtual lists.
+# 
+# === Relations
+# 
+# Here is a diagram which shows relations
+# between the IPAccess::TCPSocket class
+# and other classes from this module:
+# 
+# link:images/ipaccess_relations.png
+
+module IPAccess
+  
+  # This method converts names to NetAddr::CIDR objects. It returns an array of CIDR objects.
+  # 
+  # Allowed input are strings (DNS names or IP addresses optionally with masks), numbers (IP addresses representation),
+  # IPSocket objects, URI objects, IPAddr objects, Net::HTTP objects, IPAddrList objects, NetAddr::CIDR objects,
+  # NetAddr::Tree objects, IPAccess::List objects, symbols, objects that contain file descriptors bound to sockets
+  # (including OpenSSL sockets) and arrays of these.
+  #
+  # In case of resolving the IPv6 link-local addresses
+  # zone index is removed. In case of DNS names there may
+  # occur Resolv::ResolvError exception. If there is an
+  # object that cannot be converted the ArgumentError
+  # exception is raised.
+  #
+  # When an argument called +:include_origins+ is present then the method will attach
+  # original converted objects to results as the +:Origin+ tag of CIDR objects (<tt>tag[:Origin]</tt>).
+  # This rule applies only to single objects or objects inside of arrays or sets.
+  # Objects that are kind of NetAddr::CIDR, IPAccess::Set, NetAddr::Tree and arrays will
+  # never be set as originators.
+  # 
+  # ==== Examples
+  # 
+  #     to_cidrs("127.0.0.1")                      # uses the IP address
+  #     to_cidrs(2130706433)                       # uses numeric representation of 127.0.0.1
+  #     to_cidrs(:private, "localhost")            # uses special symbol and DNS hostname
+  #     to_cidrs(:private, :localhost)             # uses special symbols
+  #     to_cidrs [:private, :auto]                 # other way to write the above
+  #     to_cidrs "10.0.0.0/8"                      # uses masked IP address
+  #     to_cidrs "10.0.0.0/255.0.0.0"              # uses masked IP address
+  #     to_cidrs IPSocket.new("www.pl", 80)        # uses the socket
+  #     to_cidrs IPAddr("10.0.0.1")                # uses IPAddr object
+  #     to_cidrs NetAddr::CIDR.create("10.0.0.1")  # uses NetAddr object
+  #     to_cidrs URI('http://www.pl/')             # uses URI
+  #     to_cidrs 'http://www.pl/'                  # uses the extracted host string
+  #     to_cidrs 'somehost.xx'                     # uses the host string (fetches ALL addresses from DNS)
+  #     to_cidrs 'somehost.xx/16'                  # uses the host string and a netmask
+  #
+  # ==== Special symbols
+  #
+  # When symbol is passed to this method it tries to find out if it has special meaning.
+  # That allows you to create access rules in an easy way. For most of them you may
+  # also specify IP protocol version using +ipv4_+ or +ipv6_+ prefix.
+  # 
+  # Known symbols are:
+  #
+  # <b>+:all+</b> (+:any+, +:anyone+, +:world+, +:internet+, +:net+, +:everything+, +:everyone+, +:everybody+, +:anybody+)
+  # 
+  # variants: +:ipv4_+ and +:ipv6_+
+  #
+  # Creates masked IP address that matches all networks:
+  #     – 0.0.0.0/0
+  #     – ::/0
+  # 
+  # <b>+:broadcast+</b> (+:brd+)
+  # 
+  # variants: +:ipv4_+ and +:ipv6_+
+  #
+  # Creates masked IP address that matches generic broadcast address:
+  #     – 255.255.255.255/32
+  #     – ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/128
+  #
+  # <b>+:local+</b> (+:localhost+, +:localdomain+, +:loopback+, +:lo+)
+  # 
+  # variants: +:ipv4_+ and +:ipv6_+
+  # 
+  # Creates masked IP addresses that match localhost:
+  #     – 127.0.0.1/8
+  #     – ::1/128
+  #
+  # <b>+:auto+</b> (+:automatic+, +:linklocal+)
+  # 
+  # variants: +:ipv4_+ and +:ipv6_+
+  #  
+  # Creates masked IP addresses that match automatically assigned address ranges:
+  #     – 169.254.0.0/16
+  #     – fe80::/10
+  # 
+  # <b>+:private+</b> (+:intra+, +:intranet+, +:internal+)
+  # 
+  # variants: +:ipv4_+ and +:ipv6_+
+  #
+  # Creates masked IP addresses that match private ranges:
+  #     – 10.0.0.0/8
+  #     – 172.16.0.0/12
+  #     – 192.168.0.0/16
+  #     – 2001:10::/28
+  #     – 2001:db8::/32
+  #     – fc00::/7
+  #     – fdde:9e1a:dc85:7374::/64
+  # 
+  # <b>+:multicast+</b> (+:multi+, +:multiemission+)
+  # 
+  # variants: +:ipv4_+ and +:ipv6_+
+  #
+  # Creates masked IP addresses that match multicast addresses ranges:
+  #     – 224.0.0.0/4
+  #     – ff00::/8
+  #     – ff02::1:ff00:0/104
+  # 
+  # <b>+:reserved+</b> (+:example+)
+  # 
+  # variants: +:ipv4_+
+  # 
+  # Creates masked IP addresses that match reserved addresses ranges:
+  #     – 192.0.2.0/24
+  #     – 128.0.0.0/16
+  #     – 191.255.0.0/16
+  #     – 192.0.0.0/24
+  #     – 198.18.0.0/15
+  #     – 223.255.255.0/24
+  #     – 240.0.0.0/4
+  # 
+  # <b>+:strange+</b> (+:unusual+, +:nonpublic+, +:unpublic+)
+  #
+  # Creates masked IP addressess that match the following sets (both IPv4 and IPv6):
+  #     – :local
+  #     – :auto
+  #     – :private
+  #     – :reserved
+  #     – :multicast
+  
+  def self.to_cidrs(*addresses)
+    obj = addresses.flatten
+    include_origins = false
+    obj.delete_if { |x| include_origins = true if (x.is_a?(Symbol) && x == :include_origins) }
+    
+    if obj.size == 1
+      obj = obj.first
+    else
+      ary = []
+      obj.each do |o|
+        ary += include_origins ? to_cidrs(o, :include_origins) : to_cidrs(o)
+      end
+      ary.flatten!
+      return ary
+    end
+    
+    ori_obj = obj
+    
+    # NetAddr::CIDR - immediate generation
+    if obj.is_a?(NetAddr::CIDR)
+      r = obj.dup
+      r.tag[:Originator] = ori_obj if include_origins
+      return [r] 
+    end
+    
+    # IPAccess::List - immediate generation
+    return obj.to_a if obj.is_a?(IPAccess::List)
+  
+    # NetAddr::Tree - immediate generation
+    return obj.dump.map { |addr| addr[:CIDR] } if obj.is_a?(NetAddr::Tree)
+  
+    # number or nil - immediate generation or exception
+    if (obj.is_a?(Numeric) || obj.nil?)
+      r =  NetAddr::CIDR.create(obj)
+      r.tag[:Originator] = ori_obj if include_origins
+      return [r]
+    end
+        
+    # object containing socket member (e.g. Net::HTTP) - fetch socket
+    if obj.respond_to?(:socket)
+      obj = obj.socket
+    elsif obj.respond_to?(:sock)
+      obj = obj.sock
+    elsif obj.respond_to?(:client_socket)
+      obj = obj.client_socket
+    elsif obj.instance_variable_defined?(:@socket)
+      obj = obj.instance_variable_get(:@socket)
+    elsif obj.instance_variable_defined?(:@client_socket)
+      obj = obj.instance_variable_get(:@client_socket)
+    elsif obj.instance_variable_defined?(:@sock)
+      obj = obj.instance_variable_get(:@sock)
+    end
+    obj = obj.io if (obj.respond_to?(:io) && obj.io.respond_to?(:getpeername))
+    
+    # some file descriptor but not socket - fetch socket
+    obj = ::Socket.for_fd(obj.fileno) if (!obj.respond_to?(:getpeername) && obj.respond_to?(:fileno))
+    
+    # Socket - immediate generation
+    if obj.respond_to?(:getpeername)
+      peeraddr = ::Socket.unpack_sockaddr_in(obj.getpeername).last.split('%').first
+      r = NetAddr::CIDR.create(peeraddr)
+      r.tag[:Originator] = ori_obj if include_origins
+      return [r]
+    end
+    
+    # symbol - immediate generation
+    r_args = nil
+    if obj.is_a?(Symbol)
+    case obj
+      when :ipv4_all, :ipv4_any, :ipv4_anyone, :ipv4_world, :ipv4_internet, :ipv4_net, :ipv4_everything, :ipv4_everyone, :ipv4_everybody, :ipv4_anybody
+        obj = [ "0.0.0.0/0" ]
+      when :ipv6_all, :ipv6_any, :ipv6_anyone, :ipv6_world, :ipv6_internet, :ipv6_net, :ipv6_everything, :ipv6_everyone, :ipv6_everybody, :ipv6_anybody
+        obj = [ "0.0.0.0/0", "::/0" ]
+      when :ipv4_broadcast, :ipv4_brd
+        obj = [ "255.255.255.255/32" ]
+      when :ipv6_broadcast, :ipv6_brd
+        obj = [ "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/128" ]
+      when :ipv4_local, :ipv4_localhost, :ipv4_loopback, :ipv4_lo
+        obj = [ "127.0.0.1/8" ]
+      when :ipv6_local, :ipv6_localhost, :ipv6_loopback, :ipv6_lo
+        obj = [ "::1/128" ]
+      when :ipv4_auto, :ipv4_automatic, :ipv4_linklocal
+        obj = [ "169.254.0.0/16" ]
+      when :ipv6_auto, :ipv6_automatic, :ipv6_linklocal
+        obj = [ "fe80::/10" ]
+      when :ipv4_private, :ipv4_intra, :ipv4_intranet, :ipv4_internal
+        obj = [ "10.0.0.0/8",
+                "172.16.0.0/12",
+                "192.168.0.0/16" ]
+      when :ipv6_private, :ipv6_intra, :ipv6_intranet, :ipv6_internal, :ipv6_ula, :ipv6_unique
+        obj = [ "2001:10::/28",
+                "2001:db8::/32",
+                "fc00::/7",
+                "fdde:9e1a:dc85:7374::/64" ]
+      when :ipv4_multicast, :ipv4_multi, :ipv4_multiemission
+        obj = [ "224.0.0.0/4" ]
+      when :ipv6_multicast, :ipv6_multi, :ipv6_multiemission
+        obj = [ "ff00::/8",
+                "ff02::1:ff00:0/104" ]
+      when :ipv4_example, :ipv4_reserved
+        obj = [ "192.0.2.0/24",
+                "128.0.0.0/16",
+                "191.255.0.0/16",
+                "192.0.0.0/24",
+                "198.18.0.0/15",
+                "223.255.255.0/24",
+                "240.0.0.0/4" ]
+      when :all, :any, :anyone, :world, :internet, :net, :everything, :everyone, :everybody, :anybody
+        r_args = [ :ipv4_all,
+                   :ipv6_all ] 
+      when :broadcast, :brd
+        r_args = [ :ipv4_broadcast,
+                   :ipv6_broadcast ]
+      when :local, :localhost, :localdomain, :loopback, :lo
+        r_args = [ :ipv4_local,
+                   :ipv6_local ]
+      when :auto, :automatic, :linklocal
+        r_args = [ :ipv4_auto,
+                   :ipv6_auto ]            
+      when :private, :intra, :intranet, :internal
+        r_args = [ :ipv4_private,
+                   :ipv6_private ]
+      when :multicast, :multi, :multiemission
+        r_args = [ :ipv4_multicast,
+                   :ipv6_multicast ]
+      when :reserved, :example
+        r_args = [ :ipv4_example ]
+      when :strange, :unusual, :nonpublic, :unpublic
+        r_args = [ :local,
+                   :auto,
+                   :private,
+                   :reserved,
+                   :multicast ]
+      else
+        raise ArgumentError, "provided symbol is unknown: #{obj.to_s}"
+      end
+      
+      unless r_args.nil?
+        r_args.push :include_origins if include_origins
+        return to_cidrs(*r_args)
+      end
+      
+      # strange types here
+      if obj.is_a?(Array)
+        return obj.map do |addr|
+          r = NetAddr::CIDR.create(addr)
+          r.tag[:Originator] = addr if include_origins
+          r
+        end
+      end
+    end
+    
+    # URI or something that responds to host method - fetch string
+    obj = obj.host if obj.respond_to?(:host)
+    
+    # objects of external classes 
+    case obj.class.name.to_sym
+    when :IPAddr                                          # IPAddr - fetch IP/mask string
+      obj = obj.native.inspect.split[1].chomp('>')[5..-1]
+    when :IPAddrList                                      # IPAddrList - pass array to parse
+      return include_origins ? to_cidrs(obj.to_a, :include_origins) : to_cidrs(obj.to_a)
+    end
+    
+    # string or similar - immediate generation
+    if obj.respond_to?(:to_s)
+      hostmask = ""
+      obj = obj.to_s
+      # URI
+      if obj =~ /^[^:]+:\/\/(.*)/
+        obj = $1.split('/').first
+        # IP in URI
+        if obj =~ /^\[([^\]]+)\]/
+          obj = $1
+        else
+          obj = obj.split(':').first
+        end
+      # host(s) and a mask
+      elsif obj =~ /^([^\/]+)(\/((\d{1,2}$)|(\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b$)))/
+        obj = $1
+        hostmask = $2
+      end
+      begin
+        ipa = obj.split('%').first.to_s
+        r = NetAddr::CIDR.create(ipa + hostmask)
+      rescue NetAddr::ValidationError
+        begin
+          addresses = Resolv::getaddresses(obj)
+        rescue NoMethodError # unhandled error
+          raise Resolv::ResolvError, "not connected or network error"
+        end
+        addresses.map! do |addr|
+          begin
+            r = NetAddr::CIDR.create(addr.split('%').first + hostmask)
+            r.tag[:Originator] = ori_obj
+            r
+          rescue ArgumentError
+            nil
+          end
+        end
+        addresses.flatten!
+        addresses.compact!
+        return addresses
+      end
+      r.tag[:Originator] = ori_obj
+      return [r]
+    end
+    
+    # should never happend
+    r = obj.is_a?(NetAddr::CIDR) ? obj.dup : NetAddr::CIDR.create(obj.to_s)
+    r.tag[:Originator] = ori_obj
+    return [r]
+  end
+  
+  # This method calls IPAccess.to_cidrs
+  # and returns first obtained entry containing
+  # single IP address with mask (NetAddr::CIDR).
+  
+  def self.to_cidr(*addresses)
+    r = self.to_cidrs(*addresses)
+    return r.respond_to?(:first) ? first : r
+  end
+  
+end