# net.mac-address

Checks that a text is an EUI-48 (MAC) address and normalises it to lower-case,
colon-separated form, `00:1b:63:84:45:e6`. It never throws: an invalid address
comes back with `valid: false` and a short `reason`, so an inventory can list
every bad entry instead of stopping at the first.

## Forms accepted

Exactly four, in either case:

| form | example | where you see it |
|------|---------|------------------|
| colon | `00:1b:63:84:45:e6` | Linux, macOS, IEEE 802 |
| hyphen | `00-1B-63-84-45-E6` | Windows |
| Cisco dotted | `001b.6384.45e6` | Cisco IOS |
| bare | `001b638445e6` | databases, DHCP exports |

Refused, deliberately:

- mixed separators (`00:1b-63:...`): `mixed separators`;
- single-digit octets (`0:1b:63:84:45:e6`), which some tools print but which
  are more often a typo than an address; EUI-64 and short forms:
  `not a recognised MAC address format`;
- surrounding whitespace, including a trailing newline: nothing is trimmed,
  so trim input yourself if you mean to;
- anything that is not an ASCII hex digit, including non-ASCII digits and
  fullwidth letters: `not a hex digit`. Lengths are counted in characters in
  every language, so they fail the same way everywhere.

## What the bits say

- `multicast` is the I/G bit, the least significant bit of the first octet: a
  group address (`01:00:5e:...` for IPv4 multicast, `ff:ff:ff:ff:ff:ff`
  broadcast) rather than one interface.
- `locallyAdministered` is the U/L bit, the next bit up: the address was set
  by software (Docker's `02:42:...`, VMs, randomised Wi-Fi MACs) rather than
  assigned by the maker.
- `oui` is the first three octets as the IEEE registry writes them, `00-1B-63`.
  For a locally administered address it is not a real maker's OUI.

Source: IEEE 802-2014 section 8.2 (MAC address format, I/G and U/L bits), and
the IEEE "Guidelines for Use of Extended Unique Identifier (EUI)".