From 54771322989e56cb126751ba5c3b67712e5a0cf3 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 21 Jan 2021 16:28:28 +1100 Subject: [PATCH] Have std/png verify PLTE chunk checksums --- release/c/wuffs-unsupported-snapshot.c | 8 +- script/strip-png-ancillary-chunks.go | 226 +++++++++++++++++++++++++ std/png/decode_png.wuffs | 22 ++- test/c/std/png.c | 46 +++-- test/data/bricks-gray.no-ancillary.png | Bin 0 -> 12996 bytes 5 files changed, 279 insertions(+), 23 deletions(-) create mode 100644 script/strip-png-ancillary-chunks.go create mode 100644 test/data/bricks-gray.no-ancillary.png diff --git a/release/c/wuffs-unsupported-snapshot.c b/release/c/wuffs-unsupported-snapshot.c index 3b70d58f..05ad44f9 100644 --- a/release/c/wuffs-unsupported-snapshot.c +++ b/release/c/wuffs-unsupported-snapshot.c @@ -31632,7 +31632,7 @@ wuffs_png__decoder__decode_image_config( } self->private_impl.f_chunk_type = t_5; } - if ( ! self->private_impl.f_ignore_checksum) { + if ( ! self->private_impl.f_ignore_checksum && ((self->private_impl.f_chunk_type == 1413563465) || (self->private_impl.f_chunk_type == 1163152464))) { wuffs_base__ignore_status(wuffs_crc32__ieee_hasher__initialize(&self->private_data.f_crc32, sizeof (wuffs_crc32__ieee_hasher), WUFFS_VERSION, 0)); self->private_impl.f_chunk_type_array[0] = ((uint8_t)(((self->private_impl.f_chunk_type >> 0) & 255))); self->private_impl.f_chunk_type_array[1] = ((uint8_t)(((self->private_impl.f_chunk_type >> 8) & 255))); @@ -31655,7 +31655,7 @@ wuffs_png__decoder__decode_image_config( iop_a_src = a_src->data.ptr + a_src->meta.ri; } } - if ( ! self->private_impl.f_ignore_checksum) { + if ( ! self->private_impl.f_ignore_checksum && (self->private_impl.f_chunk_type == 1163152464)) { v_checksum_have = wuffs_crc32__ieee_hasher__update_u32(&self->private_data.f_crc32, wuffs_base__io__since(v_mark, ((uint64_t)(iop_a_src - io0_a_src)), io0_a_src)); } if (wuffs_base__status__is_ok(&v_status)) { @@ -31694,7 +31694,9 @@ wuffs_png__decoder__decode_image_config( } v_checksum_want = t_7; } - if ( ! self->private_impl.f_ignore_checksum && (v_checksum_have != v_checksum_want)) { + if ( ! self->private_impl.f_ignore_checksum && (self->private_impl.f_chunk_type == 1163152464) && (v_checksum_have != v_checksum_want)) { + status = wuffs_base__make_status(wuffs_png__error__bad_checksum); + goto exit; } } label__1__break:; diff --git a/script/strip-png-ancillary-chunks.go b/script/strip-png-ancillary-chunks.go new file mode 100644 index 00000000..2ddb53e3 --- /dev/null +++ b/script/strip-png-ancillary-chunks.go @@ -0,0 +1,226 @@ +// Copyright 2021 The Wuffs Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// +build ignore + +package main + +// strip-png-ancillary-chunks.go copies PNG data from stdin to stdout, removing +// any ancillary chunks. +// +// Specification-compliant PNG decoders are required to honor critical chunks +// but may ignore ancillary (non-critical) chunks. Stripping out ancillary +// chunks before decoding should mean that different PNG decoders will agree on +// the decoded output regardless of which ancillary chunk types they choose to +// honor. Specifically, some PNG decoders may implement color and gamma +// correction but not all do. +// +// This program will strip out all ancillary chunks, but it should be +// straightforward to copy-paste-and-modify it to strip out only certain chunk +// types (e.g. only "tRNS" transparency chunks). +// +// -------- +// +// A PNG file consists of an 8-byte magic identifier and then a series of +// chunks. Each chunk is: +// +// - a 4-byte uint32 payload length N. +// - a 4-byte chunk type (e.g. "gAMA" for gamma correction metadata). +// - an N-byte payload. +// - a 4-byte CRC-32 checksum of the previous (N + 4) bytes, including the +// chunk type but excluding the payload length. +// +// Chunk types consist of 4 ASCII letters. The upper-case / lower-case bit of +// the first letter denote critical or ancillary chunks: "IDAT" and "PLTE" are +// critical, "gAMA" and "tEXt" are ancillary. See +// https://www.w3.org/TR/2003/REC-PNG-20031110/#5Chunk-naming-conventions +// +// -------- +// +// Usage: +// go run strip-png-ancillary-chunks.go < in.png > out.png +// +// Adding a -random=123 flag should not change the output: +// go run strip-png-ancillary-chunks.go -random=123 < in.png > out.png + +import ( + "encoding/binary" + "flag" + "io" + "math/rand" + "os" + "os/signal" + "syscall" +) + +var ( + randomFlag = flag.Int64("random", 0, "If non-zero, the seed for generating smaller reads") +) + +// chunkTypeAncillaryBit is whether the first byte of a big-endian uint32 chunk +// type (the first of four ASCII letters) is lower-case. +const chunkTypeAncillaryBit = 0x20000000 + +// RandomSizedReader wraps another io.Reader such that the Reader.Read []byte +// argument has randomized lengths, up to a maximum of 9 bytes. +// +// This is slower but helps manually test that PNGAncillaryChunkStripper +// produces identical output regardless of whether Read is called many times +// (with small buffers) or few times (with large buffers). Specifically, this +// exercises having Read boundaries straddle chunk boundaries. +type RandomSizedReader struct { + // Reader is the wrapped io.Reader. + Reader io.Reader + + // Rand is the random number generator. + Rand *rand.Rand +} + +// Read implements io.Reader. +func (r *RandomSizedReader) Read(p []byte) (int, error) { + if n := r.Rand.Intn(10); len(p) > n { + p = p[:n] + } + return r.Reader.Read(p) +} + +// PNGAncillaryChunkStripper wraps another io.Reader to strip ancillary chunks, +// if the data is in the PNG file format. If the data isn't PNG, it is passed +// through unmodified. +type PNGAncillaryChunkStripper struct { + // Reader is the wrapped io.Reader. + Reader io.Reader + + // stickyErr is the first error returned from the wrapped io.Reader. + stickyErr error + + // buffer[rIndex:wIndex] holds data read from the wrapped io.Reader that + // wasn't passed through yet. + buffer [8]byte + rIndex int + wIndex int + + // pending and discard is the number of remaining bytes for (and whether to + // discard or pass through) the current chunk-in-progress. + pending int64 + discard bool + + // notPNG is set true if the data stream doesn't start with the 8-byte PNG + // magic identifier. If true, the wrapped io.Reader's data (including the + // first up-to-8 bytes) is passed through without modification. + notPNG bool + + // seenMagic is whether we've seen the 8-byte PNG magic identifier. + seenMagic bool +} + +// Read implements io.Reader. +func (r *PNGAncillaryChunkStripper) Read(p []byte) (int, error) { + for { + // If the wrapped io.Reader returned a non-nil error, drain r.buffer + // (what data we have) and return that error (if fully drained). + if r.stickyErr != nil { + n := copy(p, r.buffer[r.rIndex:r.wIndex]) + r.rIndex += n + if r.rIndex < r.wIndex { + return n, nil + } + return n, r.stickyErr + } + + // Handle trivial requests, including draining our buffer. + if len(p) == 0 { + return 0, nil + } else if r.rIndex < r.wIndex { + n := copy(p, r.buffer[r.rIndex:r.wIndex]) + r.rIndex += n + return n, nil + } + + // From here onwards, our buffer is drained: r.rIndex == r.wIndex. + + // Handle non-PNG input. + if r.notPNG { + return r.Reader.Read(p) + } + + // Continue processing any PNG chunk that's in progress, whether + // discarding it or passing it through. + for r.pending > 0 { + if int64(len(p)) > r.pending { + p = p[:r.pending] + } + n, err := r.Reader.Read(p) + r.pending -= int64(n) + r.stickyErr = err + if r.discard { + continue + } + return n, err + } + + // We're either expecting the 8-byte PNG magic identifier or the 4-byte + // PNG chunk length + 4-byte PNG chunk type. Either way, read 8 bytes. + r.rIndex = 0 + r.wIndex, r.stickyErr = io.ReadFull(r.Reader, r.buffer[:8]) + if r.stickyErr != nil { + // Undo io.ReadFull converting io.EOF to io.ErrUnexpectedEOF. + if r.stickyErr == io.ErrUnexpectedEOF { + r.stickyErr = io.EOF + } + continue + } + + // Process those 8 bytes, either: + // - a PNG chunk (if we've already seen the PNG magic identifier), + // - the PNG magic identifier itself (if the input is a PNG) or + // - something else (if it's not a PNG). + if r.seenMagic { + // The number of pending bytes is equal to (N + 4) because of the 4 + // byte trailer, a checksum. + r.pending = int64(binary.BigEndian.Uint32(r.buffer[:4])) + 4 + chunkType := binary.BigEndian.Uint32(r.buffer[4:]) + r.discard = (chunkType & chunkTypeAncillaryBit) != 0 + if r.discard { + r.rIndex = r.wIndex + } + } else if string(r.buffer[:8]) == "\x89PNG\x0D\x0A\x1A\x0A" { + r.seenMagic = true + } else { + r.notPNG = true + } + } +} + +func main() { + // Piping to /usr/bin/head can cause SIGPIPE (in the upstream process) + // since head can exit early, leaving this process with pending output. The + // command line experience can be cleaner if this program ignores SIGPIPE. + signal.Ignore(syscall.SIGPIPE) + + flag.Parse() + + r := io.Reader(&PNGAncillaryChunkStripper{ + Reader: os.Stdin, + }) + + if *randomFlag != 0 { + r = &RandomSizedReader{ + Reader: r, + Rand: rand.New(rand.NewSource(*randomFlag)), + } + } + + io.Copy(os.Stdout, r) +} diff --git a/std/png/decode_png.wuffs b/std/png/decode_png.wuffs index 2d9cb49e..3d1c488f 100644 --- a/std/png/decode_png.wuffs +++ b/std/png/decode_png.wuffs @@ -142,10 +142,22 @@ pub func decoder.decode_image_config?(dst: nptr base.image_config, src: base.io_ } // Read up until an IDAT chunk. + // + // By default, libpng "warns and discards" when seeing ancillary chunk + // checksum failures (as opposed to critical chunk checksum failures) but + // it still continues to decode the image. Wuffs' decoder is similar, + // simply always ignoring ancillary chunks' CRC-32 checksums. + // + // https://github.com/glennrp/libpng/blob/dbe3e0c43e549a1602286144d94b0666549b18e6/png.h#L1436 + // + // We've already seen the IHDR chunk. We're not expecting an IEND chunk. An + // IDAT chunk breaks the loop. The only other possible critical chunk is a + // PLTE chunk. We verify PLTE checksums here but ignore other checksums. while true { this.chunk_length = args.src.read_u32be_as_u64?() this.chunk_type = args.src.read_u32le?() - if not this.ignore_checksum { + if (not this.ignore_checksum) and + ((this.chunk_type == 'IDAT'le) or (this.chunk_type == 'PLTE'le)) { this.crc32.reset!() this.chunk_type_array[0] = ((this.chunk_type >> 0) & 0xFF) as base.u8 this.chunk_type_array[1] = ((this.chunk_type >> 8) & 0xFF) as base.u8 @@ -161,7 +173,7 @@ pub func decoder.decode_image_config?(dst: nptr base.image_config, src: base.io_ while true { mark = args.src.mark() status =? this.decode_other_chunk?(src: args.src) - if not this.ignore_checksum { + if (not this.ignore_checksum) and (this.chunk_type == 'PLTE'le) { checksum_have = this.crc32.update_u32!(x: args.src.since(mark: mark)) } if status.is_ok() { @@ -170,9 +182,9 @@ pub func decoder.decode_image_config?(dst: nptr base.image_config, src: base.io_ yield? status } endwhile checksum_want = args.src.read_u32be?() - if (not this.ignore_checksum) and (checksum_have <> checksum_want) { - // TODO: uncomment and fix test_mimic_png_decode_19k_8bpp. - // return "#bad checksum" + if (not this.ignore_checksum) and (this.chunk_type == 'PLTE'le) and + (checksum_have <> checksum_want) { + return "#bad checksum" } } endwhile diff --git a/test/c/std/png.c b/test/c/std/png.c index 54bdbd8d..863a84b8 100644 --- a/test/c/std/png.c +++ b/test/c/std/png.c @@ -89,7 +89,7 @@ wuffs_png_decode(uint64_t* n_bytes_out, } const char* // -do_test_xxxxx_png_decode_bad_crc32_checksum( +do_test_xxxxx_png_decode_bad_crc32_checksum_critical( const char* (*decode_func)(uint64_t* n_bytes_out, wuffs_base__io_buffer* dst, uint32_t wuffs_initialize_flags, @@ -98,13 +98,14 @@ do_test_xxxxx_png_decode_bad_crc32_checksum( const char* test_cases[] = { // Change a byte in the IHDR CRC-32 checksum. "@001F=8A=00;test/data/hippopotamus.regular.png", + // Change a byte in a PLTE CRC-32 checksum. + "@0372=52=00;test/data/bricks-dither.png", // Change a byte in a final IDAT Adler-32 checksum. "@084E=26=00;test/data/hippopotamus.regular.png", // Change a byte in a final IDAT CRC-32 checksum. "@084F=F4=00;test/data/hippopotamus.regular.png", // Change a byte in a non-final IDAT CRC-32 checksum. "@2029=B7=00;test/data/bricks-color.png", - // TODO: Change a byte in an ancillary chunk's CRC-32 checksum. }; int tc; @@ -181,9 +182,10 @@ test_wuffs_png_decode_interface() { } const char* // -test_wuffs_png_decode_bad_crc32_checksum() { +test_wuffs_png_decode_bad_crc32_checksum_critical() { CHECK_FOCUS(__func__); - return do_test_xxxxx_png_decode_bad_crc32_checksum(&wuffs_png_decode); + return do_test_xxxxx_png_decode_bad_crc32_checksum_critical( + &wuffs_png_decode); } const char* // @@ -495,11 +497,7 @@ do_test_mimic_png_decode(const char* filename) { const char* // test_mimic_png_decode_19k_8bpp() { CHECK_FOCUS(__func__); - // libpng automatically applies the "gAMA" chunk (with no matching "sRGB" - // chunk) but Wuffs does not. To make the comparison more like-for-like, - // especially in emitting identical BGRA pixels, patch the source file by - // replacing the "gAMA" with the nonsense "hAMA". ASCII 'g' is 0x67. - return do_test_mimic_png_decode("@25=67=68;test/data/bricks-gray.png"); + return do_test_mimic_png_decode("test/data/bricks-gray.no-ancillary.png"); } const char* // @@ -527,9 +525,26 @@ test_mimic_png_decode_4002k_24bpp() { } const char* // -test_mimic_png_decode_bad_crc32_checksum() { +test_mimic_png_decode_bad_crc32_checksum_ancillary() { CHECK_FOCUS(__func__); - return do_test_xxxxx_png_decode_bad_crc32_checksum(&mimic_png_decode); + // libpng automatically applies the "gAMA" chunk (with no matching "sRGB" + // chunk) but Wuffs does not. To make the comparison more like-for-like, + // especially in emitting identical BGRA pixels, patch the source file by + // replacing the "gAMA" with the nonsense "hAMA". ASCII 'g' is 0x67. + // + // This makes the "hAMA" CRC-32 checksum no longer verify, since the checksum + // input includes the chunk type. By default, libpng "warns and discards" + // when seeing ancillary chunk checksum failures (as opposed to critical + // chunk checksum failures) but it still continues to decode the image. + // Wuffs' decoder likewise ignores the bad ancillary chunk checksum. + return do_test_mimic_png_decode("@25=67=68;test/data/bricks-gray.png"); +} + +const char* // +test_mimic_png_decode_bad_crc32_checksum_critical() { + CHECK_FOCUS(__func__); + return do_test_xxxxx_png_decode_bad_crc32_checksum_critical( + &mimic_png_decode); } #endif // WUFFS_MIMIC @@ -546,7 +561,7 @@ bench_wuffs_png_decode_19k_8bpp() { return do_bench_image_decode( &wuffs_png_decode, WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED, wuffs_base__make_pixel_format(WUFFS_BASE__PIXEL_FORMAT__Y), - "@25=67=68;test/data/bricks-gray.png", 0, SIZE_MAX, 50); + "test/data/bricks-gray.no-ancillary.png", 0, SIZE_MAX, 50); } const char* // @@ -716,7 +731,7 @@ bench_mimic_png_decode_19k_8bpp() { return do_bench_image_decode( &mimic_png_decode, WUFFS_INITIALIZE__LEAVE_INTERNAL_BUFFERS_UNINITIALIZED, wuffs_base__make_pixel_format(WUFFS_BASE__PIXEL_FORMAT__Y), - "@25=67=68;test/data/bricks-gray.png", 0, SIZE_MAX, 50); + "test/data/bricks-gray.no-ancillary.png", 0, SIZE_MAX, 50); } const char* // @@ -761,7 +776,7 @@ bench_mimic_png_decode_4002k_24bpp() { proc g_tests[] = { - test_wuffs_png_decode_bad_crc32_checksum, + test_wuffs_png_decode_bad_crc32_checksum_critical, test_wuffs_png_decode_filters_golden, test_wuffs_png_decode_filters_round_trip, test_wuffs_png_decode_frame_config, @@ -774,7 +789,8 @@ proc g_tests[] = { test_mimic_png_decode_77k_8bpp, test_mimic_png_decode_552k_32bpp, test_mimic_png_decode_4002k_24bpp, - test_mimic_png_decode_bad_crc32_checksum, + test_mimic_png_decode_bad_crc32_checksum_ancillary, + test_mimic_png_decode_bad_crc32_checksum_critical, #endif // WUFFS_MIMIC diff --git a/test/data/bricks-gray.no-ancillary.png b/test/data/bricks-gray.no-ancillary.png new file mode 100644 index 0000000000000000000000000000000000000000..59de34b65750d705759d0f5ada61f37f5bcd9e83 GIT binary patch literal 12996 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 literal 0 HcmV?d00001