vendor: add golang.org/x/crypto/cryptobyte

This change adds the cryptobyte package from x/crypto at git revision
faadfbdc035307d901e69eea569f5dda451a3ee3.

Updates #22616, #15196

Change-Id: Iffd0b022ca129d340ef429697e05b581f04e5c4f
Reviewed-on: https://go-review.googlesource.com/74270Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/vendor/golang_org/x/crypto/cryptobyte/asn1/asn1.go

+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package asn1 contains supporting types for parsing and building ASN.1
+// messages with the cryptobyte package.
+package asn1 // import "golang.org/x/crypto/cryptobyte/asn1"
+
+// Tag represents an ASN.1 identifier octet, consisting of a tag number
+// (indicating a type) and class (such as context-specific or constructed).
+//
+// Methods in the cryptobyte package only support the low-tag-number form, i.e.
+// a single identifier octet with bits 7-8 encoding the class and bits 1-6
+// encoding the tag number.
+type Tag uint8
+
+const (
+	classConstructed     = 0x20
+	classContextSpecific = 0x80
+)
+
+// Constructed returns t with the constructed class bit set.
+func (t Tag) Constructed() Tag { return t | classConstructed }
+
+// ContextSpecific returns t with the context-specific class bit set.
+func (t Tag) ContextSpecific() Tag { return t | classContextSpecific }
+
+// The following is a list of standard tag and class combinations.
+const (
+	BOOLEAN           = Tag(1)
+	INTEGER           = Tag(2)
+	BIT_STRING        = Tag(3)
+	OCTET_STRING      = Tag(4)
+	NULL              = Tag(5)
+	OBJECT_IDENTIFIER = Tag(6)
+	ENUM              = Tag(10)
+	UTF8String        = Tag(12)
+	SEQUENCE          = Tag(16 | classConstructed)
+	SET               = Tag(17 | classConstructed)
+	PrintableString   = Tag(19)
+	T61String         = Tag(20)
+	IA5String         = Tag(22)
+	UTCTime           = Tag(23)
+	GeneralizedTime   = Tag(24)
+	GeneralString     = Tag(27)
+)

src/vendor/golang_org/x/crypto/cryptobyte/asn1_test.go

+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cryptobyte
+
+import (
+	"bytes"
+	encoding_asn1 "encoding/asn1"
+	"math/big"
+	"reflect"
+	"testing"
+	"time"
+
+	"golang_org/x/crypto/cryptobyte/asn1"
+)
+
+type readASN1Test struct {
+	name string
+	in   []byte
+	tag  asn1.Tag
+	ok   bool
+	out  interface{}
+}
+
+var readASN1TestData = []readASN1Test{
+	{"valid", []byte{0x30, 2, 1, 2}, 0x30, true, []byte{1, 2}},
+	{"truncated", []byte{0x30, 3, 1, 2}, 0x30, false, nil},
+	{"zero length of length", []byte{0x30, 0x80}, 0x30, false, nil},
+	{"invalid long form length", []byte{0x30, 0x81, 1, 1}, 0x30, false, nil},
+	{"non-minimal length", append([]byte{0x30, 0x82, 0, 0x80}, make([]byte, 0x80)...), 0x30, false, nil},
+	{"invalid tag", []byte{0xa1, 3, 0x4, 1, 1}, 31, false, nil},
+	{"high tag", []byte{0x1f, 0x81, 0x80, 0x01, 2, 1, 2}, 0xff /* actually 0x4001, but tag is uint8 */, false, nil},
+}
+
+func TestReadASN1(t *testing.T) {
+	for _, test := range readASN1TestData {
+		t.Run(test.name, func(t *testing.T) {
+			var in, out String = test.in, nil
+			ok := in.ReadASN1(&out, test.tag)
+			if ok != test.ok || ok && !bytes.Equal(out, test.out.([]byte)) {
+				t.Errorf("in.ReadASN1() = %v, want %v; out = %v, want %v", ok, test.ok, out, test.out)
+			}
+		})
+	}
+}
+
+func TestReadASN1Optional(t *testing.T) {
+	var empty String
+	var present bool
+	ok := empty.ReadOptionalASN1(nil, &present, 0xa0)
+	if !ok || present {
+		t.Errorf("empty.ReadOptionalASN1() = %v, want true; present = %v want false", ok, present)
+	}
+
+	var in, out String = []byte{0xa1, 3, 0x4, 1, 1}, nil
+	ok = in.ReadOptionalASN1(&out, &present, 0xa0)
+	if !ok || present {
+		t.Errorf("in.ReadOptionalASN1() = %v, want true, present = %v, want false", ok, present)
+	}
+	ok = in.ReadOptionalASN1(&out, &present, 0xa1)
+	wantBytes := []byte{4, 1, 1}
+	if !ok || !present || !bytes.Equal(out, wantBytes) {
+		t.Errorf("in.ReadOptionalASN1() = %v, want true; present = %v, want true; out = %v, want = %v", ok, present, out, wantBytes)
+	}
+}
+
+var optionalOctetStringTestData = []struct {
+	readASN1Test
+	present bool
+}{
+	{readASN1Test{"empty", []byte{}, 0xa0, true, []byte{}}, false},
+	{readASN1Test{"invalid", []byte{0xa1, 3, 0x4, 2, 1}, 0xa1, false, []byte{}}, true},
+	{readASN1Test{"missing", []byte{0xa1, 3, 0x4, 1, 1}, 0xa0, true, []byte{}}, false},
+	{readASN1Test{"present", []byte{0xa1, 3, 0x4, 1, 1}, 0xa1, true, []byte{1}}, true},
+}
+
+func TestReadASN1OptionalOctetString(t *testing.T) {
+	for _, test := range optionalOctetStringTestData {
+		t.Run(test.name, func(t *testing.T) {
+			in := String(test.in)
+			var out []byte
+			var present bool
+			ok := in.ReadOptionalASN1OctetString(&out, &present, test.tag)
+			if ok != test.ok || present != test.present || !bytes.Equal(out, test.out.([]byte)) {
+				t.Errorf("in.ReadOptionalASN1OctetString() = %v, want %v; present = %v want %v; out = %v, want %v", ok, test.ok, present, test.present, out, test.out)
+			}
+		})
+	}
+}
+
+const defaultInt = -1
+
+var optionalIntTestData = []readASN1Test{
+	{"empty", []byte{}, 0xa0, true, defaultInt},
+	{"invalid", []byte{0xa1, 3, 0x2, 2, 127}, 0xa1, false, 0},
+	{"missing", []byte{0xa1, 3, 0x2, 1, 127}, 0xa0, true, defaultInt},
+	{"present", []byte{0xa1, 3, 0x2, 1, 42}, 0xa1, true, 42},
+}
+
+func TestReadASN1OptionalInteger(t *testing.T) {
+	for _, test := range optionalIntTestData {
+		t.Run(test.name, func(t *testing.T) {
+			in := String(test.in)
+			var out int
+			ok := in.ReadOptionalASN1Integer(&out, test.tag, defaultInt)
+			if ok != test.ok || ok && out != test.out.(int) {
+				t.Errorf("in.ReadOptionalASN1Integer() = %v, want %v; out = %v, want %v", ok, test.ok, out, test.out)
+			}
+		})
+	}
+}
+
+func TestReadASN1IntegerSigned(t *testing.T) {
+	testData64 := []struct {
+		in  []byte
+		out int64
+	}{
+		{[]byte{2, 3, 128, 0, 0}, -0x800000},
+		{[]byte{2, 2, 255, 0}, -256},
+		{[]byte{2, 2, 255, 127}, -129},
+		{[]byte{2, 1, 128}, -128},
+		{[]byte{2, 1, 255}, -1},
+		{[]byte{2, 1, 0}, 0},
+		{[]byte{2, 1, 1}, 1},
+		{[]byte{2, 1, 2}, 2},
+		{[]byte{2, 1, 127}, 127},
+		{[]byte{2, 2, 0, 128}, 128},
+		{[]byte{2, 2, 1, 0}, 256},
+		{[]byte{2, 4, 0, 128, 0, 0}, 0x800000},
+	}
+	for i, test := range testData64 {
+		in := String(test.in)
+		var out int64
+		ok := in.ReadASN1Integer(&out)
+		if !ok || out != test.out {
+			t.Errorf("#%d: in.ReadASN1Integer() = %v, want true; out = %d, want %d", i, ok, out, test.out)
+		}
+	}
+
+	// Repeat the same cases, reading into a big.Int.
+	t.Run("big.Int", func(t *testing.T) {
+		for i, test := range testData64 {
+			in := String(test.in)
+			var out big.Int
+			ok := in.ReadASN1Integer(&out)
+			if !ok || out.Int64() != test.out {
+				t.Errorf("#%d: in.ReadASN1Integer() = %v, want true; out = %d, want %d", i, ok, out.Int64(), test.out)
+			}
+		}
+	})
+}
+
+func TestReadASN1IntegerUnsigned(t *testing.T) {
+	testData := []struct {
+		in  []byte
+		out uint64
+	}{
+		{[]byte{2, 1, 0}, 0},
+		{[]byte{2, 1, 1}, 1},
+		{[]byte{2, 1, 2}, 2},
+		{[]byte{2, 1, 127}, 127},
+		{[]byte{2, 2, 0, 128}, 128},
+		{[]byte{2, 2, 1, 0}, 256},
+		{[]byte{2, 4, 0, 128, 0, 0}, 0x800000},
+		{[]byte{2, 8, 127, 255, 255, 255, 255, 255, 255, 255}, 0x7fffffffffffffff},
+		{[]byte{2, 9, 0, 128, 0, 0, 0, 0, 0, 0, 0}, 0x8000000000000000},
+		{[]byte{2, 9, 0, 255, 255, 255, 255, 255, 255, 255, 255}, 0xffffffffffffffff},
+	}
+	for i, test := range testData {
+		in := String(test.in)
+		var out uint64
+		ok := in.ReadASN1Integer(&out)
+		if !ok || out != test.out {
+			t.Errorf("#%d: in.ReadASN1Integer() = %v, want true; out = %d, want %d", i, ok, out, test.out)
+		}
+	}
+}
+
+func TestReadASN1IntegerInvalid(t *testing.T) {
+	testData := []String{
+		[]byte{3, 1, 0}, // invalid tag
+		// truncated
+		[]byte{2, 1},
+		[]byte{2, 2, 0},
+		// not minimally encoded
+		[]byte{2, 2, 0, 1},
+		[]byte{2, 2, 0xff, 0xff},
+	}
+
+	for i, test := range testData {
+		var out int64
+		if test.ReadASN1Integer(&out) {
+			t.Errorf("#%d: in.ReadASN1Integer() = true, want false (out = %d)", i, out)
+		}
+	}
+}
+
+func TestASN1ObjectIdentifier(t *testing.T) {
+	testData := []struct {
+		in  []byte
+		ok  bool
+		out []int
+	}{
+		{[]byte{}, false, []int{}},
+		{[]byte{6, 0}, false, []int{}},
+		{[]byte{5, 1, 85}, false, []int{2, 5}},
+		{[]byte{6, 1, 85}, true, []int{2, 5}},
+		{[]byte{6, 2, 85, 0x02}, true, []int{2, 5, 2}},
+		{[]byte{6, 4, 85, 0x02, 0xc0, 0x00}, true, []int{2, 5, 2, 0x2000}},
+		{[]byte{6, 3, 0x81, 0x34, 0x03}, true, []int{2, 100, 3}},
+		{[]byte{6, 7, 85, 0x02, 0xc0, 0x80, 0x80, 0x80, 0x80}, false, []int{}},
+	}
+
+	for i, test := range testData {
+		in := String(test.in)
+		var out encoding_asn1.ObjectIdentifier
+		ok := in.ReadASN1ObjectIdentifier(&out)
+		if ok != test.ok || ok && !out.Equal(test.out) {
+			t.Errorf("#%d: in.ReadASN1ObjectIdentifier() = %v, want %v; out = %v, want %v", i, ok, test.ok, out, test.out)
+			continue
+		}
+
+		var b Builder
+		b.AddASN1ObjectIdentifier(out)
+		result, err := b.Bytes()
+		if builderOk := err == nil; test.ok != builderOk {
+			t.Errorf("#%d: error from Builder.Bytes: %s", i, err)
+			continue
+		}
+		if test.ok && !bytes.Equal(result, test.in) {
+			t.Errorf("#%d: reserialisation didn't match, got %x, want %x", i, result, test.in)
+			continue
+		}
+	}
+}
+
+func TestReadASN1GeneralizedTime(t *testing.T) {
+	testData := []struct {
+		in  string
+		ok  bool
+		out time.Time
+	}{
+		{"20100102030405Z", true, time.Date(2010, 01, 02, 03, 04, 05, 0, time.UTC)},
+		{"20100102030405", false, time.Time{}},
+		{"20100102030405+0607", true, time.Date(2010, 01, 02, 03, 04, 05, 0, time.FixedZone("", 6*60*60+7*60))},
+		{"20100102030405-0607", true, time.Date(2010, 01, 02, 03, 04, 05, 0, time.FixedZone("", -6*60*60-7*60))},
+		/* These are invalid times. However, the time package normalises times
+		 * and they were accepted in some versions. See #11134. */
+		{"00000100000000Z", false, time.Time{}},
+		{"20101302030405Z", false, time.Time{}},
+		{"20100002030405Z", false, time.Time{}},
+		{"20100100030405Z", false, time.Time{}},
+		{"20100132030405Z", false, time.Time{}},
+		{"20100231030405Z", false, time.Time{}},
+		{"20100102240405Z", false, time.Time{}},
+		{"20100102036005Z", false, time.Time{}},
+		{"20100102030460Z", false, time.Time{}},
+		{"-20100102030410Z", false, time.Time{}},
+		{"2010-0102030410Z", false, time.Time{}},
+		{"2010-0002030410Z", false, time.Time{}},
+		{"201001-02030410Z", false, time.Time{}},
+		{"20100102-030410Z", false, time.Time{}},
+		{"2010010203-0410Z", false, time.Time{}},
+		{"201001020304-10Z", false, time.Time{}},
+	}
+	for i, test := range testData {
+		in := String(append([]byte{byte(asn1.GeneralizedTime), byte(len(test.in))}, test.in...))
+		var out time.Time
+		ok := in.ReadASN1GeneralizedTime(&out)
+		if ok != test.ok || ok && !reflect.DeepEqual(out, test.out) {
+			t.Errorf("#%d: in.ReadASN1GeneralizedTime() = %v, want %v; out = %q, want %q", i, ok, test.ok, out, test.out)
+		}
+	}
+}
+
+func TestReadASN1BitString(t *testing.T) {
+	testData := []struct {
+		in  []byte
+		ok  bool
+		out encoding_asn1.BitString
+	}{
+		{[]byte{}, false, encoding_asn1.BitString{}},
+		{[]byte{0x00}, true, encoding_asn1.BitString{}},
+		{[]byte{0x07, 0x00}, true, encoding_asn1.BitString{Bytes: []byte{0}, BitLength: 1}},
+		{[]byte{0x07, 0x01}, false, encoding_asn1.BitString{}},
+		{[]byte{0x07, 0x40}, false, encoding_asn1.BitString{}},
+		{[]byte{0x08, 0x00}, false, encoding_asn1.BitString{}},
+		{[]byte{0xff}, false, encoding_asn1.BitString{}},
+		{[]byte{0xfe, 0x00}, false, encoding_asn1.BitString{}},
+	}
+	for i, test := range testData {
+		in := String(append([]byte{3, byte(len(test.in))}, test.in...))
+		var out encoding_asn1.BitString
+		ok := in.ReadASN1BitString(&out)
+		if ok != test.ok || ok && (!bytes.Equal(out.Bytes, test.out.Bytes) || out.BitLength != test.out.BitLength) {
+			t.Errorf("#%d: in.ReadASN1BitString() = %v, want %v; out = %v, want %v", i, ok, test.ok, out, test.out)
+		}
+	}
+}

src/vendor/golang_org/x/crypto/cryptobyte/builder.go

+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cryptobyte
+
+import (
+	"errors"
+	"fmt"
+)
+
+// A Builder builds byte strings from fixed-length and length-prefixed values.
+// Builders either allocate space as needed, or are ‘fixed’, which means that
+// they write into a given buffer and produce an error if it's exhausted.
+//
+// The zero value is a usable Builder that allocates space as needed.
+//
+// Simple values are marshaled and appended to a Builder using methods on the
+// Builder. Length-prefixed values are marshaled by providing a
+// BuilderContinuation, which is a function that writes the inner contents of
+// the value to a given Builder. See the documentation for BuilderContinuation
+// for details.
+type Builder struct {
+	err            error
+	result         []byte
+	fixedSize      bool
+	child          *Builder
+	offset         int
+	pendingLenLen  int
+	pendingIsASN1  bool
+	inContinuation *bool
+}
+
+// NewBuilder creates a Builder that appends its output to the given buffer.
+// Like append(), the slice will be reallocated if its capacity is exceeded.
+// Use Bytes to get the final buffer.
+func NewBuilder(buffer []byte) *Builder {
+	return &Builder{
+		result: buffer,
+	}
+}
+
+// NewFixedBuilder creates a Builder that appends its output into the given
+// buffer. This builder does not reallocate the output buffer. Writes that
+// would exceed the buffer's capacity are treated as an error.
+func NewFixedBuilder(buffer []byte) *Builder {
+	return &Builder{
+		result:    buffer,
+		fixedSize: true,
+	}
+}
+
+// Bytes returns the bytes written by the builder or an error if one has
+// occurred during during building.
+func (b *Builder) Bytes() ([]byte, error) {
+	if b.err != nil {
+		return nil, b.err
+	}
+	return b.result[b.offset:], nil
+}
+
+// BytesOrPanic returns the bytes written by the builder or panics if an error
+// has occurred during building.
+func (b *Builder) BytesOrPanic() []byte {
+	if b.err != nil {
+		panic(b.err)
+	}
+	return b.result[b.offset:]
+}
+
+// AddUint8 appends an 8-bit value to the byte string.
+func (b *Builder) AddUint8(v uint8) {
+	b.add(byte(v))
+}
+
+// AddUint16 appends a big-endian, 16-bit value to the byte string.
+func (b *Builder) AddUint16(v uint16) {
+	b.add(byte(v>>8), byte(v))
+}
+
+// AddUint24 appends a big-endian, 24-bit value to the byte string. The highest
+// byte of the 32-bit input value is silently truncated.
+func (b *Builder) AddUint24(v uint32) {
+	b.add(byte(v>>16), byte(v>>8), byte(v))
+}
+
+// AddUint32 appends a big-endian, 32-bit value to the byte string.
+func (b *Builder) AddUint32(v uint32) {
+	b.add(byte(v>>24), byte(v>>16), byte(v>>8), byte(v))
+}
+
+// AddBytes appends a sequence of bytes to the byte string.
+func (b *Builder) AddBytes(v []byte) {
+	b.add(v...)
+}
+
+// BuilderContinuation is continuation-passing interface for building
+// length-prefixed byte sequences. Builder methods for length-prefixed
+// sequences (AddUint8LengthPrefixed etc) will invoke the BuilderContinuation
+// supplied to them. The child builder passed to the continuation can be used
+// to build the content of the length-prefixed sequence. For example:
+//
+//   parent := cryptobyte.NewBuilder()
+//   parent.AddUint8LengthPrefixed(func (child *Builder) {
+//     child.AddUint8(42)
+//     child.AddUint8LengthPrefixed(func (grandchild *Builder) {
+//       grandchild.AddUint8(5)
+//     })
+//   })
+//
+// It is an error to write more bytes to the child than allowed by the reserved
+// length prefix. After the continuation returns, the child must be considered
+// invalid, i.e. users must not store any copies or references of the child
+// that outlive the continuation.
+//
+// If the continuation panics with a value of type BuildError then the inner
+// error will be returned as the error from Bytes. If the child panics
+// otherwise then Bytes will repanic with the same value.
+type BuilderContinuation func(child *Builder)
+
+// BuildError wraps an error. If a BuilderContinuation panics with this value,
+// the panic will be recovered and the inner error will be returned from
+// Builder.Bytes.
+type BuildError struct {
+	Err error
+}
+
+// AddUint8LengthPrefixed adds a 8-bit length-prefixed byte sequence.
+func (b *Builder) AddUint8LengthPrefixed(f BuilderContinuation) {
+	b.addLengthPrefixed(1, false, f)
+}
+
+// AddUint16LengthPrefixed adds a big-endian, 16-bit length-prefixed byte sequence.
+func (b *Builder) AddUint16LengthPrefixed(f BuilderContinuation) {
+	b.addLengthPrefixed(2, false, f)
+}
+
+// AddUint24LengthPrefixed adds a big-endian, 24-bit length-prefixed byte sequence.
+func (b *Builder) AddUint24LengthPrefixed(f BuilderContinuation) {
+	b.addLengthPrefixed(3, false, f)
+}
+
+// AddUint32LengthPrefixed adds a big-endian, 32-bit length-prefixed byte sequence.
+func (b *Builder) AddUint32LengthPrefixed(f BuilderContinuation) {
+	b.addLengthPrefixed(4, false, f)
+}
+
+func (b *Builder) callContinuation(f BuilderContinuation, arg *Builder) {
+	if !*b.inContinuation {
+		*b.inContinuation = true
+
+		defer func() {
+			*b.inContinuation = false
+
+			r := recover()
+			if r == nil {
+				return
+			}
+
+			if buildError, ok := r.(BuildError); ok {
+				b.err = buildError.Err
+			} else {
+				panic(r)
+			}
+		}()
+	}
+
+	f(arg)
+}
+
+func (b *Builder) addLengthPrefixed(lenLen int, isASN1 bool, f BuilderContinuation) {
+	// Subsequent writes can be ignored if the builder has encountered an error.
+	if b.err != nil {
+		return
+	}
+
+	offset := len(b.result)
+	b.add(make([]byte, lenLen)...)
+
+	if b.inContinuation == nil {
+		b.inContinuation = new(bool)
+	}
+
+	b.child = &Builder{
+		result:         b.result,
+		fixedSize:      b.fixedSize,
+		offset:         offset,
+		pendingLenLen:  lenLen,
+		pendingIsASN1:  isASN1,
+		inContinuation: b.inContinuation,
+	}
+
+	b.callContinuation(f, b.child)
+	b.flushChild()
+	if b.child != nil {
+		panic("cryptobyte: internal error")
+	}
+}
+
+func (b *Builder) flushChild() {
+	if b.child == nil {
+		return
+	}
+	b.child.flushChild()
+	child := b.child
+	b.child = nil
+
+	if child.err != nil {
+		b.err = child.err
+		return
+	}
+
+	length := len(child.result) - child.pendingLenLen - child.offset
+
+	if length < 0 {
+		panic("cryptobyte: internal error") // result unexpectedly shrunk
+	}
+
+	if child.pendingIsASN1 {
+		// For ASN.1, we reserved a single byte for the length. If that turned out
+		// to be incorrect, we have to move the contents along in order to make
+		// space.
+		if child.pendingLenLen != 1 {
+			panic("cryptobyte: internal error")
+		}
+		var lenLen, lenByte uint8
+		if int64(length) > 0xfffffffe {
+			b.err = errors.New("pending ASN.1 child too long")
+			return
+		} else if length > 0xffffff {
+			lenLen = 5
+			lenByte = 0x80 | 4
+		} else if length > 0xffff {
+			lenLen = 4
+			lenByte = 0x80 | 3
+		} else if length > 0xff {
+			lenLen = 3
+			lenByte = 0x80 | 2
+		} else if length > 0x7f {
+			lenLen = 2
+			lenByte = 0x80 | 1
+		} else {
+			lenLen = 1
+			lenByte = uint8(length)
+			length = 0
+		}
+
+		// Insert the initial length byte, make space for successive length bytes,
+		// and adjust the offset.
+		child.result[child.offset] = lenByte
+		extraBytes := int(lenLen - 1)
+		if extraBytes != 0 {
+			child.add(make([]byte, extraBytes)...)
+			childStart := child.offset + child.pendingLenLen
+			copy(child.result[childStart+extraBytes:], child.result[childStart:])
+		}
+		child.offset++
+		child.pendingLenLen = extraBytes
+	}
+
+	l := length
+	for i := child.pendingLenLen - 1; i >= 0; i-- {
+		child.result[child.offset+i] = uint8(l)
+		l >>= 8
+	}
+	if l != 0 {
+		b.err = fmt.Errorf("cryptobyte: pending child length %d exceeds %d-byte length prefix", length, child.pendingLenLen)
+		return
+	}
+
+	if !b.fixedSize {
+		b.result = child.result // In case child reallocated result.
+	}
+}
+
+func (b *Builder) add(bytes ...byte) {
+	if b.err != nil {
+		return
+	}
+	if b.child != nil {
+		panic("attempted write while child is pending")
+	}
+	if len(b.result)+len(bytes) < len(bytes) {
+		b.err = errors.New("cryptobyte: length overflow")
+	}
+	if b.fixedSize && len(b.result)+len(bytes) > cap(b.result) {
+		b.err = errors.New("cryptobyte: Builder is exceeding its fixed-size buffer")
+		return
+	}
+	b.result = append(b.result, bytes...)
+}
+
+// A MarshalingValue marshals itself into a Builder.
+type MarshalingValue interface {
+	// Marshal is called by Builder.AddValue. It receives a pointer to a builder
+	// to marshal itself into. It may return an error that occurred during
+	// marshaling, such as unset or invalid values.
+	Marshal(b *Builder) error
+}
+
+// AddValue calls Marshal on v, passing a pointer to the builder to append to.
+// If Marshal returns an error, it is set on the Builder so that subsequent
+// appends don't have an effect.
+func (b *Builder) AddValue(v MarshalingValue) {
+	err := v.Marshal(b)
+	if err != nil {
+		b.err = err
+	}
+}

src/vendor/golang_org/x/crypto/cryptobyte/cryptobyte_test.go

+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cryptobyte
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func builderBytesEq(b *Builder, want ...byte) error {
+	got := b.BytesOrPanic()
+	if !bytes.Equal(got, want) {
+		return fmt.Errorf("Bytes() = %v, want %v", got, want)
+	}
+	return nil
+}
+
+func TestContinuationError(t *testing.T) {
+	const errorStr = "TestContinuationError"
+	var b Builder
+	b.AddUint8LengthPrefixed(func(b *Builder) {
+		b.AddUint8(1)
+		panic(BuildError{Err: errors.New(errorStr)})
+	})
+
+	ret, err := b.Bytes()
+	if ret != nil {
+		t.Error("expected nil result")
+	}
+	if err == nil {
+		t.Fatal("unexpected nil error")
+	}
+	if s := err.Error(); s != errorStr {
+		t.Errorf("expected error %q, got %v", errorStr, s)
+	}
+}
+
+func TestContinuationNonError(t *testing.T) {
+	defer func() {
+		recover()
+	}()
+
+	var b Builder
+	b.AddUint8LengthPrefixed(func(b *Builder) {
+		b.AddUint8(1)
+		panic(1)
+	})
+
+	t.Error("Builder did not panic")
+}
+
+func TestGeneratedPanic(t *testing.T) {
+	defer func() {
+		recover()
+	}()
+
+	var b Builder
+	b.AddUint8LengthPrefixed(func(b *Builder) {
+		var p *byte
+		*p = 0
+	})
+
+	t.Error("Builder did not panic")
+}
+
+func TestBytes(t *testing.T) {
+	var b Builder
+	v := []byte("foobarbaz")
+	b.AddBytes(v[0:3])
+	b.AddBytes(v[3:4])
+	b.AddBytes(v[4:9])
+	if err := builderBytesEq(&b, v...); err != nil {
+		t.Error(err)
+	}
+	s := String(b.BytesOrPanic())
+	for _, w := range []string{"foo", "bar", "baz"} {
+		var got []byte
+		if !s.ReadBytes(&got, 3) {
+			t.Errorf("ReadBytes() = false, want true (w = %v)", w)
+		}
+		want := []byte(w)
+		if !bytes.Equal(got, want) {
+			t.Errorf("ReadBytes(): got = %v, want %v", got, want)
+		}
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+}
+
+func TestUint8(t *testing.T) {
+	var b Builder
+	b.AddUint8(42)
+	if err := builderBytesEq(&b, 42); err != nil {
+		t.Error(err)
+	}
+
+	var s String = b.BytesOrPanic()
+	var v uint8
+	if !s.ReadUint8(&v) {
+		t.Error("ReadUint8() = false, want true")
+	}
+	if v != 42 {
+		t.Errorf("v = %d, want 42", v)
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+}
+
+func TestUint16(t *testing.T) {
+	var b Builder
+	b.AddUint16(65534)
+	if err := builderBytesEq(&b, 255, 254); err != nil {
+		t.Error(err)
+	}
+	var s String = b.BytesOrPanic()
+	var v uint16
+	if !s.ReadUint16(&v) {
+		t.Error("ReadUint16() == false, want true")
+	}
+	if v != 65534 {
+		t.Errorf("v = %d, want 65534", v)
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+}
+
+func TestUint24(t *testing.T) {
+	var b Builder
+	b.AddUint24(0xfffefd)
+	if err := builderBytesEq(&b, 255, 254, 253); err != nil {
+		t.Error(err)
+	}
+
+	var s String = b.BytesOrPanic()
+	var v uint32
+	if !s.ReadUint24(&v) {
+		t.Error("ReadUint8() = false, want true")
+	}
+	if v != 0xfffefd {
+		t.Errorf("v = %d, want fffefd", v)
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+}
+
+func TestUint24Truncation(t *testing.T) {
+	var b Builder
+	b.AddUint24(0x10111213)
+	if err := builderBytesEq(&b, 0x11, 0x12, 0x13); err != nil {
+		t.Error(err)
+	}
+}
+
+func TestUint32(t *testing.T) {
+	var b Builder
+	b.AddUint32(0xfffefdfc)
+	if err := builderBytesEq(&b, 255, 254, 253, 252); err != nil {
+		t.Error(err)
+	}
+
+	var s String = b.BytesOrPanic()
+	var v uint32
+	if !s.ReadUint32(&v) {
+		t.Error("ReadUint8() = false, want true")
+	}
+	if v != 0xfffefdfc {
+		t.Errorf("v = %x, want fffefdfc", v)
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+}
+
+func TestUMultiple(t *testing.T) {
+	var b Builder
+	b.AddUint8(23)
+	b.AddUint32(0xfffefdfc)
+	b.AddUint16(42)
+	if err := builderBytesEq(&b, 23, 255, 254, 253, 252, 0, 42); err != nil {
+		t.Error(err)
+	}
+
+	var s String = b.BytesOrPanic()
+	var (
+		x uint8
+		y uint32
+		z uint16
+	)
+	if !s.ReadUint8(&x) || !s.ReadUint32(&y) || !s.ReadUint16(&z) {
+		t.Error("ReadUint8() = false, want true")
+	}
+	if x != 23 || y != 0xfffefdfc || z != 42 {
+		t.Errorf("x, y, z = %d, %d, %d; want 23, 4294901244, 5", x, y, z)
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+}
+
+func TestUint8LengthPrefixedSimple(t *testing.T) {
+	var b Builder
+	b.AddUint8LengthPrefixed(func(c *Builder) {
+		c.AddUint8(23)
+		c.AddUint8(42)
+	})
+	if err := builderBytesEq(&b, 2, 23, 42); err != nil {
+		t.Error(err)
+	}
+
+	var base, child String = b.BytesOrPanic(), nil
+	var x, y uint8
+	if !base.ReadUint8LengthPrefixed(&child) || !child.ReadUint8(&x) ||
+		!child.ReadUint8(&y) {
+		t.Error("parsing failed")
+	}
+	if x != 23 || y != 42 {
+		t.Errorf("want x, y == 23, 42; got %d, %d", x, y)
+	}
+	if len(base) != 0 {
+		t.Errorf("len(base) = %d, want 0", len(base))
+	}
+	if len(child) != 0 {
+		t.Errorf("len(child) = %d, want 0", len(child))
+	}
+}
+
+func TestUint8LengthPrefixedMulti(t *testing.T) {
+	var b Builder
+	b.AddUint8LengthPrefixed(func(c *Builder) {
+		c.AddUint8(23)
+		c.AddUint8(42)
+	})
+	b.AddUint8(5)
+	b.AddUint8LengthPrefixed(func(c *Builder) {
+		c.AddUint8(123)
+		c.AddUint8(234)
+	})
+	if err := builderBytesEq(&b, 2, 23, 42, 5, 2, 123, 234); err != nil {
+		t.Error(err)
+	}
+
+	var s, child String = b.BytesOrPanic(), nil
+	var u, v, w, x, y uint8
+	if !s.ReadUint8LengthPrefixed(&child) || !child.ReadUint8(&u) || !child.ReadUint8(&v) ||
+		!s.ReadUint8(&w) || !s.ReadUint8LengthPrefixed(&child) || !child.ReadUint8(&x) || !child.ReadUint8(&y) {
+		t.Error("parsing failed")
+	}
+	if u != 23 || v != 42 || w != 5 || x != 123 || y != 234 {
+		t.Errorf("u, v, w, x, y = %d, %d, %d, %d, %d; want 23, 42, 5, 123, 234",
+			u, v, w, x, y)
+	}
+	if len(s) != 0 {
+		t.Errorf("len(s) = %d, want 0", len(s))
+	}
+	if len(child) != 0 {
+		t.Errorf("len(child) = %d, want 0", len(child))
+	}
+}
+
+func TestUint8LengthPrefixedNested(t *testing.T) {
+	var b Builder
+	b.AddUint8LengthPrefixed(func(c *Builder) {
+		c.AddUint8(5)
+		c.AddUint8LengthPrefixed(func(d *Builder) {
+			d.AddUint8(23)
+			d.AddUint8(42)
+		})
+		c.AddUint8(123)
+	})
+	if err := builderBytesEq(&b, 5, 5, 2, 23, 42, 123); err != nil {
+		t.Error(err)
+	}
+
+	var base, child1, child2 String = b.BytesOrPanic(), nil, nil
+	var u, v, w, x uint8
+	if !base.ReadUint8LengthPrefixed(&child1) {
+		t.Error("parsing base failed")
+	}
+	if !child1.ReadUint8(&u) || !child1.ReadUint8LengthPrefixed(&child2) || !child1.ReadUint8(&x) {
+		t.Error("parsing child1 failed")
+	}
+	if !child2.ReadUint8(&v) || !child2.ReadUint8(&w) {
+		t.Error("parsing child2 failed")
+	}
+	if u != 5 || v != 23 || w != 42 || x != 123 {
+		t.Errorf("u, v, w, x = %d, %d, %d, %d, want 5, 23, 42, 123",
+			u, v, w, x)
+	}
+	if len(base) != 0 {
+		t.Errorf("len(base) = %d, want 0", len(base))
+	}
+	if len(child1) != 0 {
+		t.Errorf("len(child1) = %d, want 0", len(child1))
+	}
+	if len(base) != 0 {
+		t.Errorf("len(child2) = %d, want 0", len(child2))
+	}
+}
+
+func TestPreallocatedBuffer(t *testing.T) {
+	var buf [5]byte
+	b := NewBuilder(buf[0:0])
+	b.AddUint8(1)
+	b.AddUint8LengthPrefixed(func(c *Builder) {
+		c.AddUint8(3)
+		c.AddUint8(4)
+	})
+	b.AddUint16(1286) // Outgrow buf by one byte.
+	want := []byte{1, 2, 3, 4, 0}
+	if !bytes.Equal(buf[:], want) {
+		t.Errorf("buf = %v want %v", buf, want)
+	}
+	if err := builderBytesEq(b, 1, 2, 3, 4, 5, 6); err != nil {
+		t.Error(err)
+	}
+}
+
+func TestWriteWithPendingChild(t *testing.T) {
+	var b Builder
+	b.AddUint8LengthPrefixed(func(c *Builder) {
+		c.AddUint8LengthPrefixed(func(d *Builder) {
+			defer func() {
+				if recover() == nil {
+					t.Errorf("recover() = nil, want error; c.AddUint8() did not panic")
+				}
+			}()
+			c.AddUint8(2) // panics
+
+			defer func() {
+				if recover() == nil {
+					t.Errorf("recover() = nil, want error; b.AddUint8() did not panic")
+				}
+			}()
+			b.AddUint8(2) // panics
+		})
+
+		defer func() {
+			if recover() == nil {
+				t.Errorf("recover() = nil, want error; b.AddUint8() did not panic")
+			}
+		}()
+		b.AddUint8(2) // panics
+	})
+}
+
+// ASN.1
+
+func TestASN1Int64(t *testing.T) {
+	tests := []struct {
+		in   int64
+		want []byte
+	}{
+		{-0x800000, []byte{2, 3, 128, 0, 0}},
+		{-256, []byte{2, 2, 255, 0}},
+		{-129, []byte{2, 2, 255, 127}},
+		{-128, []byte{2, 1, 128}},
+		{-1, []byte{2, 1, 255}},
+		{0, []byte{2, 1, 0}},
+		{1, []byte{2, 1, 1}},
+		{2, []byte{2, 1, 2}},
+		{127, []byte{2, 1, 127}},
+		{128, []byte{2, 2, 0, 128}},
+		{256, []byte{2, 2, 1, 0}},
+		{0x800000, []byte{2, 4, 0, 128, 0, 0}},
+	}
+	for i, tt := range tests {
+		var b Builder
+		b.AddASN1Int64(tt.in)
+		if err := builderBytesEq(&b, tt.want...); err != nil {
+			t.Errorf("%v, (i = %d; in = %v)", err, i, tt.in)
+		}
+
+		var n int64
+		s := String(b.BytesOrPanic())
+		ok := s.ReadASN1Integer(&n)
+		if !ok || n != tt.in {
+			t.Errorf("s.ReadASN1Integer(&n) = %v, n = %d; want true, n = %d (i = %d)",
+				ok, n, tt.in, i)
+		}
+		if len(s) != 0 {
+			t.Errorf("len(s) = %d, want 0", len(s))
+		}
+	}
+}
+
+func TestASN1Uint64(t *testing.T) {
+	tests := []struct {
+		in   uint64
+		want []byte
+	}{
+		{0, []byte{2, 1, 0}},
+		{1, []byte{2, 1, 1}},
+		{2, []byte{2, 1, 2}},
+		{127, []byte{2, 1, 127}},
+		{128, []byte{2, 2, 0, 128}},
+		{256, []byte{2, 2, 1, 0}},
+		{0x800000, []byte{2, 4, 0, 128, 0, 0}},
+		{0x7fffffffffffffff, []byte{2, 8, 127, 255, 255, 255, 255, 255, 255, 255}},
+		{0x8000000000000000, []byte{2, 9, 0, 128, 0, 0, 0, 0, 0, 0, 0}},
+		{0xffffffffffffffff, []byte{2, 9, 0, 255, 255, 255, 255, 255, 255, 255, 255}},
+	}
+	for i, tt := range tests {
+		var b Builder
+		b.AddASN1Uint64(tt.in)
+		if err := builderBytesEq(&b, tt.want...); err != nil {
+			t.Errorf("%v, (i = %d; in = %v)", err, i, tt.in)
+		}
+
+		var n uint64
+		s := String(b.BytesOrPanic())
+		ok := s.ReadASN1Integer(&n)
+		if !ok || n != tt.in {
+			t.Errorf("s.ReadASN1Integer(&n) = %v, n = %d; want true, n = %d (i = %d)",
+				ok, n, tt.in, i)
+		}
+		if len(s) != 0 {
+			t.Errorf("len(s) = %d, want 0", len(s))
+		}
+	}
+}

src/vendor/golang_org/x/crypto/cryptobyte/example_test.go

+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cryptobyte_test
+
+import (
+	"errors"
+	"fmt"
+
+	"golang_org/x/crypto/cryptobyte"
+	"golang_org/x/crypto/cryptobyte/asn1"
+)
+
+func ExampleString_lengthPrefixed() {
+	// This is an example of parsing length-prefixed data (as found in, for
+	// example, TLS). Imagine a 16-bit prefixed series of 8-bit prefixed
+	// strings.
+
+	input := cryptobyte.String([]byte{0, 12, 5, 'h', 'e', 'l', 'l', 'o', 5, 'w', 'o', 'r', 'l', 'd'})
+	var result []string
+
+	var values cryptobyte.String
+	if !input.ReadUint16LengthPrefixed(&values) ||
+		!input.Empty() {
+		panic("bad format")
+	}
+
+	for !values.Empty() {
+		var value cryptobyte.String
+		if !values.ReadUint8LengthPrefixed(&value) {
+			panic("bad format")
+		}
+
+		result = append(result, string(value))
+	}
+
+	// Output: []string{"hello", "world"}
+	fmt.Printf("%#v\n", result)
+}
+
+func ExampleString_aSN1() {
+	// This is an example of parsing ASN.1 data that looks like:
+	//    Foo ::= SEQUENCE {
+	//      version [6] INTEGER DEFAULT 0
+	//      data OCTET STRING
+	//    }
+
+	input := cryptobyte.String([]byte{0x30, 12, 0xa6, 3, 2, 1, 2, 4, 5, 'h', 'e', 'l', 'l', 'o'})
+
+	var (
+		version                   int64
+		data, inner, versionBytes cryptobyte.String
+		haveVersion               bool
+	)
+	if !input.ReadASN1(&inner, asn1.SEQUENCE) ||
+		!input.Empty() ||
+		!inner.ReadOptionalASN1(&versionBytes, &haveVersion, asn1.Tag(6).Constructed().ContextSpecific()) ||
+		(haveVersion && !versionBytes.ReadASN1Integer(&version)) ||
+		(haveVersion && !versionBytes.Empty()) ||
+		!inner.ReadASN1(&data, asn1.OCTET_STRING) ||
+		!inner.Empty() {
+		panic("bad format")
+	}
+
+	// Output: haveVersion: true, version: 2, data: hello
+	fmt.Printf("haveVersion: %t, version: %d, data: %s\n", haveVersion, version, string(data))
+}
+
+func ExampleBuilder_aSN1() {
+	// This is an example of building ASN.1 data that looks like:
+	//    Foo ::= SEQUENCE {
+	//      version [6] INTEGER DEFAULT 0
+	//      data OCTET STRING
+	//    }
+
+	version := int64(2)
+	data := []byte("hello")
+	const defaultVersion = 0
+
+	var b cryptobyte.Builder
+	b.AddASN1(asn1.SEQUENCE, func(b *cryptobyte.Builder) {
+		if version != defaultVersion {
+			b.AddASN1(asn1.Tag(6).Constructed().ContextSpecific(), func(b *cryptobyte.Builder) {
+				b.AddASN1Int64(version)
+			})
+		}
+		b.AddASN1OctetString(data)
+	})
+
+	result, err := b.Bytes()
+	if err != nil {
+		panic(err)
+	}
+
+	// Output: 300ca603020102040568656c6c6f
+	fmt.Printf("%x\n", result)
+}
+
+func ExampleBuilder_lengthPrefixed() {
+	// This is an example of building length-prefixed data (as found in,
+	// for example, TLS). Imagine a 16-bit prefixed series of 8-bit
+	// prefixed strings.
+	input := []string{"hello", "world"}
+
+	var b cryptobyte.Builder
+	b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) {
+		for _, value := range input {
+			b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
+				b.AddBytes([]byte(value))
+			})
+		}
+	})
+
+	result, err := b.Bytes()
+	if err != nil {
+		panic(err)
+	}
+
+	// Output: 000c0568656c6c6f05776f726c64
+	fmt.Printf("%x\n", result)
+}
+
+func ExampleBuilder_lengthPrefixOverflow() {
+	// Writing more data that can be expressed by the length prefix results
+	// in an error from Bytes().
+
+	tooLarge := make([]byte, 256)
+
+	var b cryptobyte.Builder
+	b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
+		b.AddBytes(tooLarge)
+	})
+
+	result, err := b.Bytes()
+	fmt.Printf("len=%d err=%s\n", len(result), err)
+
+	// Output: len=0 err=cryptobyte: pending child length 256 exceeds 1-byte length prefix
+}
+
+func ExampleBuilderContinuation_errorHandling() {
+	var b cryptobyte.Builder
+	// Continuations that panic with a BuildError will cause Bytes to
+	// return the inner error.
+	b.AddUint16LengthPrefixed(func(b *cryptobyte.Builder) {
+		b.AddUint32(0)
+		panic(cryptobyte.BuildError{Err: errors.New("example error")})
+	})
+
+	result, err := b.Bytes()
+	fmt.Printf("len=%d err=%s\n", len(result), err)
+
+	// Output: len=0 err=example error
+}

src/vendor/golang_org/x/crypto/cryptobyte/string.go

+// Copyright 2017 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package cryptobyte contains types that help with parsing and constructing
+// length-prefixed, binary messages, including ASN.1 DER. (The asn1 subpackage
+// contains useful ASN.1 constants.)
+//
+// The String type is for parsing. It wraps a []byte slice and provides helper
+// functions for consuming structures, value by value.
+//
+// The Builder type is for constructing messages. It providers helper functions
+// for appending values and also for appending length-prefixed submessages –
+// without having to worry about calculating the length prefix ahead of time.
+//
+// See the documentation and examples for the Builder and String types to get
+// started.
+package cryptobyte // import "golang.org/x/crypto/cryptobyte"
+
+// String represents a string of bytes. It provides methods for parsing
+// fixed-length and length-prefixed values from it.
+type String []byte
+
+// read advances a String by n bytes and returns them. If less than n bytes
+// remain, it returns nil.
+func (s *String) read(n int) []byte {
+	if len(*s) < n {
+		return nil
+	}
+	v := (*s)[:n]
+	*s = (*s)[n:]
+	return v
+}
+
+// Skip advances the String by n byte and reports whether it was successful.
+func (s *String) Skip(n int) bool {
+	return s.read(n) != nil
+}
+
+// ReadUint8 decodes an 8-bit value into out and advances over it. It
+// returns true on success and false on error.
+func (s *String) ReadUint8(out *uint8) bool {
+	v := s.read(1)
+	if v == nil {
+		return false
+	}
+	*out = uint8(v[0])
+	return true
+}
+
+// ReadUint16 decodes a big-endian, 16-bit value into out and advances over it.
+// It returns true on success and false on error.
+func (s *String) ReadUint16(out *uint16) bool {
+	v := s.read(2)
+	if v == nil {
+		return false
+	}
+	*out = uint16(v[0])<<8 | uint16(v[1])
+	return true
+}
+
+// ReadUint24 decodes a big-endian, 24-bit value into out and advances over it.
+// It returns true on success and false on error.
+func (s *String) ReadUint24(out *uint32) bool {
+	v := s.read(3)
+	if v == nil {
+		return false
+	}
+	*out = uint32(v[0])<<16 | uint32(v[1])<<8 | uint32(v[2])
+	return true
+}
+
+// ReadUint32 decodes a big-endian, 32-bit value into out and advances over it.
+// It returns true on success and false on error.
+func (s *String) ReadUint32(out *uint32) bool {
+	v := s.read(4)
+	if v == nil {
+		return false
+	}
+	*out = uint32(v[0])<<24 | uint32(v[1])<<16 | uint32(v[2])<<8 | uint32(v[3])
+	return true
+}
+
+func (s *String) readUnsigned(out *uint32, length int) bool {
+	v := s.read(length)
+	if v == nil {
+		return false
+	}
+	var result uint32
+	for i := 0; i < length; i++ {
+		result <<= 8
+		result |= uint32(v[i])
+	}
+	*out = result
+	return true
+}
+
+func (s *String) readLengthPrefixed(lenLen int, outChild *String) bool {
+	lenBytes := s.read(lenLen)
+	if lenBytes == nil {
+		return false
+	}
+	var length uint32
+	for _, b := range lenBytes {
+		length = length << 8
+		length = length | uint32(b)
+	}
+	if int(length) < 0 {
+		// This currently cannot overflow because we read uint24 at most, but check
+		// anyway in case that changes in the future.
+		return false
+	}
+	v := s.read(int(length))
+	if v == nil {
+		return false
+	}
+	*outChild = v
+	return true
+}
+
+// ReadUint8LengthPrefixed reads the content of an 8-bit length-prefixed value
+// into out and advances over it. It returns true on success and false on
+// error.
+func (s *String) ReadUint8LengthPrefixed(out *String) bool {
+	return s.readLengthPrefixed(1, out)
+}
+
+// ReadUint16LengthPrefixed reads the content of a big-endian, 16-bit
+// length-prefixed value into out and advances over it. It returns true on
+// success and false on error.
+func (s *String) ReadUint16LengthPrefixed(out *String) bool {
+	return s.readLengthPrefixed(2, out)
+}
+
+// ReadUint24LengthPrefixed reads the content of a big-endian, 24-bit
+// length-prefixed value into out and advances over it. It returns true on
+// success and false on error.
+func (s *String) ReadUint24LengthPrefixed(out *String) bool {
+	return s.readLengthPrefixed(3, out)
+}
+
+// ReadBytes reads n bytes into out and advances over them. It returns true on
+// success and false and error.
+func (s *String) ReadBytes(out *[]byte, n int) bool {
+	v := s.read(n)
+	if v == nil {
+		return false
+	}
+	*out = v
+	return true
+}
+
+// CopyBytes copies len(out) bytes into out and advances over them. It returns
+// true on success and false on error.
+func (s *String) CopyBytes(out []byte) bool {
+	n := len(out)
+	v := s.read(n)
+	if v == nil {
+		return false
+	}
+	return copy(out, v) == n
+}
+
+// Empty reports whether the string does not contain any bytes.
+func (s String) Empty() bool {
+	return len(s) == 0
+}