r00t2/go_goutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

checking in some WIP

Browse Source 
* added some netx funcs
* added netx/dnsx
* currently updating docs and adding *x funcs to sprigx
This commit is contained in:
brent saner
2026-02-24 17:41:57 -05:00
parent 4770052b52
commit c6fc692f5e
14 changed files with 2773 additions and 646 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
netx/dnsx/errors.go Normal file
View File

@@ -0,0 +1,12 @@
package dnsx
import (
`errors`
)
var (
ErrBadChars error = errors.New("netx/dnsx: invalid characters/encoding were encountered")
ErrBadLabelLen error = errors.New("netx/dnsx: a label with invalid length was encountered")
ErrBadPtrLen error = errors.New("netx/dnsx: a PTR record with invalid length was encountered")
ErrBadPtrRoot error = errors.New("netx/dnsx: a PTR record with invalid root encountered")
)

571
netx/dnsx/funcs.go Normal file
View File

@@ -0,0 +1,571 @@
package dnsx
import (
`bytes`
`encoding/base32`
`fmt`
`math`
`net`
`net/netip`
`strings`
`go4.org/netipx`
`r00t2.io/goutils/stringsx`
)
/*
AddrFromPtr returns a [net/netip.Addr] from a PTR record.
It is the inverse of [AddrToPtr].
See also [IpFromPtr].
*/
func AddrFromPtr(s string) (ip netip.Addr, err error) {
var idx int
var ipStr string
var tmpStr string
var spl []string = strings.Split(strings.TrimSuffix(s, "."), ".")
switch len(spl) {
case 6:
if strings.Join(spl[4:], ".") != "in-addr.arpa" {
err = ErrBadPtrRoot
return
}
ipStr = fmt.Sprintf("%s.%s.%s.%s", spl[3], spl[2], spl[1], spl[0])
case 34:
if strings.Join(spl[32:], ".") != "ip6.arpa" {
err = ErrBadPtrRoot
return
}
tmpStr = stringsx.Reverse(strings.ReplaceAll(strings.Join(spl[:32], ""), ".", ""))
for idx = 0; idx < len(tmpStr); idx++ {
if idx%4 == 0 && idx != 0 {
ipStr += ":"
}
ipStr += string(rune(tmpStr[idx]))
}
default:
err = ErrBadPtrLen
return
}
if ip, err = netip.ParseAddr(ipStr); err != nil {
return
}
return
}
/*
AddrToPtr returns a PTR record from ip.
It is the inverse of [AddrFromPtr].
It includes the root label at the end (the trailing period).
*/
func AddrToPtr(ip netip.Addr) (s string) {
var idx int
var b []byte
var ipStr string
if ip.Is6() {
ipStr = stringsx.Reverse(strings.ReplaceAll(ip.StringExpanded(), ":", ""))
ipStr = strings.Join(
strings.Split(ipStr, ""),
".",
)
s = fmt.Sprintf("%s.ip6.arpa.", ipStr)
} else {
b = make([]byte, 4)
copy(b, ip.AsSlice())
for idx = len(b) - 1; idx >= 0; idx-- {
ipStr += fmt.Sprintf("%d.", b[idx])
}
s = fmt.Sprintf("%s.in-addr.arpa.", ipStr)
}
return
}
/*
DnsStrToWire returns a wire-format of a DNS name.
No validation or conversion (other than to wire format) is performed,
and it is expected that any IDN(A)/Punycode translation has
*already been performed* such that recordNm is in the ASCII form.
(See [IsFqdn] for more information on IDN(A)/Punycode.)
For encoding reasons, if any given label/segment has a length of 0 or greater than 255 ([math.MaxUint8]),
[ErrBadLabelLen] will be returned.
See [DnsWireToStr] for the inverse.
*/
func DnsStrToWire(recordNm string) (recordNmBytes []byte, err error) {
var cLen int
var c []byte
var cStr string
var spl []string
var buf *bytes.Buffer = new(bytes.Buffer)
spl = strings.Split(strings.TrimSuffix(recordNm, "."), ".")
for _, cStr = range spl {
c = []byte(cStr)
cLen = len(c)
if !(cLen > 0 && cLen <= math.MaxUint8) {
err = ErrBadLabelLen
return
}
buf.Write(append([]byte{uint8(cLen)}, c...))
}
recordNmBytes = append(buf.Bytes(), 0x00)
return
}
/*
DnsWireToStr is the inverse of [DnsStrToWire]. A trailing . is not included.
For decoding reasons, it will exit with [ErrBadLabelLen] if recordNmBytes is nil/empty or
if no terminating nullbyte is found after 256 label characters have been encountered.
*/
func DnsWireToStr(recordNmBytes []byte) (recordNm string, err error) {
var c []byte
var cLen uint8
var arrLen int
var numChars int
var labels []string
var buf *bytes.Buffer
if recordNmBytes == nil || len(recordNmBytes) == 0 {
err = ErrBadLabelLen
return
}
buf = bytes.NewBuffer(recordNmBytes)
labels = make([]string, 0)
arrLen = len(recordNmBytes)
for {
if cLen, err = buf.ReadByte(); err != nil {
return
}
if cLen == 0x00 {
break
}
numChars += int(cLen)
if numChars > 255 {
err = ErrBadLabelLen
return
}
if numChars > arrLen {
err = ErrBadLabelLen
return
}
c = buf.Next(int(cLen))
labels = append(labels, string(c))
}
recordNm = strings.Join(labels, ".")
return
}
/*
IpFromPtr is like [AddrFromPtr] but with a [net.IP] instead.
It is the inverse of [IpToPtr].
*/
func IpFromPtr(s string) (ip net.IP, err error) {
var a netip.Addr
if a, err = AddrFromPtr(s); err != nil {
return
}
ip = net.IP(a.AsSlice())
return
}
/*
IpToPtr is like [AddrToPtr] but with a [net.IP] instead.
It is the inverse of [IpFromPtr].
*/
func IpToPtr(ip net.IP) (s string) {
var a netip.Addr
a, _ = netipx.FromStdIP(ip)
s = AddrToPtr(a)
return
}
/*
IsFqdn returns a boolean indicating if s is an FQDN that strictly adheres to RFC format requirements.
It performs no lookups/resolution attempts or network operations otherwise.
It will return true for the "apex record" (e.g. the "naked domain"), as this is a valid assignable FQDN.
It will return false for wildcard records (see [IsFqdnWildcard]).
s may or may not end in a period (the root zone; "absolute" FQDNs) (0x00 in wire format).
# TLDs
Because valid TLDs are fairly dynamic and can change frequently,
validation is *not* performed against the TLD itself.
This only ensures that s has a TLD label conforming to the character rules in the referenced RFCs.
See [golang.org/x/net/publicsuffix] if precise TLD validation is required (though true TLD validation generally
requires fetching the current TLD lists from IANA at runtime like [github.com/bombsimon/tld-validator]).
# Special RFC-Defined Accommodations
RFC 2181 [§ 11] specifies that site-local DNS software may accommodate non-RFC-conforming rules.
This function may and likely will return false for these site-local deviations.
The Lookup* functions/mthods in [net] should be used to validate in these casts
if that accommodation is necessary.
Note that underscores are not valid for "true" FQDNs as they are only valid for e.g. SRV record names,
TXT records, etc. - not A/AAAA/CNAME, etc. - see RFC 8553 for details.
See the following functions for allowing additional syntax/rule validation
that have record-type-specific accommodations made:
* [IsFqdnDefinedTxt]
* [IsFqdnNsec3]
* [IsFqdnSrv]
* [IsFqdnWildcard]
# RFC Coverage
This function should conform properly to:
* RFC 952
* RFC 1034 and RFC 1035
* RFC 1123
* RFC 2181 (selectively, see above)
preferring the most up-to-date rules where relevant (e.g. labels may start with digits, as per RFC 1123).
It enforces/checks label and overall length limits as defined by RFC.
# IDN(A) and Punycode
Note that it expects the ASCII-only/presentation form of a record name and
will not perform any IDN/IDNA nor Punycode translation.
If a caller anticipates FQDNs in their localized format,
the caller must perform translation first
(via e.g. [gitlab.com/golang-commonmark/puny], [golang.org/x/net/idna], etc.).
To reiterate, IDN/IDNA:
* RFC 3490
* RFC 5890
* RFC 5891
* RFC 5892
* RFC 5893
* RFC 5894
and Punycode (RFC 3492) *MUST* use their ASCII forms, NOT the localized/Unicode formats.
[§ 11]: https://datatracker.ietf.org/doc/html/rfc2181#section-11
*/
func IsFqdn(s string) (fqdn bool) {
var lbl string
var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
if !commonFqdn(s) {
return
}
for _, lbl = range lbls {
if !IsLabel(lbl) {
return
}
}
fqdn = true
return
}
/*
IsFqdnDefinedTxt is like [IsFqdn] but explicitly *only* allows fully-qualified
RFC-defined TXT "subtypes":
* ACME DNS-01 (RFC 8555)
* BIMI (RFC draft [bimi])
* DKIM (RFC 6376, RFC 8301, RFC 8463)
* DKIM ATPS (RFC 6541)
* DMARC (RFC 7489, RFC 9091, RFC 9616)
* MTA-STS (RFC 8461)
* TLSRPT (RFC 8460)
Note that the following TXT "subtypes" do not have special formatting in labels/name,
and thus are not covered by this function:
* SPF (RFC 4408, RFC 7208)
[bimi]: https://datatracker.ietf.org/doc/html/draft-brand-indicators-for-message-identification
*/
func IsFqdnDefinedTxt(fqdn string) (isOk bool) {
var lbls []string = strings.Split(fqdn, ".")
if lbls == nil || len(lbls) < 2 {
return
}
switch lbls[0] {
case "_dmarc", "_mta-sts", "_acme-challenge":
if len(lbls) < 2 {
return
}
isOk = IsFqdn(strings.Join(lbls[1:], "."))
case "_smtp":
if len(lbls) <= 2 {
return
}
if lbls[1] != "_tls" {
return
}
isOk = IsFqdn(strings.Join(lbls[2:], "."))
default:
if !IsLabel(lbls[0]) {
return
}
switch lbls[1] {
case "_domainkey", "_atps", "_bimi":
isOk = IsFqdn(strings.Join(lbls[2:], "."))
}
}
// TODO
return
}
/*
IsFqdnNsec3 confirms (partially) that s is a valid NSEC3 record name.
Note that due to the record name being a base32 encoding of a *hash*, the validity
can't be 100% confirmed with certainty - only basic checks can be done.
NSEC3 can be found via:
* RFC 5155
* RFC 6840
* RFC 6944
* RFC 7129
* RFC 8198
* RFC 9077
* RFC 9157
* RFC 9276
* RFC 9905
At the time of writing, only one hashing algorithm (SHA-1) has been specified.
However, because this function does not check against the IANA registration at runtime,
it's possible that this changes but the library may not immediately reflect this.
*/
func IsFqdnNsec3(s string) (maybeNsec3 bool) {
var h []byte
var err error
var isAscii bool
var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
if !commonFqdn(s) {
return
}
if len(lbls) <= 2 {
return
}
if len(lbls[0]) != 32 { // SHA1 is 160 bits/20 bytes digest, which is always 32 chars in base32(hex)
return
}
if h, err = base32.StdEncoding.DecodeString(strings.ToUpper(lbls[0])); err != nil {
return
}
if isAscii, err = stringsx.IsAsciiSpecial(
strings.ToLower(lbls[0]),
false, false, false, false,
[]byte{
// Normally, Base32 goes A-Z, 2-7
// but NSEC3 uses Base32Hex (RFC 4648 § 7),
// which is 0-9A-V
'0', '1', '2', '3', '4', '5',
'6', '7', '8', '9', 'a', 'b',
'c', 'd', 'e', 'f', 'g', 'h',
'j', 'k', 'm', 'n', 'p', 'q',
'r', 's', 't', 'u', 'v',
},
nil,
); err != nil {
return
}
if isAscii {
return
}
if len(h) != 20 {
return
}
maybeNsec3 = IsFqdn(strings.Join(lbls[1:], "."))
return
}
/*
IsFqdnSrv is like [IsFqdn], but explicitly *only* allows fully-qualified SRV records
(i.e. underscores must start the first two labels, and there must be at least two additional
labels after these labels).
Note that the protocol is not checked for validity, as that would require runtime
validation against a resource liable to change and would need to be fetched dynamically - see
the [IANA Protocol Numbers registry].
[IANA Protocol Numbers registry]: https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml
*/
func IsFqdnSrv(s string) (srv bool) {
var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
if !commonFqdn(s) {
return
}
if len(lbls) <= 4 {
return
}
if !strings.HasPrefix(lbls[0], "_") {
return
}
if !strings.HasPrefix(lbls[1], "_") {
return
}
srv = IsFqdn(strings.Join(lbls[2:], "."))
return
}
// IsFqdnWildcard is like [IsFqdn] but explicitly *only* allows fully-qualified wildcard records.
func IsFqdnWildcard(s string) (wildcard bool) {
var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
if len(lbls) < 2 {
return
}
if lbls[0] != "*" {
return
}
wildcard = IsFqdn(strings.Join(lbls[1:], "."))
return
}
// IsLabel returns true if s is a valid DNS label for standard records.
func IsLabel(s string) (isLbl bool) {
var err error
if strings.HasPrefix(s, "-") {
return
}
if strings.HasSuffix(s, "-") {
return
}
if isLbl, err = stringsx.IsAsciiSpecial(
s,
false, false, false, false,
[]byte{
'a', 'b', 'c', 'd', 'e', 'f',
'g', 'h', 'i', 'j', 'k', 'l',
'm', 'n', 'o', 'p', 'q', 'r',
's', 't', 'u', 'v', 'w', 'x',
'y', 'z', '0', '1', '2', '3',
'4', '5', '6', '7', '8', '9',
'-',
},
nil,
); err != nil {
return
}
return
}
/*
IsPtr returns true if s is a PTR (also called an "rDNS" or "reverse DNS" record) name.
If true, the IP is returned as well (otherwise it will be nil).
*/
func IsPtr(s string) (isPtr bool, addr net.IP) {
var err error
var lbls []string = strings.Split(strings.TrimSuffix(s, "."), ".")
if len(lbls) < 6 {
return
}
if _, err = AddrFromPtr(s); err != nil {
return
}
isPtr = true
return
}
// commonFqdn is used to validate some rules common to all record names.
func commonFqdn(s string) (isOk bool) {
var err error
var lbl string
var isAscii bool
var labels []string
var domstr string = strings.ToLower(strings.TrimSuffix(s, "."))
if isAscii, err = stringsx.IsAsciiSpecial(
domstr, false, false, false, false,
[]byte{
'a', 'b', 'c', 'd', 'e', 'f',
'g', 'h', 'i', 'j', 'k', 'l',
'm', 'n', 'o', 'p', 'q', 'r',
's', 't', 'u', 'v', 'w', 'x',
'y', 'z', '0', '1', '2', '3',
'4', '5', '6', '7', '8', '9',
'-', '_', '.',
},
nil,
); err != nil {
return
}
if !isAscii {
return
}
if (len(domstr) + 1) > 255 { // +1 for root label
return
}
labels = strings.Split(domstr, ".")
for _, lbl = range labels {
if len(lbl) < 1 || len(lbl) > 63 {
return
}
}
// TODO?
isOk = true
return
}

29
netx/dnsx/funcs_test.go Normal file
View File

@@ -0,0 +1,29 @@
package dnsx
import (
`net/netip`
"testing"
)
func TestPtr(t *testing.T) {
var err error
var ptr string
var ip netip.Addr
var ipStr string = "::ffff:192.168.0.1"
var ptrStr string = "1.0.0.0.8.a.0.c.f.f.f.f.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa."
if ip, err = AddrFromPtr(ptrStr); err != nil {
t.Fatal(err)
}
t.Logf("PTR -> Addr: %s -> %s", ptrStr, ip.String())
if ip.String() != ipStr {
t.Fatalf("expect IP %v, got %v", ipStr, ip.String())
}
ptr = AddrToPtr(ip)
if ptr != ptrStr {
t.Fatalf("expect PTR %v, got %v", ptrStr, ptr)
}
t.Logf("Addr -> PTR: %s -> %s", ip.String(), ptr)
}

220
netx/funcs.go
View File

@@ -102,11 +102,37 @@ func Cidr4ToStr(cidr uint8) (maskStr string, err error) {
return
}
/*
FamilyToVer returns a more "human-friendly" IP version from a system/lower-level IP family
([AFUnspec], [AFInet], [AFInet6]).
ipVer will be int(4) for [AFInet], int(6) for [AFInet6], int(0) for [AFUnspec], or
int(-1) for an unknown family.
*/
func FamilyToVer(family uint16) (ipVer int) {
switch family {
case AFInet:
ipVer = 4
case AFInet6:
ipVer = 6
case AFUnspec:
ipVer = 0
default:
ipVer = -1
}
return
}
/*
GetAddrFamily returns the network family of a [net/netip.Addr].
See also [GetIpFamily].
Note that this returns [AFInet] or [AFInet6], NOT uint16(4) or uint16(6).
(See [FamilyToVer] to get the associated higher-level value.)
If addr is not a "valid" IP address or the version can't be determined, family will be AFUnspec (usually 0x00/0).
*/
func GetAddrFamily(addr netip.Addr) (family uint16) {
@@ -131,6 +157,9 @@ func GetAddrFamily(addr netip.Addr) (family uint16) {
/*
GetIpFamily returns the network family of a [net.IP].
Note that this returns [AFInet] or [AFInet6], NOT uint16(4) or uint16(6).
(See [FamilyToVer] to get the associated higher-level value.)
See also [GetAddrFamily].
If ip is not a "valid" IP address or the version can't be determined,
@@ -158,6 +187,8 @@ If ip is an IPv4 address, it will simmply be the string representation (e.g. "20
If ip is an IPv6 address, it will be enclosed in brackets (e.g. "[2001:db8::1]").
If the version can't be determined, rfcStr will be an empty string.
See also [IpRfcStr] for providing an IP address as a string.
*/
func IpRfc(ip net.IP) (rfcStr string) {
@@ -170,6 +201,56 @@ func IpRfc(ip net.IP) (rfcStr string) {
return
}
/*
IpRfcStr implements [IpRfc]/[AddrRfc] for string representations of an IP address s.
If s is an IPv6 address already in the bracketed RFC format,
then rfcStr will be equal to s.
If s is not a string representation of an IP address, rfcStr will be empty.
See [IpStripRfcStr] for the inverse (removing any brackets from s if present).
*/
func IpRfcStr(s string) (rfcStr string) {
var ip net.IP
if !IsIpAddr(s) {
return
}
if IsBracketedIp6(s) {
rfcStr = s
return
}
ip = net.ParseIP(s)
if ip == nil {
return
}
rfcStr = IpRfc(ip)
return
}
/*
IpStripRfcStr returns IP address string s without any brackets.
If s is not a valid IP address, stripStr will be empty.
*/
func IpStripRfcStr(s string) (stripStr string) {
if !IsIpAddr(s) {
return
}
if !IsBracketedIp6(s) {
stripStr = s
return
}
stripStr = strings.TrimPrefix(s, "[")
stripStr = strings.TrimSuffix(stripStr, "]")
return
}
/*
IPMask4ToCidr returns a CIDR prefix size/bit size/bit length from a [net.IPMask].
@@ -257,6 +338,123 @@ func IPMask4ToStr(ipMask net.IPMask) (maskStr string, err error) {
return
}
/*
IpVerStr provides the IP family of IP address/network string s.
s may be one of the following formats/syntaxes:
* 203.0.113.0
* 203.0.113.1
* 203.0.113.0/24
* 203.0.113.1/24
* 2001:db8::
* 2001:db8::1
* 2001:db8::/32
* 2001:db8::1/32
* [2001:db8::]
* [2001:db8::1]
Unlike [GetAddrFamily]/[GetIpFamily], this returns a more "friendly"
version - if s is not valid syntax, ipVer will be int(0),
otherwise ipVer will be int(4) for family IPv4 and int(6) for family IPv6.
(See [VerToFamily] to get the associated system/lower-level value.)
*/
func IpVerStr(s string) (ipVer int) {
var err error
var ipstr string
var p netip.Prefix
ipstr = strings.TrimPrefix(s, "[")
ipstr = strings.TrimSuffix(ipstr, "]")
if p, err = netip.ParsePrefix(ipstr); err != nil {
return
}
if p.Addr().Is6() {
ipVer = 6
} else {
ipVer = 4
}
return
}
/*
IsBracketedIp6 returns a boolean indicating if s is a valid bracket-enclosed IPv6 in string format
(e.g. "[2001:db8::1]").
It will return false for *non-bracketed* IPv6 addresses (e.g. "2001:db8::1"), IPv4 addresses,
or if s is not a valid IPv6 address string.
[IpRfcStr] or [IpStripRfcStr] can be used to coerce a string to a specific format.
*/
func IsBracketedIp6(s string) (isBrktdIp bool) {
var ip net.IP
var ipstr string
if IpVerStr(s) != 6 {
return
}
ipstr = strings.TrimPrefix(s, "[")
ipstr = strings.TrimSuffix(ipstr, "]")
if ip = net.ParseIP(ipstr); ip == nil {
return
}
isBrktdIp = ipstr == s
return
}
/*
IsIpAddr returns a boolean indicating if s is an IP address (either IPv4 or IPv6) in string format.
For IPv6, it will return true for both of these formats:
* 2001:db8::1
* [2001:db8::1]
[IsBracketedIp6] can be used to narrow down which form.
*/
func IsIpAddr(s string) (isIp bool) {
var err error
var a netip.Addr
if a, err = netip.ParseAddr(s); err != nil {
return
}
isIp = a.IsValid()
return
}
/*
IsPrefixNet returns true if s is a (valid) IP address or network (either IPv4 or IPv6) in:
<addr_or_net>/<prefix_len>
format.
*/
func IsPrefixNet(s string) (isNet bool) {
var err error
var p netip.Prefix
if p, err = netip.ParsePrefix(s); err != nil {
return
}
isNet = p.Masked().IsValid()
return
}
/*
Mask4ToCidr converts an IPv4 netmask *in bitmask form* to a CIDR prefix size/bit size/bit length.
@@ -408,3 +606,25 @@ func Mask4StrToMask(maskStr string) (mask uint32, err error) {
return
}
/*
VerToFamily takes a "human-readable" IP version ipVer (4 or 6) and returns
a system-level constant (e.g. [AFUnspec], [AFInet], [AFInet6]).
If not a known IP version (i.e. neither 4 nor 6), family will be [AFUnspec].
It is the inverse of [FamilyToVer].
*/
func VerToFamily(ipVer int) (family uint16) {
switch ipVer {
case 4:
family = AFInet
case 6:
family = AFInet6
default:
family = AFUnspec
}
return
}

23
netx/funcs_test.go
View File

@@ -7,6 +7,29 @@ import (
"testing"
)
func TestFuncsDns(t *testing.T) {
var err error
var domBin []byte
var domStr string
var domEx string = "foo.r00t2.io"
if domBin, err = DnsStrToWire(domEx); err != nil {
t.Fatal(err)
}
t.Logf("Domain %s to wire: %#x\n", domEx, domBin)
if domStr, err = DnsWireToStr(domBin); err != nil {
t.Fatal(err)
}
t.Logf("Domain wire %#x to string: %s\n", domBin, domStr)
if domStr != domEx {
t.Fatalf("DNS str wrong (%s != %s)\n)", domStr, domEx)
}
t.Logf("Domain string %s matches %s", domStr, domEx)
return
}
func TestFuncsIP(t *testing.T) {
var err error