image: add a security considerations section to package doc

Internally the security model for the image package has always been,
if you don't call DecodeConfig before Decode, you cannot complain if
Decode attempts to create an arbitrarily large image (with the
assumption that DecodeConfig would've told you this information). This
should be explicitly documented.

Change-Id: I5c37b91131d6352637e725fe415f37a28f12f66d
Reviewed-on: https://go-review.googlesource.com/c/go/+/523578
Reviewed-by: Damien Neil <dneil@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/image/image.go b/src/image/image.go
index dfb70d4eaf62759f794e94344bd017ad5038b84d..4488a881e1cf5b03e17ee588a987e008682df3fc 100644 (file)
--- a/src/image/image.go
+++ b/src/image/image.go
@@ -21,6 +21,20 @@
 //
 // See "The Go image package" for more details:
 // https://golang.org/doc/articles/image_package.html
+//
+// # Security Considerations
+//
+// The image package can be used to parse arbitrarily large images, which can
+// cause resource exhaustion on machines which do not have enough memory to
+// store them. When operating on arbitrary images, DecodeConfig should be called
+// before Decode, so that the program can decide whether the image, as defined
+// in the returned header, can be safely decoded with the available resources. A
+// call to Decode which produces an extremely large image, as defined in the
+// header returned by DecodeConfig, is not considered a security issue,
+// regardless of whether the image is itself malformed or not. A call to
+// DecodeConfig which returns a header which does not match the image returned
+// by Decode may be considered a security issue, and should be reported per the
+// [Go Security Policy](https://go.dev/security/policy).
 package image
 
 import (