From 84e999c14e43b3d0c8cb1acbf65bf942ce11ca6c Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 15 Jun 2017 10:39:01 +1000 Subject: [PATCH] Add some more examples to README.md. --- README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 105 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 31a73c52..84c656b5 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Parsing Untrusted File Formats Safely + Puffs is a domain-specific language and library for parsing untrusted file formats safely. Examples of such file formats include images, audio, video, fonts and compressed archives. @@ -5,12 +7,14 @@ fonts and compressed archives. Unlike the C programming language, Puffs is safe with respect to buffer overflows, integer arithmetic overflows and null pointer dereferences. The key difference between Puffs and other memory-safe languages is that all such -checks are done at compile time, not at run time. The aim is to produce -software libraries that are as safe as Go or Rust, roughly speaking, but as -fast as C, and that can be used anywhere C libraries are used. This includes -very large C/C++ products, such as popular web browsers and operating systems -(using that term to include desktop and mobile user interfaces, not just the -kernel). +checks are done at compile time, not at run time. *If it compiles, it is safe*, +with respect to those three bug classes. + +The aim is to produce software libraries that are as safe as Go or Rust, +roughly speaking, but as fast as C, and that can be used anywhere C libraries +are used. This includes very large C/C++ products, such as popular web browsers +and operating systems (using that term to include desktop and mobile user +interfaces, not just the kernel). The trade-off in aiming for both safety and speed is that Puffs programs take longer for a programmer to write, as they have to explicitly annotate their @@ -26,10 +30,102 @@ Puffs is not a general purpose programming language. While technically possible, it is unlikely that a Puffs compiler would be worth writing in Puffs. -# What Does It Look Like? +## What Does Puffs Code Look Like? -The `std/gif/decode_lzw.puffs` file is a good example. See the "Your First -Edit" section below for more guidance. +The [`std/gif/decode_lzw.puffs`](./std/gif/decode_lzw.puffs) file is a good +example. See the "Your First Edit" section below for more guidance. + + +## What Does Compile Time Checking Look Like? + +For example, making this one-line edit to the GIF codec leads to a compile time +error. `puffs gen` fails to generate the C code, i.e. fails to compile +(transpile) the Puffs code to C code: + +--- + + $ git diff + diff --git a/std/gif/decode_lzw.puffs b/std/gif/decode_lzw.puffs + index f878c5e..f10dcee 100644 + --- a/std/gif/decode_lzw.puffs + +++ b/std/gif/decode_lzw.puffs + @@ -98,7 +98,7 @@ pub func lzw_decoder.decode?(dst ptr buf1, src ptr buf1, src_final bool)() { + in.dst.write?(x:s) + + if use_save_code { + - this.suffixes[save_code] = c as u8 + + this.suffixes[save_code] = (c + 1) as u8 + this.prefixes[save_code] = prev_code as u16 + } + + $ puffs gen std/gif + check: expression "(c + 1) as u8" bounds [1..256] is not within bounds [0..255] at + /home/n/go/src/github.com/google/puffs/std/gif/decode_lzw.puffs:101. Facts: + n_bits < 8 + c < 256 + this.stack[s] == (c as u8) + use_save_code + +--- + +In comparison, this two-line edit will compile (but the "does it decode GIF +correctly" tests then fail): + +--- + + $ git diff + diff --git a/std/gif/decode_lzw.puffs b/std/gif/decode_lzw.puffs + index f878c5e..b43443d 100644 + --- a/std/gif/decode_lzw.puffs + +++ b/std/gif/decode_lzw.puffs + @@ -97,8 +97,8 @@ pub func lzw_decoder.decode?(dst ptr buf1, src ptr buf1, src_final bool)() { + // type checking, bounds checking and code generation for it). + in.dst.write?(x:s) + + - if use_save_code { + - this.suffixes[save_code] = c as u8 + + if use_save_code and (c < 200) { + + this.suffixes[save_code] = (c + 1) as u8 + this.prefixes[save_code] = prev_code as u16 + } + + $ puffs gen std/gif + gen wrote: /home/n/go/src/github.com/google/puffs/gen/c/gif.c + gen unchanged: /home/n/go/src/github.com/google/puffs/gen/h/gif.h + $ puffs test std/gif + gen unchanged: /home/n/go/src/github.com/google/puffs/gen/c/gif.c + gen unchanged: /home/n/go/src/github.com/google/puffs/gen/h/gif.h + test: /home/n/go/src/github.com/google/puffs/test/c/gif + gif/basic.c clang PASS (8 tests run) + gif/basic.c gcc PASS (8 tests run) + gif/gif.c clang FAIL test_lzw_decode: bufs1_equal: wi: got 19311, want 19200. + contents differ at byte 3 (in hex: 0x000003): + 000000: dcdc dc00 00d9 f5f9 f6df dc5f 393a 3a3a ..........._9::: + 000010: 3a3b 618e c8e4 e4e4 e5e4 e600 00e4 bbbb :;a............. + 000020: eded 8f91 9191 9090 9090 9190 9192 9192 ................ + 000030: 9191 9292 9191 9293 93f0 f0f0 f1f1 f2f2 ................ + excerpts of got (above) versus want (below): + 000000: dcdc dcdc dcd9 f5f9 f6df dc5f 393a 3a3a ..........._9::: + 000010: 3a3a 618e c8e4 e4e4 e5e4 e6e4 e4e4 bbbb ::a............. + 000020: eded 8f91 9191 9090 9090 9090 9191 9191 ................ + 000030: 9191 9191 9191 9193 93f0 f0f0 f1f1 f2f2 ................ + + gif/gif.c gcc FAIL test_lzw_decode: bufs1_equal: wi: got 19311, want 19200. + contents differ at byte 3 (in hex: 0x000003): + 000000: dcdc dc00 00d9 f5f9 f6df dc5f 393a 3a3a ..........._9::: + 000010: 3a3b 618e c8e4 e4e4 e5e4 e600 00e4 bbbb :;a............. + 000020: eded 8f91 9191 9090 9090 9190 9192 9192 ................ + 000030: 9191 9292 9191 9293 93f0 f0f0 f1f1 f2f2 ................ + excerpts of got (above) versus want (below): + 000000: dcdc dcdc dcd9 f5f9 f6df dc5f 393a 3a3a ..........._9::: + 000010: 3a3a 618e c8e4 e4e4 e5e4 e6e4 e4e4 bbbb ::a............. + 000020: eded 8f91 9191 9090 9090 9090 9191 9191 ................ + 000030: 9191 9191 9191 9193 93f0 f0f0 f1f1 f2f2 ................ + + puffs-test-c: some tests failed + puffs test: some tests failed + +--- # Background