ber

type BerDecoder ¶

type BerDecoder interface {
	BerDecode(tag asn1.Tag, r ElementReader) error
}

BerDecoder is the interfaces implemented by types that can decode themselves from a binary representation in BER-encoding. In addition, types may want to implement the BerMatcher interface to provide support for optional elements.

The reader r reads the contents of the element, identified by tag. In particular r does not read the tag and length bytes of the element being decoded. At the end of the element r returns io.EOF, even if there are more bytes in the original data stream. If an implementation does not read r to completion, any remaining bytes are discarded. If r.Constructed() returns true, the remaining elements are syntactically validated.

Implementations must attempt to decode from r irrespective of the tag. However, implementations may alter their decoding behavior according to the tag used. Implementations SHOULD validate that r.Constructed() meets the requirements of the element. If decoding fails, an error must be returned that explains the failure. Usually such an error should be a SyntaxError or StructuralError. Implementations can also return io.ErrUnexpectedEOF to indicate that r returned io.EOF before the entire data was read.

The length of the element being decoded is available through r. Note that an element may use the indefinite length encoding in which case r might indicate a length of LengthIndefinite.

type BerEncoder ¶

type BerEncoder interface {
	BerEncode() (h Header, wt io.WriterTo, err error)
}

BerEncoder is an interface that can be implemented by types that provide custom logic to encode themselves as an ASN.1 type using Basic Encoding Rules.

Encoding using BER is a two-step process: First the size of values is estimated and then elements are written to a byte stream. The BerEncode method realizes this by returning an io.WriterTo instead of writing data directly to a writer. Implementations write exactly the amount of bytes promised by h.Length. The writer passed to wt implements io.ByteWriter.

Implementations should return any validation errors from BerEncode. Errors returned from wt are assumed to be writing errors of the underlying writer.

If an element uses the indefinite-length format, the final two zero octets are written automatically and must not be written by wt. Custom constructed elements may want to use the Sequence type to facilitate their encoding. Note that struct tags override the class and tag of the returned header.

type BerMatcher ¶

type BerMatcher interface {
	BerMatch(asn1.Tag) bool
}

BerMatcher can be implemented by types that implement BerDecoder to add support for optional elements. The BerMatch method is consulted if no tag number is given via struct tags. Implementations implement this interface by returning a boolean value indicating whether h.Class and h.Tag match the intrinsic tag of the element, i.e. if based on the h.Class and h.Tag it is expected that decoding will succeed.

type Decoder ¶

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

Decoder implements stream-based decoding of BER-encoded ASN.1 types. The Decoder type implements specialized buffering for BER-data. See the NewDecoder function for details.

To create a Decoder, use the NewDecoder function.

func NewDecoder(r io.Reader) (d *Decoder)

func (d *Decoder) Decode(val any) error

func (d *Decoder) DecodeAll(val any) error

func (d *Decoder) DecodeWithParams(val any, params string) error

func (d *Decoder) More() bool

func (d *Decoder) Next() (Header, ElementReader, error)

type ElementReader ¶

type ElementReader interface {
	// Constructed reports whether this ElementReader is reading a constructed or
	// primitive element.
	Constructed() bool

	// Next parses the next child element of a constructed element. If Next is
	// called for an element that uses the primitive encoding, an error is returned.
	//
	// The returned ElementReader is valid until the next call to Next(). If it is
	// not read to completion, any remaining bytes will be discarded when Next() is
	// called again. It is the responsibility of the caller to close the returned
	// ElementReader in order to validate the syntax of any remaining bytes.
	//
	// If no more elements are available, io.EOF is returned.
	Next() (Header, ElementReader, error) // only constructed

	// More reports whether the reader is in a valid state to decode more data. This
	// method does not indicate if reading the next element or byte will succeed. In
	// particular a return value of true does not guarantee that Next() or Read()
	// does not return an error. After Next() or Read() has returned an io.EOF
	// error, this method will return false.
	//
	// For primitive elements this is equivalent to Len() > 0.
	More() bool

	// Len returns the number of bytes remaining in the reader or -1 if its size is
	// unknown. Before Read(), ReadByte(), Close(), or Next() is called this returns
	// the indicated length of the element. If the element uses the indefinite
	// length encoding but a parent element uses a fixed length encoding, this
	// returns the number of remaining bytes in that parent.
	//
	// When used with constructed elements the result after calling Next() is
	// undefined until the returned element has been closed.
	Len() int

	// Close discards any remaining bytes in the reader. If a constructed format is
	// used, this will validate the BER structure of the remaining bytes. If the
	// remaining bytes are not a valid BER encoding, an error is returned.
	//
	// It is safe to call Close() multiple times, however subsequent calls may
	// return different errors or nil.
	Close() error

	io.Reader     // only primitive
	io.ByteReader // only primitive
}

ElementReader is a reader type for reading a BER-encoded element.

Elements can use the primitive or constructed encoding method. Depending on the encoding method only certain methods can be used. Reading methods of an ElementReader return io.EOF when the element is read to completion, although the underlying data source might have more bytes available. Before the element is read to completion, io.ErrUnexpectedEOF may be returned.

Closing an ElementReader is optional. Closing validates that the remaining bytes of a constructed element are valid BER-encoding.

type EncodeError ¶

type EncodeError struct {
	Value reflect.Value
	Err   error
}

EncodeError indicates that a value failed validation during encoding. Errors returned from a BerDecoder are wrapped in an EncodeError before they are returned from the Encoder.

func (e *EncodeError) Error() string

func (e *EncodeError) Unwrap() error

type Encoder ¶

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

Encoder implements encoding ASN.1 types into a BER-encoded data stream. It is the counterpart to the Decoder type.

To create a new Encoder, use the NewEncoder function.

func NewEncoder(w io.Writer) *Encoder

func (e *Encoder) Encode(val any) error

func (e *Encoder) EncodeWithParams(val any, params string) (err error)

type Flag ¶

type Flag bool

A Flag accepts any data and is set to true if present. A flag cannot be encoded into BER. In most cases a Flag should be used on an optional element.

type Header ¶

type Header struct {
	Tag         asn1.Tag
	Length      int
	Constructed bool
}

Header represents the BER header of an encoded element. The Length of an element indicates the number of bytes that make up the contents of the element. Length can also be the special value LengthIndefinite if the element uses the constructed indefinite-length encoding. In that case Constructed must also be set to true.

type InvalidDecodeError ¶

type InvalidDecodeError struct {
	Value reflect.Value
	// contains filtered or unexported fields
}

InvalidDecodeError indicates that an invalid value was passed to an Unmarshal or Decode function. The invalid value might be nested within the passed value.

func (e *InvalidDecodeError) Error() string

type RawValue ¶

type RawValue struct {
	Tag         asn1.Tag
	Constructed bool
	Bytes       []byte
}

A RawValue represents an un-decoded ASN.1 object. During decoding the syntax of structured elements is validated so the Bytes are guaranteed to contain a valid BER encoding. During encoding the bytes are written as-is without any validation.

func (rv RawValue) String() string

type Sequence ¶

type Sequence struct {
	Tag asn1.Tag // defaults to [UNIVERSAL 16]
	// contains filtered or unexported fields
}

Sequence is a type that simplifies the encoding of constructed BER elements. The zero value constitutes an empty sequence. If you want to implement a custom, constructed BerEncoder you can use a Sequence like this:

func (*myType) BerEncode() (asn1.Header, io.WriterTo, error) {
	s := &Sequence{
		Tag: asn1.Tag{asn1.ClassApplication, 15}
	}
	s.Append("A String")
	s.Append(42)
	return s.BerEncode()
}

Despite its name the Sequence type can be used to encode any constructed type, not just ASN.1 SEQUENCE types.

func SequenceOf(val any) (s *Sequence, err error)

func (s *Sequence) Append(val ...any) error

func (s *Sequence) AppendWithParams(val any, params string) error

func (s *Sequence) BerEncode() (Header, io.WriterTo, error)

type StringReader ¶

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

StringReader implements reading of BER-encoded ASN.1 string types. String types can use the primitive or constructed encoding. When using the constructed encoding strings can be arbitrarily nested. StringReader understands both types of encodings and offers a flexible interface to read arbitrary string types.

A StringReader must be created via NewStringReader.

func NewStringReader(tag asn1.Tag, r ElementReader) *StringReader

func (r *StringReader) Bytes() ([]byte, error)

func (r *StringReader) Constructed() bool

func (r *StringReader) Read(p []byte) (n int, err error)

func (r *StringReader) ReadByte() (b byte, err error)

func (r *StringReader) String() (string, error)

func (r *StringReader) Strings() iter.Seq2[ElementReader, error]

type StructuralError ¶

type StructuralError struct {
	Tag  asn1.Tag // element being decoded
	Type reflect.Type
	Err  error
}

A StructuralError suggests that the ASN.1 data is valid, but the Go type which is receiving it doesn't match or can't fit the data.

See also SyntaxError.

func (e *StructuralError) Error() string

func (e *StructuralError) Unwrap() error

type SyntaxError ¶

type SyntaxError struct {
	Tag asn1.Tag // element in which the syntax error occurred
	Err error
}

A SyntaxError suggests that the ASN.1 data is invalid. This can either indicate that the nesting of structured elements contains an error, or that a primitive element could not be decoded from its BER representation.

For errors that are not directly related to the syntax of the BER byte stream, StructuralError is a better fit.

func (e *SyntaxError) Error() string

func (e *SyntaxError) Unwrap() error

type UnsupportedTypeError ¶

type UnsupportedTypeError struct {
	Type reflect.Type
	// contains filtered or unexported fields
}

UnsupportedTypeError indicates that a value was passed to Marshal or an Encode function that cannot be encoded to BER.

func (e *UnsupportedTypeError) Error() string