chronos/transports/ipnet

    Dark Mode
Search:
Group by:
  Source   Edit

This module implements various IP network utility procedures.

Types

IpMask = object
  case family*: AddressFamily
  of AddressFamily.None, AddressFamily.Unix:
      nil

  of AddressFamily.IPv4:
      mask4*: uint32

  of AddressFamily.IPv6:
      mask6*: array[2, uint64]

  
  Source   Edit
IpNet = object
  host*: TransportAddress
  mask*: IpMask
  Source   Edit

Procs

proc `$`(mask: IpMask; include0x = false): string {....raises: [], tags: [].}
Returns hexadecimal string representation of IP mask mask.   Source   Edit
proc `$`(net: IpNet): string {....raises: [], tags: [].}
Return string representation of IP network in format: <IPv4 or IPv6 address>/<prefix length>.   Source   Edit
proc `+`(address: TransportAddress; v: int | uint): TransportAddress {.
    ...raises: [].}
Add to IPv4/IPv6 transport address integer v.   Source   Edit
proc `-`(address: TransportAddress; v: int | uint): TransportAddress {.
    ...raises: [].}
Sub from IPv4/IPv6 transport address integer v.   Source   Edit
proc `==`(m1, m2: IpMask): bool {.inline, ...raises: [], tags: [].}
Returns true if masks m1 and m2 are equal in IP family and by value.   Source   Edit
proc `==`(n1, n2: IpNet): bool {.inline, ...raises: [], tags: [].}
Returns true if networks n1 and n2 are equal in IP family and by value.   Source   Edit
proc `and`(address1, address2: TransportAddress): TransportAddress {....raises: [],
    tags: [].}

Bitwise and operation for address1 and address2.

Note only IPv4 and IPv6 addresses are supported. address1 and address2 must be in equal IP family

  Source   Edit
proc `not`(address: TransportAddress): TransportAddress {....raises: [], tags: [].}
Bitwise not operation for address.   Source   Edit
proc `or`(address1, address2: TransportAddress): TransportAddress {....raises: [],
    tags: [].}

Bitwise or operation for address1 or address2.

Note only IPv4 and IPv6 addresses are supported. address1 and address2 must be in equal IP family

  Source   Edit
proc broadcast(net: IpNet): TransportAddress {....raises: [], tags: [].}
Returns broadcast address for IP Network net.   Source   Edit
proc contains(net: IpNet; address: TransportAddress): bool {....raises: [],
    tags: [].}
Returns true if address belongs to IP Network net   Source   Edit
proc dec(address: var TransportAddress; v: int = 1) {....raises: [], tags: [].}
Decrement IPv4/IPv6 transport address by integer v.   Source   Edit
proc inc(address: var TransportAddress; v: int = 1) {....raises: [], tags: [].}
Increment IPv4/IPv6 transport address by integer v.   Source   Edit
proc init(t: typedesc[IpMask]; family: AddressFamily; prefix: int): IpMask {.
    ...raises: [].}
Initialize mask of IP family family from prefix length prefix.   Source   Edit
proc init(t: typedesc[IpMask]; netmask: string): IpMask {....raises: [].}

Initialize network mask using hexadecimal string representation netmask.

If netmask mask is invalid, result IpMask.family will be set to AddressFamily.None.

  Source   Edit
proc init(t: typedesc[IpMask]; netmask: TransportAddress): IpMask {....raises: [].}
Initialize network mask using address netmask.   Source   Edit
proc init(t: typedesc[IpNet]; host, mask: TransportAddress): IpNet {.inline,
    ...raises: [].}

Initialize IP Network using host address host and network mask address mask.

Note that host and mask must be from the same IP family.

  Source   Edit
proc init(t: typedesc[IpNet]; host: TransportAddress; mask: IpMask): IpNet {.
    inline, ...raises: [].}
Initialize IP Network using host address host and network mask mask.   Source   Edit
proc init(t: typedesc[IpNet]; host: TransportAddress; prefix: int): IpNet {.
    inline, ...raises: [].}
Initialize IP Network using host address host and prefix length prefix.   Source   Edit
proc init(t: typedesc[IpNet]; network: string): IpNet {.
    ...raises: [TransportAddressError], raises: [].}
Initialize IP Network from string representation in format <address>/<prefix length> or <address>/<netmask address>.   Source   Edit
proc initIp(t: typedesc[IpMask]; netmask: string): IpMask {....raises: [].}

Initialize network mask using IPv4 or IPv6 address in text representation netmask.

If netmask address string is invalid, result IpMask.family will be set to AddressFamily.None.

  Source   Edit
proc ip(mask: IpMask): string {....raises: [ValueError], raises: [], tags: [].}
Returns IP address text representation of IP mask mask.   Source   Edit
proc isAnyLocal(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is a wildcard address.

IPv4: 0.0.0.0

IPv6: ::

  Source   Edit
proc isBenchmarking(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is part of the 198.18.0.0/15 range, which is reserved for network devices benchmarking. This range is defined in [IETF RFC 2544] as 198.18.0.0 through 198.19.255.255 but [errata 423] corrects it to 198.18.0.0/15.

IPv4: 198.18.0.0/15

IPv6: 2001:2::/48

  Source   Edit
proc isBroadcast(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is a broadcast address.

IPv4: 255.255.255.255

  Source   Edit
proc isDocumentation(address: TransportAddress): bool {....raises: [], tags: [].}
Returns true if address is in a range designated for documentation.
IPv4: 192.0.2.0/24 (TEST-NET-1)
198.51.100.0/24 (TEST-NET-2) 203.0.113.0/24 (TEST-NET-3)

IPv6: 2001:DB8::/32

  Source   Edit
proc isGlobal(address: TransportAddress): bool {....raises: [], tags: [].}
Returns true if address appears to be globally reachable as specified by the [IANA IPv4 Special-Purpose Address Registry].   Source   Edit
proc isGlobalMulticast(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if the multicast address has global scope.

IPv4: 224.0.1.0 - 238.255.255.255

IPv6: FF0E:: - FFFE:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF

  Source   Edit
proc isInterfaceLocalMulticast(address: TransportAddress): bool {....raises: [],
    tags: [].}

Returns true if address is interface local multicast address.

IPv4: N/A (always returns false)

  Source   Edit
proc isLinkLocal(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is link local address.

IPv4: 169.254.0.0 - 169.254.255.255

IPv6: FE80:: - FEBF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF

  Source   Edit
proc isLinkLocalMulticast(address: TransportAddress): bool {....raises: [],
    tags: [].}

Returns true if address is link local multicast address.

IPv4: 224.0.0.0 - 224.0.0.255

  Source   Edit
proc isLinkLocalUnicast(address: TransportAddress): bool {.inline, ...raises: [],
    tags: [].}
  Source   Edit
proc isLoopback(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is loopback address.

IPv4: 127.0.0.0 - 127.255.255.255

IPv6: ::1

  Source   Edit
proc isMulticast(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is a multicast address.

IPv4: 224.0.0.0 - 239.255.255.255

IPv6: FF00:: - FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF

  Source   Edit
proc isNone(address: TransportAddress): bool {.inline, ...raises: [], tags: [].}
Returns true if address is not initialized yet, e.g. its family field is not set or equal to AddressFamily.None.   Source   Edit
proc isPrivate(address: TransportAddress): bool {....raises: [], tags: [].}
Alias for isSiteLocal().   Source   Edit
proc isReserved(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is reserved by IANA for future use. [IETF RFC 1112] defines the block of reserved addresses as 240.0.0.0/4.

NOTE: As IANA assigns new addresses, this procedure will be updated. This may result in non-reserved addresses being treated as reserved in code that relies on an outdated version of this procedure.

IPv4: 240.0.0.0/4

  Source   Edit
proc isShared(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is part of the Shared Address Space defined in [IETF RFC 6598]

IPv4: 100.64.0.0/10

  Source   Edit
proc isSiteLocal(address: TransportAddress): bool {....raises: [], tags: [].}
Returns true if address is site local address.
IPv4: 10.0.0.0 - 10.255.255.255, 172.16.0.0 - 172.31.255.255,
192.168.0.0 - 192.168.255.255

IPv6: FEC0:: - FEFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF

  Source   Edit
proc isUnicast(address: TransportAddress): bool {....raises: [], tags: [].}
Returns true if address is unicast, as defined by [IETF RFC 4291]. Any address that is not a IPv6 multicast address FF00::/8 is unicast.   Source   Edit
proc isUnicastLinkLocal(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is a IPv6 unicast address with link-local scope.

NOTE: While [RFC 4291 section 2.5.3] mentions about the [loopback address] ::1 that "it is treated as having Link-Local scope", this does not mean that the loopback address actually has link-local scope and procedure will return false on it.

IPv6: FE80::/10

  Source   Edit
proc isUniqueLocal(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is a unique local IPv6 unicast address.

IPv6: FC00::/7

  Source   Edit
proc isUnspecified(address: TransportAddress): bool {.inline, ...raises: [],
    tags: [].}
Alias for isZero().   Source   Edit
proc isV4Mapped(address: TransportAddress): bool {....raises: [], tags: [].}

Returns true if address is (IPv4 to IPv6) mapped address, e.g. 0000:0000:0000:0000:0000:FFFF:xxxx:xxxx

Procedure returns false if address family is IPv4.

  Source   Edit
proc isZero(address: TransportAddress): bool {.inline, ...raises: [], tags: [].}
Returns true if address is full of zeros, but its family is not AddressFamily.None.   Source   Edit
proc mask(a: TransportAddress; m: IpMask): TransportAddress {....raises: [],
    tags: [].}

Apply IP mask m to address a and return result address.

If a family is IPv4 and m family is IPv6, masking is still possible when m has FFFF:FFFF:FFFF:FFFF:FFFF:FFFF prefix. Returned value will be IPv4 address.

If a family is IPv6 and m family is IPv4, masking is still possible when a holds (IPv4 to IPv6) mapped address. Returned value will be IPv6 address.

If a family is IPv4 and m family is IPv4, returned value will be IPv4 address.

If a family is IPv6 and m family is IPv6, returned value will be IPv6 address.

In all other cases returned address will have AddressFamily.None.

  Source   Edit
proc network(net: IpNet): TransportAddress {.inline, ...raises: [], tags: [].}
Returns network address (host address masked with network mask) for IP Network net.   Source   Edit
proc prefix(mask: IpMask): int {....raises: [], tags: [].}

Returns number of bits set 1 in IP mask mask.

Procedure returns -1 if mask is not canonical, e.g. has holes with 0 bits between 1 bits.

  Source   Edit
proc subnetMask(mask: IpMask): TransportAddress {....raises: [], tags: [].}
Returns TransportAddress representation of IP mask mask.   Source   Edit
proc subnetMask(net: IpNet): TransportAddress {....raises: [], tags: [].}
Returns netmask address for IP Network net.   Source   Edit
proc toIPv4(address: TransportAddress): TransportAddress {....raises: [], tags: [].}

Get IPv4 from (IPv4 to IPv6) mapped address.

If address is IPv4 address it will be returned without any changes.

If address is not IPv4 to IPv6 mapped address, then result family will be set to AddressFamily.None.

  Source   Edit
proc toIPv6(address: TransportAddress): TransportAddress {....raises: [], tags: [].}

Map IPv4 address to IPv6 address.

If address is IPv4 address then it will be mapped as: <80 bits of zeros> + <16 bits of ones> + <32-bit IPv4 address>.

If address is IPv6 address it will be returned without any changes.

  Source   Edit