1// Copyright 2009 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// IP address manipulations 6// 7// IPv4 addresses are 4 bytes; IPv6 addresses are 16 bytes. 8// An IPv4 address can be converted to an IPv6 address by 9// adding a canonical prefix (10 zeros, 2 0xFFs). 10// This library accepts either size of byte slice but always 11// returns 16-byte addresses. 12 13package net 14 15// IP address lengths (bytes). 16const ( 17 IPv4len = 4 18 IPv6len = 16 19) 20 21// An IP is a single IP address, a slice of bytes. 22// Functions in this package accept either 4-byte (IPv4) 23// or 16-byte (IPv6) slices as input. 24// 25// Note that in this documentation, referring to an 26// IP address as an IPv4 address or an IPv6 address 27// is a semantic property of the address, not just the 28// length of the byte slice: a 16-byte slice can still 29// be an IPv4 address. 30type IP []byte 31 32// An IP mask is an IP address. 33type IPMask []byte 34 35// An IPNet represents an IP network. 36type IPNet struct { 37 IP IP // network number 38 Mask IPMask // network mask 39} 40 41// IPv4 returns the IP address (in 16-byte form) of the 42// IPv4 address a.b.c.d. 43func IPv4(a, b, c, d byte) IP { 44 p := make(IP, IPv6len) 45 copy(p, v4InV6Prefix) 46 p[12] = a 47 p[13] = b 48 p[14] = c 49 p[15] = d 50 return p 51} 52 53var v4InV6Prefix = []byte{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff} 54 55// IPv4Mask returns the IP mask (in 4-byte form) of the 56// IPv4 mask a.b.c.d. 57func IPv4Mask(a, b, c, d byte) IPMask { 58 p := make(IPMask, IPv4len) 59 p[0] = a 60 p[1] = b 61 p[2] = c 62 p[3] = d 63 return p 64} 65 66// CIDRMask returns an IPMask consisting of `ones' 1 bits 67// followed by 0s up to a total length of `bits' bits. 68// For a mask of this form, CIDRMask is the inverse of IPMask.Size. 69func CIDRMask(ones, bits int) IPMask { 70 if bits != 8*IPv4len && bits != 8*IPv6len { 71 return nil 72 } 73 if ones < 0 || ones > bits { 74 return nil 75 } 76 l := bits / 8 77 m := make(IPMask, l) 78 n := uint(ones) 79 for i := 0; i < l; i++ { 80 if n >= 8 { 81 m[i] = 0xff 82 n -= 8 83 continue 84 } 85 m[i] = ^byte(0xff >> n) 86 n = 0 87 } 88 return m 89} 90 91// Well-known IPv4 addresses 92var ( 93 IPv4bcast = IPv4(255, 255, 255, 255) // broadcast 94 IPv4allsys = IPv4(224, 0, 0, 1) // all systems 95 IPv4allrouter = IPv4(224, 0, 0, 2) // all routers 96 IPv4zero = IPv4(0, 0, 0, 0) // all zeros 97) 98 99// Well-known IPv6 addresses 100var ( 101 IPv6zero = IP{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0} 102 IPv6unspecified = IP{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0} 103 IPv6loopback = IP{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1} 104 IPv6interfacelocalallnodes = IP{0xff, 0x01, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x01} 105 IPv6linklocalallnodes = IP{0xff, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x01} 106 IPv6linklocalallrouters = IP{0xff, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x02} 107) 108 109// IsUnspecified returns true if ip is an unspecified address. 110func (ip IP) IsUnspecified() bool { 111 if ip.Equal(IPv4zero) || ip.Equal(IPv6unspecified) { 112 return true 113 } 114 return false 115} 116 117// IsLoopback returns true if ip is a loopback address. 118func (ip IP) IsLoopback() bool { 119 if ip4 := ip.To4(); ip4 != nil && ip4[0] == 127 { 120 return true 121 } 122 return ip.Equal(IPv6loopback) 123} 124 125// IsMulticast returns true if ip is a multicast address. 126func (ip IP) IsMulticast() bool { 127 if ip4 := ip.To4(); ip4 != nil && ip4[0]&0xf0 == 0xe0 { 128 return true 129 } 130 return ip[0] == 0xff 131} 132 133// IsInterfaceLinkLocalMulticast returns true if ip is 134// an interface-local multicast address. 135func (ip IP) IsInterfaceLocalMulticast() bool { 136 return len(ip) == IPv6len && ip[0] == 0xff && ip[1]&0x0f == 0x01 137} 138 139// IsLinkLocalMulticast returns true if ip is a link-local 140// multicast address. 141func (ip IP) IsLinkLocalMulticast() bool { 142 if ip4 := ip.To4(); ip4 != nil && ip4[0] == 224 && ip4[1] == 0 && ip4[2] == 0 { 143 return true 144 } 145 return ip[0] == 0xff && ip[1]&0x0f == 0x02 146} 147 148// IsLinkLocalUnicast returns true if ip is a link-local 149// unicast address. 150func (ip IP) IsLinkLocalUnicast() bool { 151 if ip4 := ip.To4(); ip4 != nil && ip4[0] == 169 && ip4[1] == 254 { 152 return true 153 } 154 return ip[0] == 0xfe && ip[1]&0xc0 == 0x80 155} 156 157// IsGlobalUnicast returns true if ip is a global unicast 158// address. 159func (ip IP) IsGlobalUnicast() bool { 160 return !ip.IsUnspecified() && 161 !ip.IsLoopback() && 162 !ip.IsMulticast() && 163 !ip.IsLinkLocalUnicast() 164} 165 166// Is p all zeros? 167func isZeros(p IP) bool { 168 for i := 0; i < len(p); i++ { 169 if p[i] != 0 { 170 return false 171 } 172 } 173 return true 174} 175 176// To4 converts the IPv4 address ip to a 4-byte representation. 177// If ip is not an IPv4 address, To4 returns nil. 178func (ip IP) To4() IP { 179 if len(ip) == IPv4len { 180 return ip 181 } 182 if len(ip) == IPv6len && 183 isZeros(ip[0:10]) && 184 ip[10] == 0xff && 185 ip[11] == 0xff { 186 return ip[12:16] 187 } 188 return nil 189} 190 191// To16 converts the IP address ip to a 16-byte representation. 192// If ip is not an IP address (it is the wrong length), To16 returns nil. 193func (ip IP) To16() IP { 194 if len(ip) == IPv4len { 195 return IPv4(ip[0], ip[1], ip[2], ip[3]) 196 } 197 if len(ip) == IPv6len { 198 return ip 199 } 200 return nil 201} 202 203// Default route masks for IPv4. 204var ( 205 classAMask = IPv4Mask(0xff, 0, 0, 0) 206 classBMask = IPv4Mask(0xff, 0xff, 0, 0) 207 classCMask = IPv4Mask(0xff, 0xff, 0xff, 0) 208) 209 210// DefaultMask returns the default IP mask for the IP address ip. 211// Only IPv4 addresses have default masks; DefaultMask returns 212// nil if ip is not a valid IPv4 address. 213func (ip IP) DefaultMask() IPMask { 214 if ip = ip.To4(); ip == nil { 215 return nil 216 } 217 switch true { 218 case ip[0] < 0x80: 219 return classAMask 220 case ip[0] < 0xC0: 221 return classBMask 222 default: 223 return classCMask 224 } 225} 226 227func allFF(b []byte) bool { 228 for _, c := range b { 229 if c != 0xff { 230 return false 231 } 232 } 233 return true 234} 235 236// Mask returns the result of masking the IP address ip with mask. 237func (ip IP) Mask(mask IPMask) IP { 238 if len(mask) == IPv6len && len(ip) == IPv4len && allFF(mask[:12]) { 239 mask = mask[12:] 240 } 241 if len(mask) == IPv4len && len(ip) == IPv6len && bytesEqual(ip[:12], v4InV6Prefix) { 242 ip = ip[12:] 243 } 244 n := len(ip) 245 if n != len(mask) { 246 return nil 247 } 248 out := make(IP, n) 249 for i := 0; i < n; i++ { 250 out[i] = ip[i] & mask[i] 251 } 252 return out 253} 254 255// String returns the string form of the IP address ip. 256// If the address is an IPv4 address, the string representation 257// is dotted decimal ("74.125.19.99"). Otherwise the representation 258// is IPv6 ("2001:4860:0:2001::68"). 259func (ip IP) String() string { 260 p := ip 261 262 if len(ip) == 0 { 263 return "<nil>" 264 } 265 266 // If IPv4, use dotted notation. 267 if p4 := p.To4(); len(p4) == IPv4len { 268 return itod(uint(p4[0])) + "." + 269 itod(uint(p4[1])) + "." + 270 itod(uint(p4[2])) + "." + 271 itod(uint(p4[3])) 272 } 273 if len(p) != IPv6len { 274 return "?" 275 } 276 277 // Find longest run of zeros. 278 e0 := -1 279 e1 := -1 280 for i := 0; i < IPv6len; i += 2 { 281 j := i 282 for j < IPv6len && p[j] == 0 && p[j+1] == 0 { 283 j += 2 284 } 285 if j > i && j-i > e1-e0 { 286 e0 = i 287 e1 = j 288 } 289 } 290 // The symbol "::" MUST NOT be used to shorten just one 16 bit 0 field. 291 if e1-e0 <= 2 { 292 e0 = -1 293 e1 = -1 294 } 295 296 // Print with possible :: in place of run of zeros 297 var s string 298 for i := 0; i < IPv6len; i += 2 { 299 if i == e0 { 300 s += "::" 301 i = e1 302 if i >= IPv6len { 303 break 304 } 305 } else if i > 0 { 306 s += ":" 307 } 308 s += itox((uint(p[i])<<8)|uint(p[i+1]), 1) 309 } 310 return s 311} 312 313// Equal returns true if ip and x are the same IP address. 314// An IPv4 address and that same address in IPv6 form are 315// considered to be equal. 316func (ip IP) Equal(x IP) bool { 317 if len(ip) == len(x) { 318 return bytesEqual(ip, x) 319 } 320 if len(ip) == IPv4len && len(x) == IPv6len { 321 return bytesEqual(x[0:12], v4InV6Prefix) && bytesEqual(ip, x[12:]) 322 } 323 if len(ip) == IPv6len && len(x) == IPv4len { 324 return bytesEqual(ip[0:12], v4InV6Prefix) && bytesEqual(ip[12:], x) 325 } 326 return false 327} 328 329func bytesEqual(x, y []byte) bool { 330 if len(x) != len(y) { 331 return false 332 } 333 for i, b := range x { 334 if y[i] != b { 335 return false 336 } 337 } 338 return true 339} 340 341// If mask is a sequence of 1 bits followed by 0 bits, 342// return the number of 1 bits. 343func simpleMaskLength(mask IPMask) int { 344 var n int 345 for i, v := range mask { 346 if v == 0xff { 347 n += 8 348 continue 349 } 350 // found non-ff byte 351 // count 1 bits 352 for v&0x80 != 0 { 353 n++ 354 v <<= 1 355 } 356 // rest must be 0 bits 357 if v != 0 { 358 return -1 359 } 360 for i++; i < len(mask); i++ { 361 if mask[i] != 0 { 362 return -1 363 } 364 } 365 break 366 } 367 return n 368} 369 370// Size returns the number of leading ones and total bits in the mask. 371// If the mask is not in the canonical form--ones followed by zeros--then 372// Size returns 0, 0. 373func (m IPMask) Size() (ones, bits int) { 374 ones, bits = simpleMaskLength(m), len(m)*8 375 if ones == -1 { 376 return 0, 0 377 } 378 return 379} 380 381// String returns the hexadecimal form of m, with no punctuation. 382func (m IPMask) String() string { 383 s := "" 384 for _, b := range m { 385 s += itox(uint(b), 2) 386 } 387 if len(s) == 0 { 388 return "<nil>" 389 } 390 return s 391} 392 393func networkNumberAndMask(n *IPNet) (ip IP, m IPMask) { 394 if ip = n.IP.To4(); ip == nil { 395 ip = n.IP 396 if len(ip) != IPv6len { 397 return nil, nil 398 } 399 } 400 m = n.Mask 401 switch len(m) { 402 case IPv4len: 403 if len(ip) != IPv4len { 404 return nil, nil 405 } 406 case IPv6len: 407 if len(ip) == IPv4len { 408 m = m[12:] 409 } 410 default: 411 return nil, nil 412 } 413 return 414} 415 416// Contains reports whether the network includes ip. 417func (n *IPNet) Contains(ip IP) bool { 418 nn, m := networkNumberAndMask(n) 419 if x := ip.To4(); x != nil { 420 ip = x 421 } 422 l := len(ip) 423 if l != len(nn) { 424 return false 425 } 426 for i := 0; i < l; i++ { 427 if nn[i]&m[i] != ip[i]&m[i] { 428 return false 429 } 430 } 431 return true 432} 433 434// Network returns the address's network name, "ip+net". 435func (n *IPNet) Network() string { return "ip+net" } 436 437// String returns the CIDR notation of n like "192.168.100.1/24" 438// or "2001:DB8::/48" as defined in RFC 4632 and RFC 4291. 439// If the mask is not in the canonical form, it returns the 440// string which consists of an IP address, followed by a slash 441// character and a mask expressed as hexadecimal form with no 442// punctuation like "192.168.100.1/c000ff00". 443func (n *IPNet) String() string { 444 nn, m := networkNumberAndMask(n) 445 if nn == nil || m == nil { 446 return "<nil>" 447 } 448 l := simpleMaskLength(m) 449 if l == -1 { 450 return nn.String() + "/" + m.String() 451 } 452 return nn.String() + "/" + itod(uint(l)) 453} 454 455// Parse IPv4 address (d.d.d.d). 456func parseIPv4(s string) IP { 457 var p [IPv4len]byte 458 i := 0 459 for j := 0; j < IPv4len; j++ { 460 if i >= len(s) { 461 // Missing octets. 462 return nil 463 } 464 if j > 0 { 465 if s[i] != '.' { 466 return nil 467 } 468 i++ 469 } 470 var ( 471 n int 472 ok bool 473 ) 474 n, i, ok = dtoi(s, i) 475 if !ok || n > 0xFF { 476 return nil 477 } 478 p[j] = byte(n) 479 } 480 if i != len(s) { 481 return nil 482 } 483 return IPv4(p[0], p[1], p[2], p[3]) 484} 485 486// parseIPv6 parses s as a literal IPv6 address described in RFC 4291 487// and RFC 5952. It can also parse a literal scoped IPv6 address with 488// zone identifier which is described in RFC 4007 when zoneAllowed is 489// true. 490func parseIPv6(s string, zoneAllowed bool) (ip IP, zone string) { 491 ip = make(IP, IPv6len) 492 ellipsis := -1 // position of ellipsis in p 493 i := 0 // index in string s 494 495 if zoneAllowed { 496 s, zone = splitHostZone(s) 497 } 498 499 // Might have leading ellipsis 500 if len(s) >= 2 && s[0] == ':' && s[1] == ':' { 501 ellipsis = 0 502 i = 2 503 // Might be only ellipsis 504 if i == len(s) { 505 return ip, zone 506 } 507 } 508 509 // Loop, parsing hex numbers followed by colon. 510 j := 0 511 for j < IPv6len { 512 // Hex number. 513 n, i1, ok := xtoi(s, i) 514 if !ok || n > 0xFFFF { 515 return nil, zone 516 } 517 518 // If followed by dot, might be in trailing IPv4. 519 if i1 < len(s) && s[i1] == '.' { 520 if ellipsis < 0 && j != IPv6len-IPv4len { 521 // Not the right place. 522 return nil, zone 523 } 524 if j+IPv4len > IPv6len { 525 // Not enough room. 526 return nil, zone 527 } 528 ip4 := parseIPv4(s[i:]) 529 if ip4 == nil { 530 return nil, zone 531 } 532 ip[j] = ip4[12] 533 ip[j+1] = ip4[13] 534 ip[j+2] = ip4[14] 535 ip[j+3] = ip4[15] 536 i = len(s) 537 j += IPv4len 538 break 539 } 540 541 // Save this 16-bit chunk. 542 ip[j] = byte(n >> 8) 543 ip[j+1] = byte(n) 544 j += 2 545 546 // Stop at end of string. 547 i = i1 548 if i == len(s) { 549 break 550 } 551 552 // Otherwise must be followed by colon and more. 553 if s[i] != ':' || i+1 == len(s) { 554 return nil, zone 555 } 556 i++ 557 558 // Look for ellipsis. 559 if s[i] == ':' { 560 if ellipsis >= 0 { // already have one 561 return nil, zone 562 } 563 ellipsis = j 564 if i++; i == len(s) { // can be at end 565 break 566 } 567 } 568 } 569 570 // Must have used entire string. 571 if i != len(s) { 572 return nil, zone 573 } 574 575 // If didn't parse enough, expand ellipsis. 576 if j < IPv6len { 577 if ellipsis < 0 { 578 return nil, zone 579 } 580 n := IPv6len - j 581 for k := j - 1; k >= ellipsis; k-- { 582 ip[k+n] = ip[k] 583 } 584 for k := ellipsis + n - 1; k >= ellipsis; k-- { 585 ip[k] = 0 586 } 587 } 588 return ip, zone 589} 590 591// A ParseError represents a malformed text string and the type of string that was expected. 592type ParseError struct { 593 Type string 594 Text string 595} 596 597func (e *ParseError) Error() string { 598 return "invalid " + e.Type + ": " + e.Text 599} 600 601// ParseIP parses s as an IP address, returning the result. 602// The string s can be in dotted decimal ("74.125.19.99") 603// or IPv6 ("2001:4860:0:2001::68") form. 604// If s is not a valid textual representation of an IP address, 605// ParseIP returns nil. 606func ParseIP(s string) IP { 607 if ip := parseIPv4(s); ip != nil { 608 return ip 609 } 610 ip, _ := parseIPv6(s, false) 611 return ip 612} 613 614// ParseCIDR parses s as a CIDR notation IP address and mask, 615// like "192.168.100.1/24" or "2001:DB8::/48", as defined in 616// RFC 4632 and RFC 4291. 617// 618// It returns the IP address and the network implied by the IP 619// and mask. For example, ParseCIDR("192.168.100.1/16") returns 620// the IP address 192.168.100.1 and the network 192.168.0.0/16. 621func ParseCIDR(s string) (IP, *IPNet, error) { 622 i := byteIndex(s, '/') 623 if i < 0 { 624 return nil, nil, &ParseError{"CIDR address", s} 625 } 626 addr, mask := s[:i], s[i+1:] 627 iplen := IPv4len 628 ip := parseIPv4(addr) 629 if ip == nil { 630 iplen = IPv6len 631 ip, _ = parseIPv6(addr, false) 632 } 633 n, i, ok := dtoi(mask, 0) 634 if ip == nil || !ok || i != len(mask) || n < 0 || n > 8*iplen { 635 return nil, nil, &ParseError{"CIDR address", s} 636 } 637 m := CIDRMask(n, 8*iplen) 638 return ip, &IPNet{IP: ip.Mask(m), Mask: m}, nil 639} 640