BER-TLV

Package bertlv implements encoding and decoding of BER-TLV structures using struct tags, similar to encoding/json.

go get github.com/skythen/bertlv

Struct Tags

Use the bertlv struct tag to map struct fields to BER-TLV tags.

Hex Format

Use the 0x prefix to specify tags as hex bytes. Class and construction are derived from the encoded tag bytes:

type FCI struct {
    AID       []byte   `bertlv:"0x4F"`
    Label     []byte   `bertlv:"0x50"`
    Track2    []byte   `bertlv:"0x57"`
    ExpDate   []byte   `bertlv:"0x5F24"`  // multi-byte tags
    Records   []Record `bertlv:"0x70"`    // constructed tags decode recursively
}

Decimal Format

Specify tag number and class explicitly:

"<number>,<class>[,options...]"

• number: Decimal tag number (0-16383)
• class: One of universal, application, context, private

type Data struct {
    Field1 []byte `bertlv:"1,universal"`
    Field2 []byte `bertlv:"2,application"`
    Field3 []byte `bertlv:"3,context"`
}

Options

• omitempty - skip field during encoding if empty/zero
• required - return error during decoding if tag is not present

type Data struct {
    Required []byte `bertlv:"0x4F,required"`
    Optional []byte `bertlv:"0x50,omitempty"`
    Both     []byte `bertlv:"1,universal,required,omitempty"`
}

Unmarshal

Decode BER-TLV data into a struct:

var result struct {
    AID   []byte `bertlv:"0x4F"`
    Label []byte `bertlv:"0x50"`
}

err := bertlv.Unmarshal(data, &result)

Options

opts := bertlv.Options{
    DisallowUnknownFields: true,
}

err := bertlv.UnmarshalWithOptions(data, &result, opts)

Custom Unmarshaler

Implement the Unmarshaler interface for custom decoding:

type MyType struct {
    Value string
}

func (m *MyType) UnmarshalBERTLV(value []byte) error {
    m.Value = string(value)
    return nil
}

Marshal

Encode a struct into BER-TLV format:

data := struct {
    AID   []byte `bertlv:"0x4F"`
    Label []byte `bertlv:"0x50"`
}{
    AID:   []byte{0xA0, 0x00, 0x00, 0x00, 0x04, 0x10, 0x10},
    Label: "GoCard",
}

encoded, err := bertlv.Marshal(data)

Custom Marshaler

Implement the Marshaler interface for custom encoding:

func (m MyType) MarshalBERTLV() ([]byte, error) {
    return []byte(m.Value), nil
}

Supported Types

The following Go types can be used as struct fields:

• []byte - raw TLV value
• string - UTF-8 encoded value
• int, int8, int16, int32, int64 - big-endian signed integers
• uint, uint8, uint16, uint32, uint64 - big-endian unsigned integers
• bool - single byte (0x00 = false, non-zero = true)
• struct - nested constructed TLV
• []T (slice of structs) - repeated TLV elements