asn1int

README

go-asn1int

Basic ASN.1 INTEGER implementation for Go, free of magnitude limits.

func main() {
	// INITIALIZE NEW INTEGER INSTANCE
        m, err := New(58986943) // can also init using string, [u]int64, *big.Int
        if err != nil {
                return
        }

	// MARSHAL TO ASN.1 BYTES
        var asn1Bytes []byte
	if asn1Bytes, err = m.Marshal(); err != nil {
		return
	}

        fmt.Printf("%v", asn1Bytes)
        // Output: [48 6 2 4 3 132 17 191]

	// UNMARSHAL ASN.1 BYTES BACK TO INTEGER
	var ui INTEGER
	if err = ui.Unmarshal(asn1Bytes); err != nil {
		return
	}

	fmt.Printf("%s", ui)
	// Output: 58986943
}

Documentation

Overview

Package asn1int uses math/big to implement the ASN.1 INTEGER type.

For user convenience, a small number of useful features have been added. See the documentation below, along with individual examples. Many of these features manifest as methods which may be executed ad hoc or in fluent-form.

License

This package is released under the terms of the MIT license. A copy of the license may be found in the package repository.

Reference

See ITU-T Rec. X.680 for further details on the ASN.1 INTEGER type.

Magnitude Considerations

By default, this package will not -- in ANY way -- impose limits regarding the magnitude of a value.

Handling of extremely large numbers -- whether signed or unsigned -- may consume an undesirable amount of resources. En masse, this may impact the stability of the platform upon which this code operates.

Consider this problem in the face of directory services which leverage this type -- if a DSA is exposed to a particularly large and/or hostile user base, it may be wise to impose minimum and maximum bounds upon any new INTEGER instances, thus disallowing absurdly large numbers from being written to the directory. A suitable bounding value might be:

(+/-) 99999999999999999999999999999999999999999999999999999999999999 ( 62*'9' )

Overflow issues may also arise in a scenario in which directory servers of differing implementations and/or platforms are replicating DIT content between each other. If one system disallows values greater than a particular magnitude, it is important the replication agreements (and more to the point, the systems themselves) are hardened enough to mitigate this issue.

Index

• type INTEGER
  • func New(x any) (i INTEGER, err error)
  • func (r *INTEGER) Add(x any) *INTEGER
  • func (r INTEGER) Eq(x any) bool
  • func (r INTEGER) Gt(x any) bool
  • func (r INTEGER) Lt(x any) bool
  • func (r INTEGER) Marshal() (b []uint8, err error)
  • func (r INTEGER) Negative() bool
  • func (r INTEGER) String() string
  • func (r *INTEGER) Sub(x any) *INTEGER
  • func (r *INTEGER) Unmarshal(b []uint8) (err error)

Examples

• INTEGER.Add
• INTEGER.Eq
• INTEGER.Gt
• INTEGER.Lt
• INTEGER.Negative
• INTEGER.Sub
• New
• New (BigInt)

Types

type INTEGER

type INTEGER struct {
	*big.Int // required (actual ASN.1 INTEGER)
}

INTEGER implements the ASN.1 INTEGER type, defined in ITU-T Rec. X.680.

func New

func New(x any) (i INTEGER, err error)

New initializes and returns a new instance of INTEGER alongside an error.

The input value (x) may be any of the following:

• INTEGER
• *big.Int
• int, int64, uint64
• string

Example

This example demonstrates the creation of an ASN.1 INTEGER instance.

m, err := New(58986943) // can also init using string, [u]int64, *big.Int
if err != nil {
	return
}
fmt.Printf("%s", m)

Output:

58986943

Example (BigInt)

var bi *big.Int = new(big.Int)
bi.SetString(`123456`, 10)

m, err := New(bi)
if err != nil {
	return
}

fmt.Printf("%s", m)

Output:

123456

func (*INTEGER) Add

func (r *INTEGER) Add(x any) *INTEGER

Add calls big.Int.Add to both set and return the value of r+x.

Example

This example demonstrates using addition upon an ASN.1 INTEGER instance using a string value.

value := "58986943"
m, err := New(value)
if err != nil {
	return
}
m.Add(value)

fmt.Printf("%s", m)

Output:

117973886

func (INTEGER) Eq

func (r INTEGER) Eq(x any) bool

Eq returns a Boolean value which reflects the evaluation of r==x.

Example

This example demonstrates using subtraction upon an ASN.1 INTEGER instance using an int64 value.

value := 58986943
m, err := New(int64(value))
if err != nil {
	return
}

fmt.Printf("%t", m.Eq(value-1))

Output:

false

func (INTEGER) Gt

func (r INTEGER) Gt(x any) bool

Gt returns a Boolean value which reflects the evaluation of r>x.

Example

This example demonstrates using subtraction upon an ASN.1 INTEGER instance using another INTEGER value.

value, err := New(58986943)
if err != nil {
	return
}

var m INTEGER
if m, err = New(value); err != nil {
	return
}
value.Sub(50)

fmt.Printf("%t", m.Gt(value))

Output:

true

func (INTEGER) Lt

func (r INTEGER) Lt(x any) bool

Lt returns a Boolean value which reflects the evaluation of r<x.

Example

This example demonstrates using subtraction upon an ASN.1 INTEGER instance using an int value.

value := 58986943
m, err := New(value)
if err != nil {
	return
}

fmt.Printf("%t", m.Lt(value+50))

Output:

true

func (INTEGER) Marshal

func (r INTEGER) Marshal() (b []uint8, err error)

Marshal executes asn1.Marshal upon the receiver instance, returning the ASN.1 marshaled bytes alongside an error.

func (INTEGER) Negative

func (r INTEGER) Negative() bool

Negative returns a Boolean value which reflects the evaluation of r<0.

Example

This example demonstrates use of the Negative method to identify a negative value.

i, err := New(-12646758)
if err != nil {
	return
}

fmt.Printf("%s is negative: %t", i, i.Negative())

Output:

-12646758 is negative: true

func (INTEGER) String

func (r INTEGER) String() string

String is a stringer method that returns the string representation of the receiver.

func (*INTEGER) Sub

func (r *INTEGER) Sub(x any) *INTEGER

Sub calls big.Int.Sub to both set and return the value of r-x.

Example

This example demonstrates using subtraction upon an ASN.1 INTEGER instance using a uint64 value.

value := 58986943
m, err := New(uint64(value))
if err != nil {
	return
}
m.Sub(value + 1)

fmt.Printf("%s", m)

Output:

-1

func (*INTEGER) Unmarshal

func (r *INTEGER) Unmarshal(b []uint8) (err error)

Unmarshal executes asn1.Unmarshal upon the provided bytes (b), writing the unmarshaled ASN.1 content to the receiver (r) and returning an error.