objectid

package module
v0.0.6-alpha.0 Latest Latest
Warning

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

 Go to latest Published: May 28, 2023 License: MIT Imports: 7 Imported by: 1

README

go-objectid

Go Report Card GoDoc

Package objectid offers a convenient ASN.1 Object Identifier type and associated methods.

ASN.1 Object Identifiers encompass information that goes beyond their dotted representation. This tiny package merely facilitates the handling of ASN.1 NameAndNumberForm values and alternate names that may be associated with a given OID in the wild.

Uint128 Support

Unsigned 128-bit integer support for individual NumberForm values is made possible due to the private incorporation of Luke Champine's awesome Uint128 type, which manifests here through instances of the package-provided NumberForm type.

Documentation

Overview

Package objectid implements ASN.1 Object Identifier types and methods.

Features

• Unsigned 128-bit numberForm support (i.e.: such as the registrations found below {joint-iso-itu-t(2) uuid(25)})

• Flexible index support, allowing interrogation through negative indices without the risk of panic

• Convenient Leaf, Parent and Root index alias methods, wherever allowed

Uint128 Support

Unsigned 128-bit integer support for individual NumberForm values is made possible due to the private incorporation of Luke Champine's awesome Uint128 type, which manifests here through instances of the package-provided NumberForm type.

Valid NumberForm instances may fall between the minimum decimal value of zero (0) and the maximum decimal value of 340,282,366,920,938,463,463,374,607,431,768,211,455 (three hundred forty undecillion and change). This ensures no panics occur when parsing valid UUID-based object identifiers.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ASN1Notation 

type ASN1Notation []NameAndNumberForm

ASN1Notation contains an ordered sequence of NameAndNumberForm instances.

func NewASN1Notation 

func NewASN1Notation(x any) (a *ASN1Notation, err error)

NewASN1Notation returns an instance of *ASN1Notation alongside an error.

Valid input forms for ASN.1 values are string (e.g.: "{iso(1)}") and string slices (e.g.: []string{"iso(1)", "identified-organization(3)" ...}).

NumberForm values CANNOT be negative, and CANNOT overflow NumberForm (uint128).

Example 
a := `{iso(1) identified-organization(3) dod(6)}`
id, err := NewASN1Notation(a)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("Leaf node: %s", id.Leaf())

Output:

Leaf node: dod(6)

func (ASN1Notation) AncestorOf 

func (a ASN1Notation) AncestorOf(asn any) bool

AncestorOf returns a boolean value indicative of whether the receiver is an ancestor of the input value, which can be string or ASN1Notation.

Example 
asn, _ := NewASN1Notation(`{iso(1) identified-organization(3) dod(6) internet(1)}`)
child, _ := NewASN1Notation(`{iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1)}`)
fmt.Printf("%t", asn.AncestorOf(child))

Output:

true

func (ASN1Notation) Ancestry 

func (a ASN1Notation) Ancestry() (anc []ASN1Notation)

Ancestry returns slices of DotNotation values ordered from leaf node (first) to root node (last).

Empty slices of DotNotation are returned if the dotNotation value within the receiver is less than two (2) NumberForm values in length.

Example 
asn, err := NewASN1Notation(`{iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) 56521 example(999)}`)
if err != nil {
	fmt.Println(err)
}

anc := asn.Ancestry()
fmt.Printf("%s", anc[len(anc)-2])

Output:

{iso(1) identified-organization(3)}

func (ASN1Notation) Index 

func (a ASN1Notation) Index(idx int) (nanf NameAndNumberForm, ok bool)

Index returns the Nth index from the receiver, alongside a boolean value indicative of success. This method supports the use of negative indices.

func (ASN1Notation) IsZero 

func (a ASN1Notation) IsZero() bool

IsZero returns a boolean indicative of whether the receiver is unset.

func (ASN1Notation) Leaf 

func (a ASN1Notation) Leaf() NameAndNumberForm

Leaf returns the leaf node (-1) string value from the receiver.

func (ASN1Notation) Len 

func (a ASN1Notation) Len() int

Len returns the integer length of the receiver.

func (ASN1Notation) NewSubordinate 

func (a ASN1Notation) NewSubordinate(nanf any) *ASN1Notation

NewSubordinate returns a new instance of ASN1Notation based upon the contents of the receiver as well as the input NameAndNumberForm subordinate value. This creates a fully-qualified child ASN1Notation value of the receiver.

Example 
asn, err := NewASN1Notation(`{iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) 56521 example(999)}`)
if err != nil {
	fmt.Println(err)
}

fmt.Printf("%s", asn.NewSubordinate(`friedChicken(5)`))

Output:

{iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) 56521 example(999) friedChicken(5)}

func (ASN1Notation) Parent 

func (a ASN1Notation) Parent() NameAndNumberForm

Parent returns the leaf node's parent (-2) string value from the receiver.

func (ASN1Notation) Root 

func (a ASN1Notation) Root() NameAndNumberForm

Root returns the root node (0) string value from the receiver.

func (ASN1Notation) String 

func (a ASN1Notation) String() string

String is a stringer method that returns a properly formatted ASN.1 string value.

func (ASN1Notation) Valid 

func (a ASN1Notation) Valid() bool

Valid returns a boolean value indicative of whether the receiver's length is greater than or equal to one (1) slice member.

type DotNotation 

type DotNotation []NumberForm

DotNotation contains an ordered sequence of NumberForm instances.

func NewDotNotation 

func NewDotNotation(id string) (d *DotNotation, err error)

NewDotNotation returns an instance of *DotNotation alongside a boolean value indicative of success.

Example 
a := `2.25.987895962269883002155146617097157934`
id, err := NewDotNotation(a)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("dotNotation: %s", id)

Output:

dotNotation: 2.25.987895962269883002155146617097157934

func (DotNotation) AncestorOf 

func (d DotNotation) AncestorOf(dot any) bool

AncestorOf returns a boolean value indicative of whether the receiver is an ancestor of the input value, which can be string or DotNotation.

Example 
dot, _ := NewDotNotation(`1.3.6`)
child, _ := NewDotNotation(`2.1.0.1`)
fmt.Printf("%t", dot.AncestorOf(child))

Output:

false

func (DotNotation) Ancestry 

func (d DotNotation) Ancestry() (anc []DotNotation)

Ancestry returns slices of DotNotation values ordered from leaf node (first) to root node (last).

Empty slices of DotNotation are returned if the dotNotation value within the receiver is less than two (2) NumberForm values in length.

Example 
dot, err := NewDotNotation(`1.3.6.1.4.1.56521`)
if err != nil {
	fmt.Println(err)
}

anc := dot.Ancestry()
fmt.Printf("%s", anc[len(anc)-2])

Output:

1.3

func (DotNotation) Index 

func (d DotNotation) Index(idx int) (a NumberForm, ok bool)

Index returns the Nth index from the receiver, alongside a boolean value indicative of success. This method supports the use of negative indices.

func (DotNotation) IntSlice 

func (d DotNotation) IntSlice() (slice []int, err error)

IntSlice returns slices of integer values and an error. The integer values are based upon the contents of the receiver. Note that if any single arc number overflows int, a zero slice is returned.

Successful output can be cast as an instance of asn1.ObjectIdentifier, if desired.

Example 
a := `1.3.6.1.4.1.56521.999.5`
dot, _ := NewDotNotation(a)

// If needed, slice instance can be
// cast as an asn1.ObjectIdentifier.
slice, err := dot.IntSlice()
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("%v", slice)

Output:

[1 3 6 1 4 1 56521 999 5]
Example (Overflow) 
a := `2.25.987895962269883002155146617097157934`
dot, _ := NewDotNotation(a)
if _, err := dot.IntSlice(); err != nil {
	fmt.Println(err)
	return
}

Output:

strconv.Atoi: parsing "987895962269883002155146617097157934": value out of range

func (DotNotation) IsZero 

func (d DotNotation) IsZero() bool

IsZero returns a boolean indicative of whether the receiver is unset.

func (DotNotation) Leaf 

func (d DotNotation) Leaf() NumberForm

Leaf returns the leaf-node (-1) NumberForm instance.

Example 
a := `2.25.987895962269883002155146617097157934`
id, err := NewDotNotation(a)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("Leaf node: %s", id.Leaf())

Output:

Leaf node: 987895962269883002155146617097157934

func (DotNotation) Len 

func (d DotNotation) Len() int

func (DotNotation) NewSubordinate 

func (d DotNotation) NewSubordinate(nf any) *DotNotation

NewSubordinate returns a new instance of DotNotation based upon the contents of the receiver as well as the input NumberForm subordinate value. This creates a fully-qualified child DotNotation value of the receiver.

Example 
dot, err := NewDotNotation(`1.3.6.1.4.1.56521.999`)
if err != nil {
	fmt.Println(err)
}

fmt.Printf("%s", dot.NewSubordinate(5))

Output:

1.3.6.1.4.1.56521.999.5

func (DotNotation) Parent 

func (d DotNotation) Parent() NumberForm

Parent returns the leaf-node's parent (-2) NumberForm instance.

Example 
a := `2.25.987895962269883002155146617097157934`
id, err := NewDotNotation(a)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("Leaf node parent: %s", id.Parent())

Output:

Leaf node parent: 25

func (DotNotation) Root 

func (d DotNotation) Root() NumberForm

Root returns the root node (0) NumberForm instance.

Example 
a := `2.25.987895962269883002155146617097157934`
id, err := NewDotNotation(a)
if err != nil {
	fmt.Println(err)
	return
}

fmt.Printf("Root node: %s", id.Root())

Output:

Root node: 2

func (DotNotation) String 

func (d DotNotation) String() string

String is a stringer method that returns the dotNotation form of the receiver (e.g.: "1.3.6.1").

func (DotNotation) Valid 

func (d DotNotation) Valid() bool

Valid returns a boolean value indicative of the following:

• Receiver's length is greater than or equal to one (1) slice member, and ... • The first slice in the receiver contains a decimal value that is less than three (3)

type NameAndNumberForm 

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

NameAndNumberForm contains either an identifier with a parenthesis-enclosed decimal value, or a decimal value alone. An ordered sequence of instances of this type comprise an instance of ASN1Notation.

func NewNameAndNumberForm 

func NewNameAndNumberForm(x any) (nanf *NameAndNumberForm, err error)

NewNameAndNumberForm returns an instance of *NameAndNumberForm alongside an error. Valid input forms are:

• nameAndNumberForm (e.g.: "enterprise(1)"), or ...

• numberForm (e.g.: 1)

NumberForm components CANNOT be negative and CANNOT overflow NumberForm (uint128). Permitted input types are string, uint64 and (non-negative) int.

func (NameAndNumberForm) Equal 

func (nanf NameAndNumberForm) Equal(n NameAndNumberForm) bool

Equal returns a boolean value indicative of whether instance n of NameAndNumberForm matches the receiver.

func (NameAndNumberForm) Identifier 

func (nanf NameAndNumberForm) Identifier() string

Identifier returns the string-based nameForm value assigned to the receiver instance.

func (NameAndNumberForm) IsZero 

func (nanf NameAndNumberForm) IsZero() bool

IsZero returns a boolean valu indicative of whether the receiver is considered nil.

func (NameAndNumberForm) NumberForm 

func (nanf NameAndNumberForm) NumberForm() NumberForm

NumberForm returns the underlying NumberForm value assigned to the receiver instance.

func (NameAndNumberForm) String 

func (nanf NameAndNumberForm) String() (val string)

String is a stringer method that returns the properly formatted NameAndNumberForm string value.

type NumberForm 

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

NumberForm is an unsigned 128-bit number. This type is based on github.com/lukechampine/uint128. It has been incorporated into this package to produce unsigned 128-bit OID numberForm support (i.e.: UUID-based OIDs).

func NewNumberForm 

func NewNumberForm(v any) (a NumberForm, err error)

NewNumberForm converts v into an instance of NumberForm, which is returned alongside an error.

Acceptable input types are string, int and uint64. No decimal value, whether string or int, can ever be negative.

Example 
// single UUID integer parse example
arc, err := NewNumberForm(`987895962269883002155146617097157934`)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("%s\n", arc)

Output:

987895962269883002155146617097157934

func (NumberForm) Equal 

func (a NumberForm) Equal(n any) bool

Equal returns a boolean value indicative of whether the receiver is equal to the value provided. Valid input types are string, uint64, int and NumberForm.

Any input that represents a negative number guarantees a false return.

func (NumberForm) Gt 

func (a NumberForm) Gt(n any) bool

Gt returns a boolean value indicative of whether the receiver is greater than the value provided. Valid input types are string, uint64, int and NumberForm.

Any input that represents a negative number guarantees a false return.

func (NumberForm) IsZero 

func (a NumberForm) IsZero() bool

isZero returns true if a == 0.

func (NumberForm) Lt 

func (a NumberForm) Lt(n any) bool

Lt returns a boolean value indicative of whether the receiver is less than the value provided. Valid input types are string, uint64, int and NumberForm.

Any input that represents a negative number guarantees a false return.

func (*NumberForm) Scan 

func (a *NumberForm) Scan(s fmt.ScanState, ch rune) error

Scan implements fmt.Scanner, and is only present to allow conversion of an NumberForm into a string value per fmt.Sscan. Users need not execute this method directly.

func (NumberForm) String 

func (a NumberForm) String() string

String returns the base-10 representation of a as a string.

func (NumberForm) Valid 

func (a NumberForm) Valid() bool

Valid returns a boolean valud indicative of proper instantiation.

type OID 

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

OID contains an underlying ASN1Notation value, and extends convenient methods allowing interrogation and verification.

func NewOID 

func NewOID(x any) (o *OID, err error)

NewOID creates an instance of OID and returns it alongside an error.

The correct raw input syntax is the ASN.1 NameAndNumberForm sequence syntax, i.e.: 

{iso(1) identified-organization(3) dod(6)}

Not all NameAndNumberForm values (arcs) require actual names; they can be numbers alone or in the so-called nameAndNumber syntax (name(Number)). For example: 

{iso(1) identified-organization(3) 6}

... is perfectly valid, but generally NOT recommended when clarity or precision is desired.

Example 
// UUID-based (uint128) OID example
a := `{joint-iso-itu-t(2) uuid(25) ans(987895962269883002155146617097157934)}`
id, err := NewOID(a)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("ASN.1 Notation: %s", id.ASN())

Output:

ASN.1 Notation: {joint-iso-itu-t(2) uuid(25) ans(987895962269883002155146617097157934)}

func (OID) ASN 

func (id OID) ASN() ASN1Notation

ASN returns the underlying ASN1Notation instance found within the receiver.

func (OID) Dot 

func (id OID) Dot() DotNotation

Dot returns a DotNotation instance based on the contents of the underlying ASN1Notation instance found within the receiver.

func (OID) IsZero 

func (id OID) IsZero() (is bool)

IsZero checks the receiver for nilness and returns a boolean indicative of the result.

func (OID) Leaf 

func (id OID) Leaf() (nanf NameAndNumberForm)

Leaf returns the leaf-node instance of NameAndNumberForm.

Example 
a := `{joint-iso-itu-t(2) uuid(25) ans(987895962269883002155146617097157934)}`
id, err := NewOID(a)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("Leaf node: %s", id.Leaf())

Output:

Leaf node: ans(987895962269883002155146617097157934)

func (OID) Len 

func (id OID) Len() (i int)

Len returns the integer length of all underlying NumberForm values present within the receiver.

func (OID) Parent 

func (id OID) Parent() (nanf NameAndNumberForm)

Parent returns the leaf-node's Parent instance of NameAndNumberForm.

Example 
a := `{joint-iso-itu-t(2) uuid(25) ans(987895962269883002155146617097157934)}`
id, err := NewOID(a)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("Leaf node parent: %s", id.Parent())

Output:

Leaf node parent: uuid(25)

func (OID) Root 

func (id OID) Root() (nanf NameAndNumberForm)

Root returns the root node instance of NameAndNumberForm.

Example 
a := `{joint-iso-itu-t(2) uuid(25) ans(987895962269883002155146617097157934)}`
id, err := NewOID(a)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("Root node: %s", id.Root())

Output:

Root node: joint-iso-itu-t(2)

func (OID) Valid 

func (id OID) Valid() bool

Valid returns a boolean value indicative of whether the receiver's state is considered value.

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.