cbor

package module
v0.0.0-...-2c15c13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 2, 2023 License: MPL-2.0 Imports: 15 Imported by: 0

README

CBOR

Concise Binary Object Representation (CBOR) is a schemaless data format designed to be small and extensible. This package implements a minimal CBOR encoder and decoder in a similar style to the encoding/json package.

Warning: this is a work in progress, mostly for learning purposes. See github.com/fxamacker/cbor for a more robust implementation.

package main

import (
	"bytes"
	"fmt"

	"github.com/picatz/cbor"
)

// This code shows how to encode and decode the CBOR data format.
func main() {
	// CBOR encoding of the value {"hello": "world"}.
	const data = "\xA1\x65\x68\x65\x6C\x6C\x6F\x65\x77\x6F\x72\x6C\x64"

	// Create a new cbor.Decoder using bytes.NewBufferString(data) as its source,
	// and then Decode the CBOR data into the value map[string]string.
	var value map[string]string
	err := cbor.NewDecoder(bytes.NewBufferString(data)).Decode(&value)
	if err != nil {
		panic(err)
	}

	// Output: world
	fmt.Println(value["hello"])

	// Encode the value map[string]string using the cbor.NewEncoder.
	//
	// Note: this currently doesn't encode the data exactly the same 
	//       as it got it (non-canonical).
	var buf = bytes.NewBuffer(nil)
	err = cbor.NewEncoder(buf).Encode(value)
	if err != nil {
		panic(err)
	}

	// Output: b80278036f6e6501780374776f02
	fmt.Printf("%x\n", buf.Bytes())
}

Documentation

Overview

Package cbor implements a minimal Concise Binary Object Representation (CBOR) encoder and decoder in a similar style to the encoding/json package.

CBOR is a binary data format defined in RFC 7049.

https://tools.ietf.org/html/rfc7049

Index

Examples

Constants

View Source 
const DefaultMaxValue = 10_000

DefaultMaxValue is the default maximum value for the decoder used for all limits. This is a generous value that should be sufficient for most use cases. If you need to decode larger values, you can increase the limit using the appropriate.

If you do not need to decode large values, you can decrease the limit to reduce the memory usage of the decoder. This is also useful for mitigating DoS attacks.

Variables

View Source 
var DefaultDecoderOptions = DecoderOptions{
	MaxArrayElements: DefaultMaxValue,
	MaxMapPairs:      DefaultMaxValue,
	MaxStringBytes:   DefaultMaxValue,
	MaxBytes:         DefaultMaxValue,
}

DefaultDecoderOptions is the default decoder options used by the decoder.

Functions

func Unmarshal 

func Unmarshal(data []byte, v interface{}) error

Unmarshall unmarsalls the CBOR-encoded data and stores the result in the value pointed to by v.

If v is nil or not a pointer, Unmarshal returns an InvalidUnmarshalError.

If v is a pointer to a nil pointer, Unmarshal allocates a new value for it to point to.

If v implements the Unmarshaler interface, Unmarshal calls its UnmarshalCBOR method with the CBOR data and returns its error, if any.

Otherwise, if the CBOR data is a CBOR array, Unmarshal decodes the CBOR array into the slice pointed to by v. If v is not a pointer to a slice, Unmarshal returns an InvalidUnmarshalError.

Otherwise, if the CBOR data is a CBOR map, Unmarshal decodes the CBOR map into the map pointed to by v. If v is not a pointer to a map, Unmarshal returns an InvalidUnmarshalError.

Otherwise, Unmarshal decodes the CBOR data into the value pointed to by v. If v is not a pointer, Unmarshal returns an InvalidUnmarshalError.

Types

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads and decodes CBOR values from an input stream.

It is not safe to be called from multiple goroutines.

Example 
package main

import (
	"bytes"
	"fmt"

	"github.com/picatz/cbor"
)

func main() {
	const data = "\xA1\x65\x68\x65\x6C\x6C\x6F\x65\x77\x6F\x72\x6C\x64" // {"hello": "world"}

	var value map[string]string
	err := cbor.NewDecoder(bytes.NewBufferString(data)).Decode(&value)
	if err != nil {
		panic(err)
	}

	fmt.Println(value["hello"])
}

Output:

world

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

func (*Decoder) Decode 

func (dec *Decoder) Decode(v interface{}) error

Decode reads the next CBOR-encoded value from its input and stores it in the value pointed to by v.

See the documentation for Unmarshal for details about the conversion of a CBOR value into a Go value.

func (*Decoder) SetMax 

func (dec *Decoder) SetMax(n int)

SetMax sets all the maximum values to n.

func (*Decoder) SetMaxArrayElements 

func (dec *Decoder) SetMaxArrayElements(n int)

SetMaxArrayElements sets the maximum number of elements in an array.

If the number of elements in an array exceeds this limit, an error is returned.

The default limit is 10,000.

func (*Decoder) SetMaxBytes 

func (dec *Decoder) SetMaxBytes(n int)

SetMaxBytes sets the maximum number of bytes in a byte string.

If the number of bytes in a byte string exceeds this limit, an error is returned.

The default limit is 10,000.

func (*Decoder) SetMaxMapPairs 

func (dec *Decoder) SetMaxMapPairs(n int)

SetMaxMapPairs sets the maximum number of pairs in a map.

If the number of pairs in a map exceeds this limit, an error is returned.

The default limit is 10,000.

func (*Decoder) SetMaxStringBytes 

func (dec *Decoder) SetMaxStringBytes(n int)

SetMaxStringBytes sets the maximum number of bytes in a string.

If the number of bytes in a string exceeds this limit, an error is returned.

The default limit is 10,000.

type DecoderOptions 

type DecoderOptions struct {
	MaxArrayElements int
	MaxMapPairs      int
	MaxStringBytes   int
	MaxBytes         int
}

Decoder options.

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is a minimal CBOR encoder.

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode 

func (e *Encoder) Encode(v interface{}) error

Encode writes the CBOR encoding of v to the stream.

type MajorType 

type MajorType int

MajorType is the major type of a CBOR item.

https://tools.ietf.org/html/rfc7049#section-2.1 

const (
	// MajorTypeUnsignedInt is the major type for unsigned integers.
	MajorTypeUnsignedInt MajorType = 0 // uint

	// MajorTypeNegativeInt is the major type for negative integers.
	MajorTypeNegativeInt MajorType = 1 // int

	// MajorTypeByteString is the major type for byte strings.
	MajorTypeByteString MajorType = 2 // []byte

	// MajorTypeTextString is the major type for text strings.
	MajorTypeTextString MajorType = 3 // string

	// MajorTypeArray is the major type for arrays.
	MajorTypeArray MajorType = 4 // []any

	// MajorTypeMap is the major type for maps.
	MajorTypeMap MajorType = 5 // map[any]any

	// MajorTypeTag is the major type for tags.
	MajorTypeTag MajorType = 6 // tag

	// MajorTypeSimple is the major type for simple values.
	MajorTypeSimple MajorType = 7 // simple (bool, nil, etc.)
)

Major types defined in RFC 7049.

type Marshaler 

type Marshaler interface {
	MarshalCBOR() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into a CBOR description.

MarshalCBOR must copy the CBOR data if it wishes to retain the data after returning.

type SimpleValue 

type SimpleValue int

SimpleValue is a simple value.

https://tools.ietf.org/html/rfc7049#section-2.3 

const (
	// SimpleValueFalse is the simple value for false.
	SimpleValueFalse SimpleValue = 20

	// SimpleValueTrue is the simple value for true.
	SimpleValueTrue SimpleValue = 21

	// SimpleValueNull is the simple value for null.
	SimpleValueNull SimpleValue = 22

	// SimpleValueUndefined is the simple value for undefined.
	SimpleValueUndefined SimpleValue = 23

	// SimpleValueSimpleValue is the simple value for simple value.
	SimpleValueSimpleValue SimpleValue = 24

	// SimpleValueFloat16 is the simple value for a 16-bit float.
	SimpleValueFloat16 SimpleValue = 25

	// SimpleValueFloat32 is the simple value for a 32-bit float.
	SimpleValueFloat32 SimpleValue = 26

	// SimpleValueFloat64 is the simple value for a 64-bit float.
	SimpleValueFloat64 SimpleValue = 27

	// SimpleValueBreak is the simple value for break.
	SimpleValueBreak SimpleValue = 31
)

Simple values defined in RFC 7049.

type Tag 

type Tag int

Tag is a CBOR tag.

https://tools.ietf.org/html/rfc7049#section-2.4 

const (
	// TagDateTimeString is the tag for a date/time string.
	TagDateTimeString Tag = 0

	// TagUnixTime is the tag for a Unix time.
	TagUnixTime Tag = 1

	// TagPositiveBignum is the tag for a positive bignum.
	TagPositiveBignum Tag = 2

	// TagNegativeBignum is the tag for a negative bignum.
	TagNegativeBignum Tag = 3

	// TagDecimalFraction is the tag for a decimal fraction.
	TagDecimalFraction Tag = 4

	// TagBigfloat is the tag for a bigfloat.
	TagBigfloat Tag = 5

	// TagBase64URL is the tag for a base64url-encoded string.
	TagBase64URL Tag = 21

	// TagBase64 is the tag for a base64-encoded string.
	TagBase64 Tag = 22

	// TagBase16 is the tag for a base16-encoded string.
	TagBase16 Tag = 23

	// TagCBOR is the tag for a CBOR-encoded value.
	TagCBOR Tag = 24

	// TagURI is the tag for a URI.
	TagURI Tag = 32

	// TagBase64URLNoPadding is the tag for a base64url-encoded string
	// without padding.
	TagBase64URLNoPadding Tag = 33

	// TagBase64NoPadding is the tag for a base64-encoded string without
	// padding.
	TagBase64NoPadding Tag = 34

	// TagRegularExpression is the tag for a regular expression.
	TagRegularExpression Tag = 35

	// TagMIMEMessage is the tag for a MIME message.
	TagMIMEMessage Tag = 36

	// TagCBORSequence is the tag for a CBOR sequence.
	TagCBORSequence Tag = 258

	// TagCBORMap is the tag for a CBOR map.
	TagCBORMap Tag = 259

	// TagCBORSet is the tag for a CBOR set.
	TagCBORSet Tag = 260

	// TagCBORDateTimeString is the tag for a CBOR date/time string.
	TagCBORDateTimeString Tag = 261

	// TagCBORUnixTime is the tag for a CBOR Unix time.
	TagCBORUnixTime Tag = 262

	// TagCBORPositiveBignum is the tag for a CBOR positive bignum.
	TagCBORPositiveBignum Tag = 263

	// TagCBORNegativeBignum is the tag for a CBOR negative bignum.
	TagCBORNegativeBignum Tag = 264

	// TagCBORDecimalFraction is the tag for a CBOR decimal fraction.
	TagCBORDecimalFraction Tag = 265

	// TagCBORBigfloat is the tag for a CBOR bigfloat.
	TagCBORBigfloat Tag = 266

	// TagCBORBase64URL is the tag for a CBOR base64url-encoded string.
	TagCBORBase64URL Tag = 267

	// TagCBORBase64 is the tag for a CBOR base64-encoded string.
	TagCBORBase64 Tag = 268

	// TagCBORBase16 is the tag for a CBOR base16-encoded string.
	TagCBORBase16 Tag = 269

	// TagCBORURI is the tag for a CBOR URI.
	TagCBORURI Tag = 270

	// TagCBORBase64URLNoPadding is the tag for a CBOR base64url-encoded
	// string without padding.
	TagCBORBase64URLNoPadding Tag = 271

	// TagCBORBase64NoPadding is the tag for a CBOR base64-encoded string
	// without padding.
	TagCBORBase64NoPadding Tag = 272

	// TagCBORRegularExpression is the tag for a CBOR regular expression.
	TagCBORRegularExpression Tag = 273

	// TagCBORMIMEMessage is the tag for a CBOR MIME message.
	TagCBORMIMEMessage Tag = 274
)

Tags defined in RFC 7049.

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalCBOR([]byte) error
}

Unmarshaler is the interface implemented by types that can unmarshal a CBOR description of themselves.

The input can be assumed to be a valid encoding of a CBOR value. UnmarshalCBOR must copy the CBOR data if it wishes to retain the data after returning.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.