Library ipOps

Utility functions for manipulating and comparing IP addresses.

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/ipOps.lua

Functions

bin_to_ip (binstring)

Converts a string of binary digits into an IP address.

cidr_to_subnet (subnet)

Convert a CIDR subnet mask to dotted decimal notation.

compare_ip (left, op, right)

Compares two IP addresses.

expand_ip (ip, family)

Expands an IP address supplied in shortened notation. Serves also to check the well-formedness of an IP address.

fromdword (ip)

Converts the supplied IPv4 address from a DWORD value into a dotted string.

get_first_ip (ip, prefix)

Calculates the first IP address of a range of addresses given an IP address in the range and prefix length for that range.

get_first_last_ip (ip, prefix)

Calculates the first and last IP addresses of a range of addresses, given an IP address in the range and a prefix length for that range

get_ips_from_range (range)

Returns the first and last IP addresses in the supplied range of addresses.

get_last_ip (ip, prefix)

Calculates the last IP address of a range of addresses given an IP address in the range and prefix length for that range.

get_parts_as_number (ip)

Separates the supplied IP address into its constituent parts and returns them as a table of numbers.

hex_to_bin (hex)

Converts a string of hexadecimal digits into the corresponding string of binary digits.

ip_in_range (ip, range)

Checks whether the supplied IP address is within the supplied range of IP addresses.

ip_sort (ips, op)

Sorts a table of IP addresses

ip_to_bin (ip)

Converts an IP address into a string representing the address as binary digits.

ip_to_str (ip, family)

Converts an IP address into an opaque string (big-endian)

isPrivate (ip)

Checks to see if the supplied IP address is part of a non-routable address space.

str_to_ip (ip)

Converts an opaque string (big-endian) into an IP address

subnet_to_cidr (subnet)

Convert a dotted decimal subnet mask to CIDR notation.

todword (ip)

Converts the supplied IPv4 address into a DWORD value.

Functions

bin_to_ip (binstring)

Converts a string of binary digits into an IP address.

Parameters

binstring
String representing an IP address as 32 or 128 binary digits.

Usage:

ip = ipOps.bin_to_ip( "01111111000000000000000000000001" )

Return values:

  1. String representing an IP address (or nil in case of an error).
  2. String error message in case of an error.
cidr_to_subnet (subnet)

Convert a CIDR subnet mask to dotted decimal notation.

Parameters

subnet
CIDR string representing the subnet mask.

Usage:

local netmask = ipOps.cidr_to_subnet( "/16" )

Return value:

Dotted decimal representation of the suppliet subnet mask (e.g. "255.255.0.0")
compare_ip (left, op, right)

Compares two IP addresses.

When comparing addresses from different families, IPv4 addresses will sort before IPv6 addresses.

Parameters

left
String representing an IPv4 or IPv6 address. Shortened notation is permitted.
op
A comparison operator which may be one of the following strings: "eq", "ge", "le", "gt" or "lt" (respectively ==, >=, <=, >, <).
right
String representing an IPv4 or IPv6 address. Shortened notation is permitted.

Usage:

if ipOps.compare_ip( "2001::DEAD:0:0:0", "eq", "2001:0:0:0:DEAD::" ) then
  ...
end

Return values:

  1. True or false (or nil in case of an error).
  2. String error message in case of an error.
expand_ip (ip, family)

Expands an IP address supplied in shortened notation. Serves also to check the well-formedness of an IP address.

Note: IPv4in6 notated addresses will be returned in pure IPv6 notation unless the IPv4 portion is shortened and does not contain a dot, in which case the address will be treated as IPv6.

Parameters

ip
String representing an IPv4 or IPv6 address in shortened or full notation.
family
String representing the address family to expand to. Only affects IPv4 addresses when "inet6" is provided, causing the function to return an IPv4-mapped IPv6 address.

Usage:

local ip = ipOps.expand_ip( "2001::" )

Return values:

  1. String representing a fully expanded IPv4 or IPv6 address (or nil in case of an error).
  2. String error message in case of an error.
fromdword (ip)

Converts the supplied IPv4 address from a DWORD value into a dotted string.

For example, the address (((a*256+b)*256+c)*256+d) becomes a.b.c.d.

Parameters

ip
DWORD representing an IPv4 address.

Return value:

The string representing the address.
get_first_ip (ip, prefix)

Calculates the first IP address of a range of addresses given an IP address in the range and prefix length for that range.

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.
prefix
Number or a string representing a decimal number corresponding to a prefix length.

Usage:

first = ipOps.get_first_ip( "192.0.0.0", 26 )

Return values:

  1. String representing the first IP address of the range denoted by the supplied parameters (or nil in case of an error).
  2. String error message in case of an error.
get_first_last_ip (ip, prefix)

Calculates the first and last IP addresses of a range of addresses, given an IP address in the range and a prefix length for that range

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.
prefix
Number or a string representing a decimal number corresponding to a prefix length.

Usage:

first, last = ipOps.get_first_last_ip( "192.0.0.0", 26)

Return values:

  1. String representing the first IP address of the range denoted by the supplied parameters (or nil in case of an error).
  2. String representing the last IP address of the range denoted by the supplied parameters (or nil in case of an error).
  3. String error message in case of an error.
get_ips_from_range (range)

Returns the first and last IP addresses in the supplied range of addresses.

Parameters

range
String representing a range of IPv4 or IPv6 addresses in either CIDR or first-last notation.

Usage:

first, last = ipOps.get_ips_from_range( "192.168.0.0/16" )

Return values:

  1. String representing the first address in the supplied range (or nil in case of an error).
  2. String representing the last address in the supplied range (or nil in case of an error).
  3. String error message in case of an error.
get_last_ip (ip, prefix)

Calculates the last IP address of a range of addresses given an IP address in the range and prefix length for that range.

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.
prefix
Number or a string representing a decimal number corresponding to a prefix length.

Usage:

last = ipOps.get_last_ip( "192.0.0.0", 26 )

Return values:

  1. String representing the last IP address of the range denoted by the supplied parameters (or nil in case of an error).
  2. String error message in case of an error.
get_parts_as_number (ip)

Separates the supplied IP address into its constituent parts and returns them as a table of numbers.

For example, the address 139.104.32.123 becomes { 139, 104, 32, 123 }.

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.

Usage:

local a, b, c, d;
local t, err = ipOps.get_parts_as_number( "139.104.32.123" )
if t then a, b, c, d = table.unpack( t ) end

Return values:

  1. Array of numbers for each part of the supplied IP address (or nil in case of an error).
  2. String error message in case of an error.
hex_to_bin (hex)

Converts a string of hexadecimal digits into the corresponding string of binary digits.

Each hex digit results in four bits.

Parameters

hex
String representing a hexadecimal number.

Usage:

bin_string = ipOps.hex_to_bin( "F00D" )

Return values:

  1. String representing the supplied number in binary digits (or nil in case of an error).
  2. String error message in case of an error.
ip_in_range (ip, range)

Checks whether the supplied IP address is within the supplied range of IP addresses.

The address and the range must both belong to the same address family.

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.
range
String representing a range of IPv4 or IPv6 addresses in first-last or CIDR notation (e.g. "192.168.1.1 - 192.168.255.255" or "2001:0A00::/23").

Usage:

if ipOps.ip_in_range( "192.168.1.1", "192/8" ) then ... end

Return values:

  1. True or false (or nil in case of an error).
  2. String error message in case of an error.
ip_sort (ips, op)

Sorts a table of IP addresses

An in-place sort using table.sort to sort by IP address. Sorting non-IP addresses is likely to result in a bad sort and possibly an infinite loop.

Parameters

ips
The table of IP addresses to sort
op
The comparison operation to use. Default: "lt" (ascending)
ip_to_bin (ip)

Converts an IP address into a string representing the address as binary digits.

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.

Usage:

bit_string = ipOps.ip_to_bin( "2001::" )

Return values:

  1. String representing the supplied IP address as 32 or 128 binary digits (or nil in case of an error).
  2. String error message in case of an error.
ip_to_str (ip, family)

Converts an IP address into an opaque string (big-endian)

Parameters

ip
String representing an IPv4 or IPv6 address.
family
(optional) Address family to convert to. "ipv6" converts IPv4 addresses to IPv4-mapped IPv6.

Usage:

opaque = ipOps.ip_to_str( "192.168.3.4" )

Return values:

  1. 4- or 16-byte string representing IP address (or nil in case of an error).
  2. String error message in case of an error
isPrivate (ip)

Checks to see if the supplied IP address is part of a non-routable address space.

The non-Internet-routable address spaces known to this function are

  • IPv4 Loopback (RFC3330)
  • IPv4 Private Use (RFC1918)
  • IPv4 Link Local (RFC3330)
  • IPv4 IETF Protocol Assignments (RFC 5736)
  • IPv4 TEST-NET-1, TEST-NET-2, TEST-NET-3 (RFC 5737)
  • IPv4 Network Interconnect Device Benchmark Testing (RFC 2544)
  • IPv4 Reserved for Future Use (RFC 1112, Section 4)
  • IPv4 Multicast Local Network Control Block (RFC 3171, Section 3)
  • IPv6 Unspecified and Loopback (RFC3513)
  • IPv6 Site-Local (RFC3513, deprecated in RFC3879)
  • IPv6 Unique Local Unicast (RFC4193)
  • IPv6 Link Local Unicast (RFC4291)

Parameters

ip
String representing an IPv4 or IPv6 address. Shortened notation is permitted.

Usage:

local is_private = ipOps.isPrivate( "192.168.1.1" )

Return values:

  1. True or false (or nil in case of an error).
  2. String error message in case of an error or String non-routable address containing the supplied IP address.
str_to_ip (ip)

Converts an opaque string (big-endian) into an IP address

Parameters

ip
Opaque string representing an IP address. If length 4, then IPv4 is assumed. If length 16, then IPv6 is assumed.

Return values:

  1. IP address in readable notation (or nil in case of an error)
  2. String error message in case of an error
subnet_to_cidr (subnet)

Convert a dotted decimal subnet mask to CIDR notation.

Parameters

subnet
Dotted decimal string representing the subnet mask.

Usage:

local cidr = ipOps.subnet_to_cidr( "255.255.0.0" )

Return value:

CIDR representation of the supplied subnet mask (e.g. "/16").
todword (ip)

Converts the supplied IPv4 address into a DWORD value.

For example, the address a.b.c.d becomes (((a*256+b)*256+c)*256+d).

Note: IPv6 addresses are not supported. Currently, numbers in NSE are limited to 10^14, and consequently not all IPv6 addresses can be represented. Consider using ip_to_str for IPv6 addresses.

Parameters

ip
String representing an IPv4 address. Shortened notation is permitted.

Usage:

local dword = ipOps.todword( "73.150.2.210" )

Return values:

  1. Number corresponding to the supplied IP address (or nil in case of an error).
  2. String error message in case of an error.