mac_address v0.0.1 MACAddress View Source
This module provides common functions for working with MAC addresses.
Overview
MACAddress offers helper functions and generally makes working with MAC addresses easier in Elixir.
A major focus of this module is to support consumers of MAC addresses such as cryptographically secure ID generators, commonly found in distributed systems.
Limitations
Working with MAC addresses in Elixir is typically done through the :inet module. As such, any limitations that exist in :inet are typically true here as well. Most notably, this includes situations where querying addresses requires super user privileges, such as has been observed on Solaris.
Link to this section Summary
Functions
Creates a cryptographically secure random MAC address with the broadcast bit set
Converts a MAC address from a string hex representation to an Elixir binary representation
Converts a MAC address from a string hex representation to an Elixir binary representation
Returns the MAC address, if any, for the given interface name
Returns the MAC address, if any, for the given interface name
Returns a tuple of interface name + mac address
Munges a MAC address in a cryptographically secure way so it no longer leaks public details but maintains uniqueness
Given a MAC address, munges the MAC address in a cryptographically secure way so it no longer leaks public details but maintains uniqueness
Converts a MAC binary to a hex formatted string with optional separators
Link to this section Types
String name of an interface.
MAC address Elixir binary.
Link to this section Functions
Creates a cryptographically secure random MAC address with the broadcast bit set.
Useful for ID generation, testing, etc.
from_hex!(charlist() | binary(), keyword()) :: mac_address()
Converts a MAC address from a string hex representation to an Elixir binary representation.
If the address cannot be converted, an exception is raised.
Options
The accepted options are:
:separators- A list of binaries that are possible separators. Defaults to “:” and “-“ if none are specified.
Examples
iex> MACAddress.from_hex!("00:A0:C9:14:C8:29")
<<0, 160, 201, 20, 200, 41>>
iex> MACAddress.from_hex!("06-b0-b9-42-d8-42", separators: ["-"])
<<6, 176, 185, 66, 216, 66>>
iex> MACAddress.from_hex!("06b0b942d842")
<<6, 176, 185, 66, 216, 66>>
iex> MACAddress.from_hex!("06%%b0%%b9%%42%%d8%%42", separators: "%%")
<<6, 176, 185, 66, 216, 66>>from_hex(binary(), keyword()) :: {:ok, mac_address()} | :error
Converts a MAC address from a string hex representation to an Elixir binary representation.
If the address cannot be converted, :error is returned.
Options
The accepted options are:
:separators- A list of binaries that are possible separators. Defaults to “:” and “-“ if none are specified.
Examples
iex> MACAddress.from_hex("00:A0:C9:14:C8:29")
{:ok, <<0, 160, 201, 20, 200, 41>>}
iex> MACAddress.from_hex("00-A0-C9-14-C8-29")
{:ok, <<0, 160, 201, 20, 200, 41>>}
iex> MACAddress.from_hex("00*A0*C9*14*C8*29", separators: "*")
{:ok, <<0, 160, 201, 20, 200, 41>>}
iex> MACAddress.from_hex("F")
:errormac_address!(interface_name()) :: mac_address()
Returns the MAC address, if any, for the given interface name.
The returned MAC address is limited by the :inet module.
mac_address(interface_name()) :: {:ok, mac_address()} | {:error, :inet.posix()} | :error
Returns the MAC address, if any, for the given interface name.
The returned MAC address is limited by the :inet module.
Returns an error if the given interface cannot be found or doesn’t have a valid MAC address.
mac_addresses() ::
{:ok, {interface_name(), [mac_address()]}} | {:error, :inet.posix()}
Returns a tuple of interface name + mac address.
Returns an error if there is a problem accessing the MAC addresses.
The returned MAC addresses are limited to those readable by the :inet module.
Munges a MAC address in a cryptographically secure way so it no longer leaks public details but maintains uniqueness.
Selects the first MAC address found, and if none are available, it will generate a random MAC address using broadcast_address/1.
See munge_address/2 for passing a specific MAC address.
Useful for anything that may publicly expose a MAC address to the outside world, such as an ID generator. Ex: Twitter Snowflake.
munge_address(mac_address()) :: mac_address()
Given a MAC address, munges the MAC address in a cryptographically secure way so it no longer leaks public details but maintains uniqueness.
Useful for anything that may publicly expose a MAC address to the outside world, such as an ID generator. Ex: Twitter Snowflake.
to_hex(mac_address(), keyword()) :: binary()
Converts a MAC binary to a hex formatted string with optional separators.
Options
The accepted options are:
:case- specifies the character case to use when encoding:separator- specifies the separator between each hex byte.
The values for :case can be:
:upper- uses upper case characters:lower- uses lower case characters (default)
:separator may be any valid binary. Defaults to :.
Examples
iex> MACAddress.to_hex(<<6, 176, 185, 66, 216, 66>>)
"06:b0:b9:42:d8:42"
iex> MACAddress.to_hex(<<6, 176, 185, 66, 216, 66>>, case: :upper)
"06:B0:B9:42:D8:42"
iex> MACAddress.to_hex(<<6, 176, 185, 66, 216, 66>>, case: :lower, separator: "-")
"06-b0-b9-42-d8-42"
iex> MACAddress.to_hex(<<6, 176, 185, 66, 216, 66>>, case: :lower, separator: "")
"06b0b942d842"