deb822

README

deb822

A Go SerDes library for Debian deb822 encoding.

Credits

This library was originally based on the work of the go-debian library by Paul Tagliamonte but has since been heavily modified and extended.

Documentation

Index

• func Marshal(writer io.Writer, data any) error
• func Unmarshal(data []byte, v any) error
• type Decoder
  • func NewDecoder(reader io.Reader, keyring openpgp.EntityList) (*Decoder, error)
  • func (d *Decoder) Decode(v any) error
  • func (d *Decoder) Signer() *openpgp.Entity
• type Encoder
  • func NewEncoder(writer io.Writer, privateKey *openpgp.Entity) (*Encoder, error)
  • func (e *Encoder) Close() error
  • func (e *Encoder) Encode(incoming interface{}) error
• type Stanza
  • func (p Stanza) MarshalJSON() ([]byte, error)
  • func (p *Stanza) Set(key, value string)
  • func (p *Stanza) UnmarshalJSON(data []byte) error
  • func (p *Stanza) WriteTo(w io.Writer) (total int64, err error)
• type StanzaReader
  • func NewStanzaReader(reader io.Reader, keyring openpgp.EntityList) (*StanzaReader, error)
  • func (pr *StanzaReader) All() ([]Stanza, error)
  • func (pr *StanzaReader) Next() (*Stanza, error)
  • func (pr *StanzaReader) Signer() *openpgp.Entity

Functions

func Marshal

func Marshal(writer io.Writer, data any) error

Marshal is a one-off interface to serialize a single object to a writer.

Most notably, this will *not* separate stanzas with a newline as is expected upon repeated calls, please use the Encoder streaming interface for that.

Given a struct (or list of structs), write to the io.Writer stream in the RFC822-alike Debian control-file format

func Unmarshal

func Unmarshal(data []byte, v any) error

Types

type Decoder

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

func NewDecoder

func NewDecoder(reader io.Reader, keyring openpgp.EntityList) (*Decoder, error)

func (*Decoder) Decode

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

func (*Decoder) Signer

func (d *Decoder) Signer() *openpgp.Entity

Return the Entity (if one exists) that signed this set of stanzas.

type Encoder

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

Encoder is a struct that allows for the streaming Encoding of data back out to an `io.Writer`. Most notably, this will separate subsequent `Encode` calls of a Struct with a newline.

Given a struct (or list of structs), write to the io.Writer stream in the RFC822-alike Debian control-file format

In order to Marshal a custom Struct, you are required to implement the Marshallable interface. It's highly encouraged to put this interface on the struct without a pointer receiver, so that pass-by-value works when you call Marshal.

func NewEncoder

func NewEncoder(writer io.Writer, privateKey *openpgp.Entity) (*Encoder, error)

Create a new Encoder, which is configured to write to the given `io.Writer`. Optionally, you can pass in a private key to sign the output with.

func (*Encoder) Close

func (e *Encoder) Close() error

Close the Encoder, flushing the buffer and closing the underlying io.Writer.

func (*Encoder) Encode

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

Take a Struct, Encode it into a stanza, and write that out to the io.Writer set up when the Encoder was configured.

type Stanza

type Stanza struct {
	Values map[string]string
	Order  []string
}

A Stanza is a block of RFC2822-like key value pairs. This struct contains two methods to fetch values, a Map called Values, and a Slice called Order, which maintains the ordering as defined in the RFC2822-like block

func (Stanza) MarshalJSON

func (p Stanza) MarshalJSON() ([]byte, error)

MarshalJSON ensures the keys are marshaled in the order specified by Order

func (*Stanza) Set

func (p *Stanza) Set(key, value string)

func (*Stanza) UnmarshalJSON

func (p *Stanza) UnmarshalJSON(data []byte) error

UnmarshalJSON ensures the keys are unmarshaled and ordered as they appear in the JSON object

func (*Stanza) WriteTo

func (p *Stanza) WriteTo(w io.Writer) (total int64, err error)

type StanzaReader

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

Wrapper to allow iteration on a set of stanzas without consuming them all into memory at one time. This is also the level in which data is signed, so information such as the entity that signed these documents can be read by calling the `.Signer` method on this struct. The next unread stanza can be returned by calling the `.Next` method on this struct.

func NewStanzaReader

func NewStanzaReader(reader io.Reader, keyring openpgp.EntityList) (*StanzaReader, error)

Create a new StanzaReader from the given `io.Reader`, and `keyring`. if `keyring` is set to `nil`, this will result in all OpenPGP signature checking being disabled. *including* that the contents match!

Also keep in mind, `reader` may be consumed 100% in memory due to the underlying OpenPGP API being hella fiddly.

func (*StanzaReader) All

func (pr *StanzaReader) All() ([]Stanza, error)

func (*StanzaReader) Next

func (pr *StanzaReader) Next() (*Stanza, error)

Consume the io.Reader and return the next parsed stanza, modulo garbage lines causing us to return an error.

func (*StanzaReader) Signer

func (pr *StanzaReader) Signer() *openpgp.Entity

Return the Entity (if one exists) that signed this set of stanzas.