terraform/internal/ipaddr/README.md

# Forked IP address parsing functions

This directory contains a subset of code from the Go project's `net` package
as of Go 1.16, used under the Go project license which we've included here
in [`LICENSE`](LICENSE) and [`PATENTS`](PATENTS), which are also copied from
the Go project.

Terraform has its own fork of these functions because Go 1.17 included a
breaking change to reject IPv4 address octets written with leading zeros.

The Go project rationale for that change was that Go historically interpreted
leading-zero octets inconsistently with many other implementations, trimming
off the zeros and still treating the rest as decimal rather than treating the
octet as octal.

The Go team made the reasonable observation that having a function that
interprets a non-normalized form in a manner inconsistent with other
implementations may cause naive validation or policy checks to produce
incorrect results, and thus it's a potential security concern. For more
information, see [Go issue #30999](https://golang.org/issue/30999).

After careful consideration, the Terraform team has concluded that Terraform's
use of these functions as part of the implementation of the `cidrhost`,
`cidrsubnet`, `cidrsubnets`, and `cidrnetmask` functions has a more limited
impact than the general availability of these functions in the Go standard
library, and so we can't justify a similar exception to our Terraform 1.0
compatibility promises as the Go team made to their Go 1.0 compatibility
promises.

If you're considering using this package for new functionality _other than_ the
built-in functions mentioned above, please do so only if consistency with the
behavior of those functions is important. Otherwise, new features are not
burdened by the same compatibility constraints and so should typically prefer
to use the stricter interpretation of the upstream parsing functions.
lang/funcs: Preserve IP address leading zero behavior from Go 1.16 Go 1.17 includes a breaking change to both net.ParseIP and net.ParseCIDR functions to reject IPv4 address octets written with leading zeros. Our use of these functions as part of the various CIDR functions in the Terraform language doesn't have the same security concerns that the Go team had in evaluating this change to the standard library, and so we can't justify an exception to our v1.0 compatibility promises on the same sort of security grounds that the Go team used to justify their compatibility exception. For that reason, we'll now use our own fork of the Go library functions which has the new check disabled in order to preserve the prior behavior. We're taking this path, rather than pre-normalizing the IP address before calling into the standard library, because an additional normalization layer would be entirely new code and additional complexity, whereas this fork is relatively minor in terms of code size and avoids any significant changes to our own calls to these functions. Thanks to the Kubernetes team for their prior work on carving out a subset of the "net" package for their similar backward-compatibility concern. Our "ipaddr" package here is a lightly-modified fork of their fork, with only the comments changed to talk about Terraform instead of Kubernetes. This fork is not intended for use in any other future feature implementations, because they wouldn't be subject to the same compatibility constraints as our existing functions. We will use these forked implementations for new callers only if consistency with the behavior of the existing functions is a key requirement. 2021-08-17 20:30:18 +02:00			`# Forked IP address parsing functions`

			This directory contains a subset of code from the Go project's `net` package
			`as of Go 1.16, used under the Go project license which we've included here`
			in [`LICENSE`](LICENSE) and [`PATENTS`](PATENTS), which are also copied from
			`the Go project.`

			`Terraform has its own fork of these functions because Go 1.17 included a`
			`breaking change to reject IPv4 address octets written with leading zeros.`

			`The Go project rationale for that change was that Go historically interpreted`
			`leading-zero octets inconsistently with many other implementations, trimming`
			`off the zeros and still treating the rest as decimal rather than treating the`
			`octet as octal.`

			`The Go team made the reasonable observation that having a function that`
			`interprets a non-normalized form in a manner inconsistent with other`
			`implementations may cause naive validation or policy checks to produce`
			`incorrect results, and thus it's a potential security concern. For more`
			`information, see [Go issue #30999](https://golang.org/issue/30999).`

			`After careful consideration, the Terraform team has concluded that Terraform's`
			use of these functions as part of the implementation of the `cidrhost`,
			`cidrsubnet`, `cidrsubnets`, and `cidrnetmask` functions has a more limited
			`impact than the general availability of these functions in the Go standard`
			`library, and so we can't justify a similar exception to our Terraform 1.0`
			`compatibility promises as the Go team made to their Go 1.0 compatibility`
			`promises.`

			`If you're considering using this package for new functionality _other than_ the`
			`built-in functions mentioned above, please do so only if consistency with the`
			`behavior of those functions is important. Otherwise, new features are not`
			`burdened by the same compatibility constraints and so should typically prefer`
			`to use the stricter interpretation of the upstream parsing functions.`