TLS API: Module OverSIP::Utils

OverSIP provide the OverSIP::Utils module with helper methods.

Module class methods

string_compare(string1, string2)

Performs a string comparison by ensuring that two identical byte secuences are matched regardless they have different encoding.

For example, the following Ruby code would return false since the first string has BINARY encoding while the second string has UTF_8 encoding:

string1 = "iñaki".force_encoding(::Encoding::BINARY)
string2 = "iñaki".force_encoding(::Encoding::UTF_8)

string1 == string2
#=> false

Parameters

string1

A String. If it is not a String it is converted to it via the to_s() Ruby method.

string2

A String. If it is not a String it is converted to it via the to_s() Ruby method.

Example

string1 = "iñaki".force_encoding(::Encoding::BINARY)
string2 = "iñaki".force_encoding(::Encoding::UTF_8)

OverSIP::Utils.string_compare string1, string2
#=> true

regexp_compare(string, expression)

Performs a string regular expression comparison by ensuring that two identical byte secuences are matched regardless they have different encoding. It returns a Fixnum indicating the position in which the given string matches the expression (same as Ruby =~ method), or nil if there is no match.

For example, the following Ruby code would raise an error due to encoding incompatibilities:

string1 = "iñaki".force_encoding(::Encoding::BINARY)

string1 =~ /iñaki/
#=> Encoding::CompatibilityError: incompatible encoding regexp match (UTF-8 regexp with ASCII-8BIT string)

Parameters

string

A String. If it is not a String it is converted to it via the to_s() Ruby method.

expression

A String or a Regexp (between / and /). Otherwise it is converted to String via the to_s() Ruby method.

Example

string1 = "iñaki".force_encoding(::Encoding::BINARY)

OverSIP::Utils.regexp_compare string1, "^iñaki$"
#=> 0

OverSIP::Utils.regexp_compare string1, /^iñaki$/
#=> 0

OverSIP::Utils.regexp_compare string1, "ñ"
#=> 1

ip?(ip)

Returns true if the given ip is an IPv4, IPv6 or IPv6 reference.

Parameters

ip

A String containing an IP.

Examples

OverSIP::Utils.ip? "1.2.3.4"
#=> true

OverSIP::Utils.ip? "2001:838:2:1::30:67"
#=> true

OverSIP::Utils.ip? "[2001:838:2:1::30:67]"
#=> true

pure_ip?(ip)

Returns true if the given ip is an IPv4 or IPv6.

Parameters

ip

A String containing an IP.

Examples

OverSIP::Utils.ip? "1.2.3.4"
#=> true

OverSIP::Utils.ip? "2001:838:2:1::30:67"
#=> true

OverSIP::Utils.ip? "[2001:838:2:1::30:67]"
#=> false

ip_type(ip)

Returns the type of IP of the given ip:

• IPv4: :ipv4 (Symbol)
• IPv6: :ipv6 (Symbol)
• IPv6 reference: :ipv6_reference (Symbol)
• Other: false

Parameters

ip

A String containing an IP.

Examples

OverSIP::Utils.ip_type "1.2.3.4"
#=> :ipv4

OverSIP::Utils.ip_type "2001:838:2:1::30:67"
#=> :ipv6

OverSIP::Utils.ip_type "[2001:838:2:1::30:67]"
#=> :ipv6_reference

compare_ips(ip1, ip2)

Performs binary IP comparison between ip1 and ip2. It returns:

• true if both IP’s are equal (binary comparison).
• false if they are different.
• nil if ip1 or ip2 is not a valid IPv4, IPv6 or IPv6 reference.

This function matches an IPv6 with its IPv6 reference representation.

Parameters

ip1

A String containing an IP.

ip2

A String containing an IP.

Examples

OverSIP::Utils.compare_ips "2001:83A:2:1::30:67", "[2001:83a:002:001::030:067]"
#=> true

OverSIP::Utils.compare_ips "1.2.3.4", "example.net"
#=> nil

compare_pure_ips(ip1, ip2)

Same as compare_ips() method but IPv6 references are not allowed.

Example

OverSIP::Utils.compare_pure_ips "2001:83A:2:1::30:67", "[2001:83a:002:001::030:067]"
#=> nil

normalize_ipv6(ip, force_pure_ipv6=false)

Returns the normalized representation of the given ip if it contains an IPv6 or IPv6 reference (otherwise it returns false). If the second argument is true then the output of the method is a pure IPv6 regardless the given ip was an IPv6 reference.

Parameters

ip

A String containing an IPv6 or IPv6 reference.

force_pure_ipv6

Boolean (true/false).

Examples

OverSIP::Utils.normalize_ipv6 "2001:AA:00BB:001::030:067"
#=> "2001:aa:bb:1::30:67"

OverSIP::Utils.normalize_ipv6 "[2001:AA:00BB:001::030:067]"
#=> "[2001:aa:bb:1::30:67]"

OverSIP::Utils.normalize_ipv6 "[2001:AA:00BB:001::030:067]", true
#=> "2001:aa:bb:1::30:67"

OverSIP::Utils.normalize_ipv6 "example.net"
#=> false

OverSIP::Utils.normalize_ipv6 "1.2.3.4"
#=> false