mac_address_eui48 0.1.0 → 0.1.1

data/README.md

@@ -1,36 +1,85 @@
 # MacAddressEui48
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/mac_address_eui48`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
+This is an implementation of MAC address along with tools for OUI lookup and random MAC address generation. It can be used as a Ruby library or through the command line tools. 
+
+The OUI resolver is based on the official OUI file provided by the IEEE http://standards-oui.ieee.org/oui.txt. This file is stored in `data/`.
+
+## Features
+### Command line tools
+
+* gen_mac_address.rb: generate random MAC address
+  * Fully random address
+  * Generate multiple address at one time
+  * Address with registered OUI
+  * Address with given OUI
+* oui_lookup.rb: resolve OUI of MAC address
+
+### Library 
+
+
+* MacAddressEui48::MacAddress
+  * Initialization from Integer, String of MacAddress
+  * Comparison operator
+  * Iteration over a range of MacAddress
+  * Test for Broadcast address
+  * Flag tests: locally administered, multicast, ...
+
+* MacAddressEui48::OuiResolver	
+  * Lookup: Organization/Vendor from MAC address
+  * Reverse lookup: OUI (MAC prefix) from Organization/Vendor 
+  * Random MAC address generation
+    * Over all space (2^48 values) 
+    * Only within space of registered OUI
+    * Over a specific OUI
+   
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'mac_address_eui48'
+```bash
+gem install mac_address_eui48
 ```
 
-And then execute:
-
-    $ bundle
+## Usage
 
-Or install it yourself as:
+### Command line tools 
+
+Generation of random MAC address
+```bash
+# fully random address
+$ ./gen_mac_address.rb 
+5A:79:5A:7D:FC:71
+
+# random address in with registered OUI
+$ ./gen_mac_address.rb -r
+00:1C:AE:57:0E:BA
+
+# multiple address
+$ ./gen_mac_address.rb -n 5
+3F:40:DC:4B:CC:EB
+49:23:BC:D4:54:9D
+85:F6:49:BB:CC:47
+33:68:8A:9E:21:57
+42:B6:80:B8:B0:7F
+
+# random mac address from a given OUI (vendor)
+$ ./gen_mac_address.rb -o "Xerox Corporation"
+9C:93:4E:27:2A:16
+```
 
-    $ gem install mac_address_eui48
+Resolving OUI 
+```bash
+$ ./oui_lookup.rb C4:04:15:12:34:56
+NETGEAR INC.,
+```
+ 
+### Library 
 
-## Usage
+TODO
 
-TODO: Write usage instructions here
 
 ## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+TODO
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mac_address_eui48. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/cunchem/mac_address_eui48. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 

data/bin/benchmark.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
+
+require 'benchmark'
+require 'mac_address_eui48.rb'
+
+n = 50
+Benchmark.bm(25) do |x|
+  resolver = MacAddressEui48::OuiResolver.new()
+  x.report("Init Resolver              :")   {resolver = MacAddressEui48::OuiResolver.new()}      
+  x.report("random_mac       (#{n} times):")   { n.times do resolver.random_mac; end  }
+  x.report("random_oui_mac   (#{n} times):")   { n.times do resolver.random_oui_mac; end  }
+  x.report("random_mac_vendor(#{n} times):")   { n.times do resolver.random_mac_vendor("Apple, Inc."); end  }
+  x.report("oui_lookup       (#{n} times):")   { n.times do resolver.oui_lookup(resolver.random_mac); end  }
+  x.report("reverse_lookup   (#{n} times):")   { n.times do resolver.reverse_lookup(resolver.oui_lookup(resolver.random_mac)); end  }
+end

data/bin/gen_mac_address.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
+require 'mac_address_eui48.rb'
+require 'optparse'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: gen_mac_address.rb [options]
+    gen_mac_address (mac_address_eui4)
+    Copyright (C) 2015 Mathieu Cunche <mathieu.cunche@insa-lyon.fr>"
+ 
+
+  options[:verbose] = false
+  opts.on("-v", "--[no-]verbose", "Run verbosely") do 
+    options[:verbose] = true
+  end
+
+  options[:oui] = nil
+  opts.on("-o OUI", "--oui OUI", "OUI (Oragnization Unique Identifier)") do |v|
+    options[:oui] = v
+  end
+
+  options[:registered] = false
+  opts.on("-r", "--registered", "Generate random MAC from registered OUIs (disabled by default)") do |v|
+    options[:registered] = true
+  end
+
+  options[:number] = 1
+  opts.on("-n N", "--number N", "Number of MAC address to generate") do |v|
+    options[:number] = v
+  end
+ 
+  options[:help] = false
+  opts.on("-h", "--help", "Show this help") do 
+    puts opts
+    exit
+    options[:help] = true
+  end
+end.parse!
+
+#p options
+#p ARGV
+
+
+
+resolver = MacAddressEui48::OuiResolver.new()
+options[:number].to_i.times do 
+  if (options[:oui]==nil) then
+    if(options[:registered])then 
+      mac = resolver.random_oui_mac
+    else
+      mac = resolver.random_mac
+    end
+  else
+    mac = resolver.random_mac_vendor(options[:oui])
+  end
+  puts mac
+end

data/bin/oui_lookup.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
+require 'mac_address_eui48.rb'
+require 'optparse'
+
+options = {}
+optp = OptionParser.new do |opts|
+  opts.banner = "Usage: oui_lookup.rb [options] <mac_address>
+    Copyright (C) 2015 Mathieu Cunche <mathieu.cunche@insa-lyon.fr>"
+  
+  options[:help] = false
+  opts.on("-h", "--help", "Show this help") do 
+    puts opts
+    exit
+    options[:help] = true
+  end
+end.parse!
+
+# Check required conditions
+if ARGV.empty?
+  puts optp
+  exit(-1)
+end
+
+
+mac = ARGV.pop
+resolver = MacAddressEui48::OuiResolver.new()
+oui = resolver.oui_lookup(mac)
+puts oui
+

data/lib/mac_address_eui48.rb

@@ -1,5 +1,5 @@
 
-# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@innsa-lyon.fr>
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
 
 require "mac_address_eui48/version"
 require "mac_address_eui48/mac_address"
@@ -7,23 +7,21 @@ require "mac_address_eui48/oui_resolver"
 
 
 module MacAddressEui48  
-  OUI_FILE="data/oui.txt"
   
   # MAC address format is hexadecimal characters separated by ':'
   # ex: "AA:BB:CC:DD:EE:FF" or "11:22:33:44:55:66
-
   def MacAddressEui48::is_valid_mac(mac_addr)
     return (mac_addr =~ /^(\h\h:){5}\h\h$/)
   end
   
-  def MacAddressEui48::macaddr_to_int(a)
+  def MacAddressEui48::str_mac_to_int(a)
     return a = a.delete(":").to_i(16)
   end
     
-  def MacAddressEui48::int_to_macaddr(i)
+  def MacAddressEui48::int_to_str_mac(i,sep=':')
     a = i.to_s(16)
     a = a.rjust(12,'0')
-    a = a.insert(10,':').insert(8,':').insert(6,':').insert(4,':').insert(2,':')
+    a = a.insert(10,sep).insert(8,sep).insert(6,sep).insert(4,sep).insert(2,sep)
     return a.upcase 
   end
   
@@ -31,7 +29,9 @@ module MacAddressEui48
     oui = ""
     mac_array=mac_addr.upcase.split(":")
     prefix = mac_array[0] + "-" + mac_array[1] + "-" + mac_array[2]
-    oui_file = File.open(OUI_FILE)
+
+    path = File.expand_path('../../data/oui.txt', __FILE__)      
+    oui_file = File.open(path)
     oui_file.each_line do |line|
       if (line =~ /.*#{prefix}.*(hex)/) then
         

data/lib/mac_address_eui48/mac_address.rb

@@ -1,21 +1,22 @@
-# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@innsa-lyon.fr>
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
 
 module MacAddressEui48  
  
   
   class MacAddress
     include Comparable
-    attr_reader :mac_str
-    
+        
     def initialize(arg)
       case arg
       when MacAddress
-        @mac_str = arg.to_s
+        @val = arg.to_i
       when Integer 
-        @mac_str = MacAddressEui48::int_to_macaddr(arg)
+        @val = arg
       when String
+        # String value must be provided as hex char separated by ':'
         if (MacAddressEui48::is_valid_mac(arg)) then 
           @mac_str=arg
+          @val=MacAddressEui48::str_mac_to_int(arg)
         else
           raise "Wrong format for string mac address #{arg}"
         end
@@ -24,39 +25,43 @@ module MacAddressEui48
       end
     end
     
-    
     def to_i
-      return MacAddressEui48::macaddr_to_int(@mac_str)
+      @val
     end
     
     def <=>(other)
-      MacAddressEui48::macaddr_to_int(self.mac_str) <=> MacAddressEui48::macaddr_to_int(other.mac_str)
+      self.to_i <=> other.to_i
     end
     
-    def to_s
-      @mac_str  
+    def to_s(sep=':')
+      MacAddressEui48::int_to_str_mac(@val,sep).upcase
     end
   
     def is_broadcast
-      self.mac_str ==  "FF:FF:FF:FF:FF:FF"
+      #self.to_s ==  "FF:FF:FF:FF:FF:FF"
+      @val == 2**48-1
     end
    
     def is_unicast
-      return !is_multicast
+      !is_multicast
     end
+    
     def is_multicast
-      
+      mask = 1 << (5*8)
+      (mask & @val) !=0
     end
+    
     def is_glob_uniq
-      return !is_loc_admin
+      !is_loc_admin
     end
+    
     def is_loc_admin
-      
+      mask = 2 << (5*8)
+      (mask & @val) !=0 
     end
-    
 
     def next
-      return MacAddress.new(MacAddressEui48::int_to_macaddr(((self.to_i) +1)%2**48))
+      return MacAddress.new(((self.to_i) +1)%2**48)
     end
     alias_method :succ, :next
     

data/lib/mac_address_eui48/oui_resolver.rb

@@ -1,25 +1,37 @@
-# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@innsa-lyon.fr>
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
+
+
+class Hash
+  def safe_invert
+    self.each_with_object( {} ) { |(key, value), out| ( out[value] ||= [] ) << key }
+  end
+end
 
 module MacAddressEui48  
+
+  
   class OuiResolver
     def initialize()
-      @hash=Hash.new(nil)
+      @oui_hash=Hash.new(nil)
+      path = File.expand_path('../../../data/oui.txt', __FILE__)
+      oui_file = File.open(path)
       
-      oui_file = File.open(OUI_FILE)
       oui_file.each_line do |line|
         if (line =~ /\(hex\)/) then
           prefix = line.split("\t")[0].split(" ")[0].gsub("-",":").chomp
           oui = line.split("\t")[2].chomp
-          @hash[prefix]=oui
-        end
-        
+          @oui_hash[prefix]=oui
+        end  
       end
+      @reverse_oui_hash= @oui_hash.safe_invert
+      @vendor_table=@oui_hash.values
+      
     end
     def oui_lookup(mac_addr)
-      return @hash[mac_addr[0..7].upcase]
+      return @oui_hash[mac_addr[0..7].upcase]
     end
     def reverse_lookup(vendor)
-      return @hash.select { |key, val| val == vendor }.keys 
+      return @reverse_oui_hash[vendor]
     end
     def has_oui(mac)
       return (oui_lookup(mac) != nil) 
@@ -27,10 +39,13 @@ module MacAddressEui48
     
     def random_mac
       i = rand(2**48)
-      return MacAddressEui48::int_to_macaddr(i).upcase
+      return MacAddressEui48::int_to_str_mac(i)
     end
     def random_oui_mac 
-      vendor = @hash.values.uniq[rand(@hash.values.uniq.size)]
+      # Some vendors may appear more than once in the OUI table 
+      # All vendors don't have the same probability to be picked
+      n = @vendor_table.size
+      vendor = @vendor_table[rand(n)]
       return random_mac_vendor(vendor)
     end
     
@@ -39,14 +54,13 @@ module MacAddressEui48
       if (ouis.size <=0) then
         raise "OUI not found #{vendor}"
       end
+      
       oui = ouis[rand(ouis.size)]
-      i1 =  MacAddressEui48::macaddr_to_int( oui + ":00:00:00")
+      i1 =  MacAddressEui48::str_mac_to_int( oui + ":00:00:00")
       i2 = rand(2**24)       
       i = i1 + i2
-      return MacAddressEui48::int_to_macaddr(i)
-    end
-    
+      return MacAddressEui48::int_to_str_mac(i)
+    end   
   end
-  
-  
+ 
 end

data/lib/mac_address_eui48/version.rb

@@ -1,5 +1,5 @@
-# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@innsa-lyon.fr>
+# Copyright (C) 2015  Mathieu Cunche <mathieu.cunche@insa-lyon.fr>
 
 module MacAddressEui48
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mac_address_eui48
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-07 00:00:00.000000000 Z
+date: 2015-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -47,7 +47,10 @@ description:
 email:
 - mathieu.cunche@insa-lyon.fr
 executables:
+- benchmark.rb
 - console
+- gen_mac_address.rb
+- oui_lookup.rb
 - setup
 extensions: []
 extra_rdoc_files: []
@@ -56,7 +59,10 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bin/benchmark.rb
 - bin/console
+- bin/gen_mac_address.rb
+- bin/oui_lookup.rb
 - bin/setup
 - data/oui.txt
 - lib/mac_address_eui48.rb