asn1

asn1 is a pure V Language module for X.690 Abstract Syntax Notation One (ASN.1) Distinguished Encoding Rules (DER) encoding and decoding.

This module provides you with the ability to generate and parse ASN.1 encoded data. More precisely, it provides you with the ability to generate and parse data encoded with ASN.1’s DER (Distinguished Encoding Rules) encoding. It does not support other than DER.

[!CAUTION] > This module is marked as an experimental, so its subject to change (possibly rapidly). > Use with caution, submit bugs when found, and please gives feedback.

Supported ASN.1 Type

Currently supports the following basic ASN1 types:

• Boolean
• BitString
• Integer (through int, i64, and math.big.Integer)
• ObjectIdentifier
• NumericString
• Null
• Enumerated
• IA5String (ascii string)
• OctetString
• PrintableString
• UTF8String
• UTCTime
• GeneralizedTime
• VisibleString
• Sequence,
• SequenceOf
• Set
• SetOf

Features

• Supports most basic ASN.1 tag types.
• Supports single and multi-byte (high form) tag formats for tag number > 31.
• Serializing and deserializing of ASN.1 objcet to bytes and vice versa.

Code Examples

Here are some simple usage examples.

import x.encoding.asn1

fn main() {
    value := asn1.Integer.from_int(32)

    output := asn1.encode(value)!
    assert output == [u8(0x02), 0x01, 0x20]

    // you can encode (serialize) with string options
    output2 := asn1.encode_with_options(value, 'context_specific:5;explicit;inner:2')!
    assert output2 == [u8(0xa5), 0x03, 0x02, 0x01, 0x20]

    // You can decode (deserialize) back the bytes into Element.
    el := asn1.decode_with_options([u8(0xa5), 0x03, 0x02, 0x01, 0x20], 'context_specific:5;explicit;inner:2')!

    // el is an Element, turn it into underlying object
    int_el := el.into_object[asn1.Integer]()!

    int_el_value := int_el.as_i64()!
    assert int_el_value == 32
}

See more complete examples in the examples directory.

Documentation

See the documentation for more detailed information on how to use functionality in this module.

License

This project is licensed under the MIT License (see LICENSE file)

fn decode(bytes []u8) !Element

decode decodes single element from bytes, its not allowing trailing data.

Examples:

Original object was Utf8String with tag == 12 (0c)

import x.encoding.asn1

original_obj := asn1.Utf8String.new('hi')!
bytes_data := [u8(0x0C), 0x02, 0x68, 0x69]
decoded_obj := asn1.decode(bytes_data)!
assert decoded_obj.equal(original_obj)

fn decode_with_field_options(bytes []u8, fo FieldOptions) !Element

decode_with_field_options is similar to decode_with_options, but its more controllable through FieldOptions.

fn decode_with_options(bytes []u8, opt string) !Element

decode_with_options decodes single element from bytes with options support, its not allowing trailing data. Its accepts options string to drive decoding process.

Examples:

UTF8String with implicit tagging definded as [5] IMPLICIT UTF8String was encoded into 85 02 68 69

original_obj := asn1.Utf8String.new('hi')!
implicit_bytes := [u8(0x85), 0x02, 0x68, 0x69]
obj_2 := asn1.decode_with_options(implicit_bytes, 'context_specific:5;implicit;inner:12')!

assert obj_2.equal(original_obj)
dump(obj_2) // Output: obj_2: asn1.Element(Utf8String: (hi))

UTF8String with explicit tagging defined as [5] EXPLICIT UTF8String was encoded into A5 04 0C 02 68 69

explicit_bytes := [u8(0xA5), 0x04, 0x0C, 0x02, 0x68, 0x69]
obj_3 := asn1.decode_with_options(explicit_bytes, 'context_specific:5;explicit;inner:0x0c')!

assert obj_3.equal(original_obj)
dump(obj_3) // output: obj_3: asn1.Element(Utf8String: (hi))

fn encode(el Element) ![]u8

encode serializes element into bytes array. By default, its encode in .der rule with empty options. See encode_with_options if you want pass an option string. See field.v for more option in detail.

Examples:

import x.encoding.asn1

obj := asn1.Utf8String.new('hi')!
out := asn1.encode(obj)!
assert out == [u8(0x0C), 0x02, 0x68, 0x69]

fn encode_with_field_options(el Element, fo FieldOptions) ![]u8

encode_with_field_options serializes this element into bytes array with options defined in fo.

fn encode_with_options(el Element, opt string) ![]u8

encode_with_options serializes element into bytes array with options string passed to drive the result.

Examples:

Utf8String defined as [5] IMPLICIT UTF8String was encoded into 85 02 68 69. Utf8String defined as [5] EXPLICIT UTF8String was encoded into A5 04 0C 02 68 69.

obj := asn1.Utf8String.new('hi')!
implicit_out := asn1.encode_with_options(obj, 'context_specific:5;implicit;inner:12')!
assert implicit_out == [u8(0x85), 0x02, 0x68, 0x69]

explicit_out := asn1.encode_with_options(obj, 'context_specific:5;explicit;inner:0x0c')!
assert explicit_out == [u8(0xA5), 0x04, 0x0C, 0x02, 0x68, 0x69]

fn encoded_len(el Element) int

encoded_len calculates the size in bytes when the el element was serialized.

fn make_payload[T](val T, kd KeyDefault) ![]u8

make_payload builds bytes of payload for some structures contains field of Elements. Consider this examples from RFC 5280 defines schema.

 Certificate  ::=  SEQUENCE  {
    tbsCertificate       TBSCertificate,
    signatureAlgorithm   AlgorithmIdentifier,
    signatureValue       BIT STRING  }

where your structure defined as:.

struct Certificate {
        tbs_certificate 	TBSCertificate
        signature_algorithm	AlgorithmIdentifier
        signature_value		BitString
}

Usually you can do.

cert := Certificate.new()!
payload := asn1.make_payload[Certificate](cert)!

and then you can use the produced payload.

BUG: there are some issues would you encounter when your T contains fields that have generic in it, its would produce unexpected result, see detail bug on: https://github.com/vlang/v/issues/22721. So, just use this when your T.fields is not contains generic within it. UPDATED: This issue has been fixed in this PR #22724 Thanks to @felipensp

fn new_key_default() KeyDefault

new_key_default creates empty KeyDefault maps.

fn AnyDefinedBy.new(params Element) AnyDefinedBy

AnyDefinedBy.new creates a new ANY DEFINED BY element.

fn ApplicationElement.from_element(inner Element, tagnum int, mode TaggedMode) !ApplicationElement

from_element creates application class element from some element.

fn ApplicationElement.new(tag Tag, content []u8) !ApplicationElement

new creates a new application class element.

fn BitString.from_binary_string(s string) !BitString

from_binary_string creates a new BitString from binary bits arrays in s, ie, arrays of 1 and 0. If s.len is not a multiple of 8, it will contain non-null pad, otherwise, the pad is null. The bit string '011010001' will need two content octets: 01101000 10000000 (hexadecimal 68 80); seven bits of the last octet are not used and is interpreted as a pad value.

import x.encoding.asn1

bs := asn1.BitString.from_binary_string('011010001')!
	assert (bs.pad == 7 && bs.data == [u8(0x68), 0x80]) == true

fn BitString.new(s string) !BitString

new creates a new BitString from regular string s.

fn Boolean.new(value bool) Boolean

new creates a new Boolean value from true or false value. By default, when you pass true, its would store 0xff as underlying byte value. If you want more to be relaxed, see from_u8 to creates with another byte value.

fn Boolean.parse(mut p Parser) !Boolean

parse tries to read a Boolean type from parser or return error on fails

fn Choice.new(el Element, choices []Element) !Choice

new creates a new choice element. It accepts el as a choosen element and choices as a source of possible choices list.

fn ContextElement.explicit_context(inner Element, tagnum int) !ContextElement

explicit_context creates a new ContextElement with explicit mode.

fn ContextElement.from_element(inner Element, tagnum int, mode TaggedMode) !ContextElement

from_element creates a new tagged type of ContextElement from some element in inner.

fn ContextElement.implicit_context(inner Element, tagnum int) !ContextElement

implicit_context creates new ContextElement with implicit mode.

fn ContextElement.new(tag Tag, content []u8) !ContextElement

new creates a raw context specific element. Use ContextElement.from_element instead if your context specific element is wrapper of another element.

fn Element.from_object[T](t T) !Element

from_object[T] transforms and creates a new Element from generic type (maybe universal type, like an OctetString). Its accepts generic element t that you should pass to this function. You should make sure if this element implements required methods of the Element, or an error would be returned.

Fixme: its not tested. Examples:

oc := asn1.OctetString.new('xxx')!
el := asn1.Element.from_object[OctetString](oc)!

and then treats your OctetString as an Element

fn ElementList.from_bytes(src []u8) ![]Element

ElementList.from_bytes parses bytes in src as series of Element or return error on fails. Its does not support trailing data.

fn Enumerated.new(val int) Enumerated

new creates a new Enumerated from int value.

fn FieldOptions.from_attrs(attrs []string) !FieldOptions

from_attrs parses and validates []string into FieldOptions.

fn FieldOptions.from_string(s string) !FieldOptions

from_string parses string as an attribute of field options. Its allows string similar to application:4; optional; has_default to be treated as an field options. See FieldOptions in field_options.v for more detail.

fn GeneralString.new(s string) !GeneralString

new creates a GeneralString element from string s.

fn GeneralizedTime.from_time(t time.Time) !GeneralizedTime

from_time creates GeneralizedTime element from standard time.Time (as an UTC time).

fn GeneralizedTime.new(s string) !GeneralizedTime

GeneralizedTime.new creates a new GeneralizedTime from string s

fn IA5String.new(s string) !IA5String

new creates a IA5String element from string s.

fn Integer.from_bigint(b big.Integer) Integer

from_bigint creates a new ASN.1 Integer from big.Integer b

fn Integer.from_hex(x string) !Integer

from_hex creates a new ASN.1 Integer from hex string in x where x is a valid hex string without 0x prefix. If your string value is below max_i64, use from_i64 instead

fn Integer.from_i64(v i64) Integer

from_i64 creates new a ASN.1 Integer from i64 v.

fn Integer.from_int(v int) Integer

from_int creates a new ASN.1 Integer from int v.

fn Integer.from_string(s string) !Integer

from_string creates a new ASN.1 Integer from decimal string s. If your string value is below max_i64, use from_i64 instead

fn Length.from_bytes(bytes []u8) !(Length, []u8)

Length.from_bytes tries to read length from bytes array and return the length and the rest of remaining bytes on success, or error on fails.

fn Length.new(v int) !Length

new creates Length from integer value. Passing negative value (<0) for length is not make a sense, so just return error instead if it happen.

fn NumericString.new(s string) !NumericString

new creates a new NumericString element from string s.

fn ObjectIdentifier.from_ints(src []int) !ObjectIdentifier

from_ints creates a new ObjectIdentifier type from arrays of int.

fn ObjectIdentifier.new(s string) !ObjectIdentifier

new creates a new ObjectIdentifier type from dots (.) separated string.

fn OctetString.from_hexstring(hs string) !OctetString

from_hexstring creates a new OctetString element from valid hex string or error on fails.

fn OctetString.new(s string) !OctetString

new creates a new OctetString element from string s.

fn Optional.new(el Element, with_present bool) !Optional

new creates and marked element as an Optional element.

fn Parser.new(data []u8) &Parser

new creates a new Parser from bytes array in data.

fn PrintableString.new(s string) !PrintableString

new creates new PrintableString element from string s.

fn PrivateELement.from_element(inner Element, tagnum int, mode TaggedMode) !PrivateELement

from_element creates a new private class element from another element.

fn PrivateELement.new(tag Tag, content []u8) !PrivateELement

new creates a raw private class element.

fn RawElement.from_element(el Element, cls TagClass, tagnum int, mode TaggedMode) !RawElement

from_element creates a RawElement from another element (with wrapping semantic).

fn RawElement.new(tag Tag, content []u8) !RawElement

new creates a RawElement from tag and content. If your element is universal class, use universal type constructor instead, provided in this module.

fn Sequence.from_list(els []Element) !Sequence

from_list creates new Sequence from list of elements.

fn Sequence.new() !Sequence

new creates new Sequence with default size.

fn SequenceOf.from_list[T](els []T) !SequenceOf[T]

SequenceOf.from_list creates a new SequenceOf[T] from arrays of T type.

fn SequenceOf.new[T]() SequenceOf[T]

SequenceOf.new creates a new SequenceOf[T]

fn Set.from_list(els []Element) !Set

from_list creates a new Set from arrays of element in els.

fn Set.new() !Set

creates a new Set with default size.

fn SetOf.from_list[T](els []T) !SetOf[T]

from_list creates new SetOf type T from arrays of T.

fn SetOf.new[T]() !SetOf[T]

new creates an empty SetOf type T.

fn Tag.from_bytes(bytes []u8) !(Tag, []u8)

Tag.from_bytes creates a new Tag from bytes. Its return newly created tag and the rest of remaining bytes on success, or error on failures.

fn Tag.new(cls TagClass, constructed bool, number int) !Tag

Tag.new creates new ASN.1 tag identifier. Its accepts params of TagClass cls, the tag form in the constructed or primitive form in constructed flag, and the integer tag number.

fn UtcTime.from_time(t time.Time) !UtcTime

from_time creates a new UtcTime element from standard time.Time in UTC time format.

fn UtcTime.new(s string) !UtcTime

new_utctime creates a new UtcTime element from string s.

fn Utf8String.from_bytes(src []u8) !Utf8String

from_bytes creates a new Utf8String element from bytes in src.

fn Utf8String.new(s string) !Utf8String

new creates a new Utf8String element from string s.

fn VisibleString.new(s string) !VisibleString

from_string creates a new VisibleString from string s.

interface Element {
	// tag tells the ASN.1 identity of this Element.
	tag() Tag
	// payload tells the payload (values) of this Element.
	// The element's size was calculated implicitly from payload.len
	// Its depends on the tag how interpretes this payload.
	payload() ![]u8
}

Element represents a generic ASN.1 Element. Most of the standard Universal class element defined on this module satisfies this interface. This interface was also expanded by methods defined on this interface.

fn (el Element) encoded_len() int

encoded_len calculates the length of bytes when this element was serialized.

fn (el Element) equal(other Element) bool

equal checks whether this two element equal and holds the same tag and content

fn (el Element) into_object[T]() !T

into_object[T] transforms and tries to cast element el into generic object T if the element not holding object T, it would return error.

Note: Not tested. Examples:

oc := asn1.OctetString.new('xxx')!
el := asn1.Element.from_object[OctetString](oc)!

cast back the element into OctetString.

os := el.into_object[OctetString]()!

and then treats os as an OctetString.

fn (el Element) length() !int

length tells the payload length of this element.

fn (el Element) set_default_value(mut fo FieldOptions, value Element) !

set_default_value installs default value within FieldOptions for the element

fn (el Element) unwrap_with_field_options(fo FieldOptions) !Element

unwrap_with_field_options performs unwrapping operations with FieldOptions.

fn (el Element) unwrap_with_options(opt string) !Element

unwrap_with_options performs unwrapping operations to the element with options provided. Its technically reverse operation of the .wrap() applied to the element with the same options. If you provide with diferent options, the result is in undesired behaviour, even its success

type ElementList = []Element

ElementList.

ElementList is arrays of Element. Many places maybe required this wells, likes Sequence or Set fields.

fn (els ElementList) payload() ![]u8

payload produces bytes array from arays of Element.

fn (els ElementList) encoded_len() int

encoded_len tells the length of bytes when the ElementList was serialized.

type KeyDefault = map[string]Element

KeyDefault is map of string (field.name) into Element for element with default semantic. its is to be used for building payload of complex structures like sequence. see make_payload below.

type Length = int

ASN.1 length handling routines.

The standard of X.690 ITU document defines two length types - definite and indefinite. In DER encoding only uses the definite length. The length field must be encoded in the minimum number of octets. There are two forms of definite length octets: short (for lengths value between 0 and 127), and long definite (for lengths value between 0 and 2^1008 -1). In short form contains one octet. Bit 8 has value "0" and bits 7-1 give the length (length value from 0 to 127) In long form, its required two or more octets, limited to 127 octets. Bit 8 of first octet has value "1" and bits 7-1 gives the number of additional length octets. Second and following octets give the length, base 256, most significant digit first.

This module only support definite length, in short or long form. Its required for DER encoding the length octets should be in definite length.

Length represent ASN.1 length value

fn (v Length) encode(mut dst []u8) !

encode serializes the length v into bytes array stored into buffer buf in .der rule.

fn (so SequenceOf[T]) tag() Tag

The tag of SequenceOf element.

fn (so SequenceOf[T]) payload() ![]u8

The payload of SequenceOf element.

fn (so SequenceOf[T]) fields() []T

fields returns underlying arrays of T from the SequenceOf[T].

fn (so SetOf[T]) tag() Tag

tag returns the tag of SetOf[T] element.

fn (so SetOf[T]) fields() []T

fields returns underlying arrays of T from the SetOf[T].

fn (so SetOf[T]) payload() ![]u8

payload returns the payload of SetOf[T] element.

fn (mut so SetOf[T]) add_element(el Element) !

add_element adds an element el into SetOf[T] fields.

enum EncodingRule {
	// Distinguished Encoding Rules (DER)
	der = 0
	// Basic Encoding Rules (BER)
	ber = 1
	// Octet Encoding Rules (OER)
	oer = 2
	// Packed Encoding Rules (PER)
	per = 3
	// XML Encoding Rules (XER)
	xer = 4
}

EncodingRule is standard of rule thats drives how some ASN.1 element was encoded or deserialized.

enum TagClass {
	universal        = 0x00 // 0b00
	application      = 0x01 // 0b01
	context_specific = 0x02 // 0b10
	private          = 0x03 // 0b11
}

TagClass is an enum of ASN.1 tag class.

To make sure ASN.1 encodings are not ambiguous, every ASN.1 type is associated with a tag. A tag consists of three parts: the tag class, tag form and the tag number. The following classes are defined in the ASN.1 standard.

enum TagType {
	// vfmt off
	reserved 			= 0 	// reserved for BER
	boolean 			= 1 	// BOOLEAN type
	integer 			= 2 	// INTEGER type
	bitstring 			= 3 	// BIT STRING
	octetstring 		= 4 	// OCTET STRING
	null 				= 5 	// NULL
	oid 				= 6		// OBJECT IDENTIFIER
	objdesc 			= 7 	// OBJECT DESCRIPTOR
	external 			= 8 	// INSTANCE OF, EXTERNAL
	real 				= 9 	// REAL
	enumerated 			= 10 	// ENUMERATED
	embedded 			= 11 	// EMBEDDED PDV
	utf8string 			= 12 	// UTF8STRING
	relativeoid 		= 13 	// RELATIVE-OID
	// deprecated
	time 				= 14
	// 0x0f is reserved
	sequence 			= 16 	// SEQUENCE, SEQUENCE OF, Constructed
	set 				= 17 	// SET, SET OF, Constructed
	numericstring 		= 18 	// NUMERICSTRING
	printablestring 	= 19 	// PRINTABLESTRING
	t61string 			= 20 	// TELETEXSTRING, T61STRING
	videotexstring 		= 21 	// VIDEOTEXSTRING
	ia5string 			= 22 	// IA5STRING
	utctime 			= 23 	// UTCTIME
	generalizedtime 	= 24 	// GENERALIZEDTIME
	graphicstring 		= 25 	// GRAPHICSTRING
	visiblestring 		= 26 	// VISIBLESTRING, ISO646STRING
	generalstring 		= 27 	// GENERALSTRING
	universalstring 	= 28 	// UNIVERSALSTRING
	characterstring 	= 29 	// CHARACTER STRING
	bmpstring   		= 30 	// BMPSTRING
	// unsupported 
	date        		= 0x1f
	time_of_day 		= 0x20
	date_time   		= 0x21
	duration    		= 0x22
	// Internationalized OID
	i18_oid 			= 0x23
	// Internationalized Relative OID
	// Reserved 0x25 and above
	relative_i18_oid 	= 0x24
	// vfmt on
}

TagType is standard UNIVERSAL tag number. Some of them was deprecated, so its not going to be supported on this module.

enum TaggedMode {
	explicit
	implicit
}

EXPLICIT and IMPLICIT MODE

TaggedMode is way of rule how some element is being wrapped (unwrapped). Explicit rule add new (outer) tag to the existing element, where implicit rule replaces the tag of existing element.

struct AnyDefinedBy {
pub:
	// default to null element
	params Element = Null{}
}

ANY DEFINED BY

fn (a AnyDefinedBy) tag() Tag

tag returns the underlying tag of ANY DEFINED BY element.

fn (a AnyDefinedBy) payload() ![]u8

payload returns the underlying payload of ANY DEFINED BY element.

struct ApplicationElement {
	RawElement
}

Limited support for APPLICATION CLASS Element.

fn (app ApplicationElement) tag() Tag

tag returns the tag of the application class element.

fn (app ApplicationElement) payload() ![]u8

payload returns the payload of application class element.

struct BitString {
mut:
	data []u8
	pad  u8 // numbers of unused bits
}

ASN.1 UNIVERSAL CLASS OF BITSTRING TYPE.

The BIT STRING type denotes an arbitrary string of bits (ones and zeroes). A BIT STRING value can have any length, including zero. This type is a string type. BIT STRING, OCTET STRING, UTCTime, GeneralizedTime, and the various string types can use either primitive encoding or constructed encoding, at the sender’s discretion-- in BER. However, in DER all types that have an encoding choice between primitive and constructed must use the primitive encoding. DER restricts the encoding to primitive only. The same applies for BITSTRING. ie, For BIT STRING and OCTET STRING types, DER does not allow the constructed form (breaking a string into multiple TLVs) or the indefinite length form.

fn (bs BitString) data() []u8

data returns underlying BitString data.

fn (bs BitString) pad() u8

pad returns underlying BitString pad byte.

fn (bs BitString) tag() Tag

tag returns the tag of BITSTRING type.

fn (bs BitString) payload() ![]u8

payload returns the payload of BITSTRING instance.

struct Boolean {
mut:
	// boolean value represented in single  byte to allow stores multiple value represents
	// true value others than 0xff, ie., non-null byte representing true value.
	value u8
}

ASN.1 UNIVERSAL CLASS OF BOOLEAN TYPE.

A Boolean value can take true or false. ASN.1 DER encoding restricts encoding of boolean true value into 0xff and otherwise, encodes into zero (0x00) for false value. The encoding of a boolean value shall be primitive. The contents octets shall consist of a single octet.

fn (v Boolean) tag() Tag

tag returns the tag of Boolean type.

fn (b Boolean) payload() ![]u8

payload returns the payload of Boolean type in .der rule.

fn (b Boolean) value() bool

value gets the boolean value represented by underlying byte value. It returns FALSE if the byte == 0x00 and TRUE otherwise.

struct Choice {
mut:
	size    int = default_choices_size
	choosen Element
	choices []Element
}

ASN.1 CHOICE

Choice is an ASN.1 Element

fn (mut c Choice) set_size(size int) !

set_size sets the maximal this choices size

fn (mut c Choice) choose(some Element) !

choose chooses some element for as a choosen element for the choice c.

fn (c Choice) tag() Tag

tag returns the tag of choice element.

fn (c Choice) payload() ![]u8

payload returns the payload of choice element.

struct ContextElement {
	RawElement
}

ContextSpecific tagged type element.

fn (ctx ContextElement) tag() Tag

tag returns the tag of context specific element.

fn (ctx ContextElement) payload() ![]u8

payload returns the payload of the context specific element.

struct Enumerated {
pub:
	value int
}

ASN.1 ENUMERATED TYPE.

Enumerated type treated as ordinary integer, only differs on tag value. The encoding of an enumerated value shall be that of the integer value with which it is associated. In DER rule, Enumerated type should be primitive type.

fn (e Enumerated) tag() Tag

The tag of enumerated element.

fn (e Enumerated) payload() ![]u8

The payload of the enumerated element.

struct FieldOptions {
mut:
	// The fields `cls`, `tagnum`, `mode` and `inner` was used
	// for wrapping (and unwrapping) purposes. turn some element
	// into another element configured with this options.
	// In the encoding (decoding) phase, it would be checked
	// if this options meet required criteria.
	// Limitation applied on the wrapper fields:
	// 1. Wrap into UNIVERSAL is not allowed (cls != universal)
	// 2. You should provide mode for wrapping, explicit or implicit.
	// 3. If cls == '', no wrapping is performed, discarding all wrapper options
	cls    string // should cls != 'universal'
	tagnum int = -1 // Provides with wrapper tag number, as n outer tag number.
	mode   string // explicit or implicit, depends on definition schema.

	// inner should valid inner tag format, ie, universal form in single value 'number'
	// or extended form in triplet value of 'class,form,number' format.
	inner string

	// optional field applied to element with OPTIONAL behaviour, with or without DEFAULT value.
	// Set `optional` to true when this element has OPTIONAL keyword in the definition of element.
	// Usually element with OPTIONAL keyword is not presents in the encoding (decoding) data.
	optional bool
	present  bool

	// This field applied to element with DEFAULT keyword behaviour.
	// Its applied into wrapping of element or optionality of the element.
	// If some element has DEFAULT keyword, set this field to true and gives default element
	// into `default_value` field.
	has_default   bool
	default_value ?Element
}

Configuration format for field tagging.

Currently, this configurations option support following string config, ie.

• class:number, for wrapping the element with other non-universal class, for examole: private:100.
• explicit or implicit mode.
• inner:5 for universal class form or inner:class,constructed,number for extended form.
• optional or `optional:present' tagging for element with OPTIONAL behaviour.
• has_default tagging for element with DEFAULT behaviour.

Field options attributes handling.

FieldOptions is a structure to accomodate and allowing configures your complex structures through string or arrays of string stored in FieldOptions fields. For example, you can tagging your fields of some element with tagging like @[context_specific:10; explicit; inner:5; optional]. Its will be parsed and can be used to drive encoding or decoding of Element.

fn (mut fo FieldOptions) install_default(el Element, force bool) !

install_default tries to install and sets element el as a default value when has_default flag of FieldOptions has been set into true, or error if has_default is false. When default_value has been set with some value before this, its would return error until you force it by setingt force flag into true.

struct GeneralString {
pub:
	value string
}

ASN.1 GENERALSTRING Handling It may contain any characters from a "G" and "C" set of any standardized character sets. A "G" set contains some specified set of graphic (i.e., printable) characters, while a "C" set contains a group of control characters. For example, the "G" set in the ASCII character set consists of the characters with ASCII numbers 33 through 126, while the "C" set is those characters with ASCII numbers 0 through 31. For historical reasons, the characters SPACE (number 32) and DELETE (number 127) are not considered to be in either the C set or the G set, but instead stand on their own We only treated GeneralString as an us-ascii charset

fn (gst GeneralString) tag() Tag

tag returns the tag of GeneralString type element.

fn (gst GeneralString) payload() ![]u8

payload returns the payload of GeneralString type element.

struct GeneralizedTime {
pub:
	value string
}

ASN.1 UNIVERSAL CLASS OF GENERALIZEDTIME TYPE.

In DER Encoding scheme, GeneralizedTime should :- The encoding shall terminate with a "Z"

• The seconds element shall always be present
• The fractional-seconds elements, if present, shall omit all trailing zeros;
• if the elements correspond to 0, they shall be wholly omitted, and the decimal point element also shall be omitted

GeneralizedTime values MUST be:- expressed in Greenwich Mean Time (Zulu) and MUST include seconds(i.e., times are YYYYMMDDHHMMSSZ), even where the number of seconds is zero.- GeneralizedTime values MUST NOT include fractional seconds.

fn (gt GeneralizedTime) into_utctime() !time.Time

into_utctime turns this GeneralizedTime into corresponding UTC time.

fn (gt GeneralizedTime) tag() Tag

The tag of GeneralizedTime element.

fn (gt GeneralizedTime) payload() ![]u8

The payload of GeneralizedTime element.

struct IA5String {
pub:
	value string
}

ASN.1 IA5String type handling routine. IA5String is a standard ASCII characters

fn (v IA5String) tag() Tag

tag returns the tag of IA5String type element.

fn (v IA5String) payload() ![]u8

payload returns the payload of IA5String type element.

struct Integer {
pub:
	// underlying integer value with support from `i64` and `big.Integer`
	value IntValue
}

Integer represent Universal class of arbitrary length type of ASN.1 INTEGER. The encoding of an integer value shall be primitive. If the contents octets of an integer value encoding consist of more than one octet, then the bits of the first octet and bit 8 of the second octet. a) shall not all be ones; and. b) shall not all be zero. NOTE – These rules ensure that an integer value is always encoded in the smallest possible number of octets.

fn (v Integer) hex() string

hex returns Integer value as a hex string.

fn (v Integer) tag() Tag

tag returns the tag of Integer type element

fn (v Integer) payload() ![]u8

payload returns the payload of Integer type element.

fn (n Integer) equal(m Integer) bool

equal do checking if integer n was equal to integer m. ISSUE?: There are some issues when compared n == m directly, its fails even internally its a same, so we provide and use equality check

fn (v Integer) as_bigint() !big.Integer

as_bigint casts Integer value to big.Integer or error on fails.

fn (v Integer) as_i64() !i64

as_i64 casts Integer value to i64 value or error on fails.

struct Null {}

ASN.1 UNIVERSAL CLASS OF NULL TYPE.

The ASN.1 NULL type is a placeholder used when there is no value. It's a simple, non-string type with the UNIVERSAL TAG number 5. The NULL type can be used in situations where the presence of a type is important, but no concrete value is needed.

fn (n Null) tag() Tag

tag returns the tag of Null element.

fn (n Null) payload() ![]u8

payload returns the payload of the Null element, its should empty bytes.

struct NumericString {
pub:
	value string
}

NumericString.

NumericString was restricted character string types restricted to sequences of zero, one or more characters from some specified collection of characters. That was : digit : 0,1,..9 and spaces char (0x20)

fn (nst NumericString) tag() Tag

tag returns the tag of NumericString element.

fn (nst NumericString) payload() ![]u8

payload returns the payload of NumericString element.

struct ObjectIdentifier {
mut:
	value []int
}

ASN.1 ObjectIdentifier type.

The ASN. 1 OBJECT IDENTIFIER type is used when you need to provide a unique identifier.

fn (o ObjectIdentifier) value() []int

value returns underlying ObjectIdentifier values as arrays of int.

fn (oid ObjectIdentifier) tag() Tag

tag returns the tag of ObjectIdentifier type.

fn (oid ObjectIdentifier) payload() ![]u8

payload the payload of ObjectIdentifier type.

fn (oid ObjectIdentifier) equal(oth ObjectIdentifier) bool

equal checks whether two ObjectIdentifier was equal.

struct OctetString {
pub:
	value string
}

ASN.1 UNIVERSAL TYPE OF OCTETSTRING.

The ASN.1 OCTET STRING type contains arbitrary strings of octets. This type is very similar to BIT STRING, except that all values must be an integral number of eight bits. You can use constraints to specify a maximum length for an OCTET STRING type.

fn (oct OctetString) tag() Tag

tag returns the tag of OctetString type.

fn (oct OctetString) payload() ![]u8

payload returns the payload of OctetString type.

struct Optional {
	// underlying element marked as an optional
	elem Element
mut:
	// presence of this flag negates optionality of this elemeent.
	// set to true when its should present, if not sure, just set to to false
	present bool
}

ASN.1 OPTIONAL Element.

Note: At the abstract ASN.1 level the absence of a DEFAULT value in an encoding is the same as its being present.Contrast this with OPTIONAL, where a value being present in the encoding is semantically distinct from its being absent. In some encoding rules (like BER/PER) it is at the whim of the sender whether a DEFAULT value is encoded or not (except for primitive type values in PER which are required by the PER standard to be absent in the encoding), while with others (like DER) the DEFAULT value is NEVER encoded. For all encoding rules, if the component that has a DEFAULT value is not encoded the receiving application must behave as though the DEFAULT value had been encoded.

fn (mut opt Optional) set_present_bit(present bool)

set_present_bit sets this Optional element with flag in present.

fn (opt Optional) tag() Tag

tag returns the tag of Optional element.

fn (opt Optional) payload() ![]u8

payload the payload of Optional element.

fn (opt Optional) encode() ![]u8

encode serializes this Optional element into bytes array.

fn (opt Optional) into_element() !Element

into_element turns this optional into Element.

fn (opt Optional) into_object[T]() !T

into_object tries to turns this optional into real underlying object T. Its return object T on success or error on fails.

struct Parser {
mut:
	data []u8
}

Parser is ongoing ASN.1 parser. Its capables parsing ASN.1 element through availables methods.

fn (mut p Parser) reset()

reset resets internal data of parser to empty buffer.

fn (mut p Parser) peek_tag() !Tag

peek_tag lookups the tag from the parser without updates internal parser data.

fn (mut p Parser) read_tag() !Tag

read_tag lookups the tag from the current parser and updates internal parser data.

fn (mut p Parser) read_length() !Length

read_length read the Length from the current parser data.

fn (mut p Parser) read_bytes(length int) ![]u8

read_bytes read length bytes from the current parser data.

fn (mut p Parser) read_tlv() !Element

read_tlv read an Element from the parser data. Its return an Element, you should cast it to underlying data if you need.

fn (mut p Parser) finish() !

finish end this parser or error if not empty.

fn (mut p Parser) is_empty() bool

is_empty checks whether the parser has empty buffer data.

struct PrintableString {
pub:
	value string
}

ASN.1 UNIVERSAL CLASS OF PRINTABLESTRING TYPE.

PrintableString consists of: Latin capital letters A, B, ... Z Latin small letters a, b, ... z Digits 0, 1, ... 9 symbols: (space) ' ( ) + , - . / : = ?

fn (pst PrintableString) tag() Tag

tag returns the tag of PrintableString element.

fn (pst PrintableString) payload() ![]u8

payload returns the payload of PrintableString element.

struct PrivateELement {
	RawElement
}

Limited support for PRIVATE CLASS Element.

fn (prv PrivateELement) tag() Tag

tag returns the tag of the private element.

fn (prv PrivateELement) payload() ![]u8

payload returns the payload of the private element.

struct RawElement {
mut:
	// The tag is the (outer) tag of the TLV, if this a wrpper.
	tag Tag
	// `content` is the value of a TLV. Its depends on the context.
	content []u8
	// Optional fields
	inner_tag     ?Tag
	mode          ?TaggedMode
	default_value ?Element
}

ASN.1 Raw Element.

fn (r RawElement) tag() Tag

tag returns the tag of the RawElement, ie, outer tag when its a wrapper.

fn (r RawElement) payload() ![]u8

payload returns the payload of the RawElement.

fn (mut r RawElement) set_mode(mode TaggedMode, force bool) !

set_mode sets the RawElement tagged mode, in explicit or implicit mode. If the mode has been set, it would drop into error until you forces it by setting force flag into true value, ie, replaces the old one.

fn (mut r RawElement) set_inner_tag(inner_tag Tag, force bool) !

set_inner_tag sets the inner tag of the RawElement into inner_tag value. If it has been already set, it would be an error until you setting force flag into true value to replace the old one.

fn (r RawElement) inner_tag() ?Tag

inner_tag returns the inner tag of the RawElement if it exists, or error on fails.

fn (r RawElement) inner_element() !Element

inner_element returns the inner element of the RawElement if its exists.

struct Sequence {
mut:
	//	maximal size of this sequence fields
	size int = default_sequence_size
	// fields is the elements of the sequence
	fields []Element
}

ASN.1 UNIVERSAL CLASS OF SEQUENCE and SEQUENCE OF TYPE.

https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der These are two very different types. A SEQUENCE is equivalent to “struct” in most programming languages. It holds a fixed number of fields of different types. A SEQUENCE OF, holds an arbitrary number of fields of a single type. This is analogous to an array or a list in a programming language. Sequence structure can represents both SEQUENCE and SEQUENCE OF type. The encoding of a sequence value shall be constructed. in DER encoded of SEQUENCE or SET, never encode a default value.

fn (seq Sequence) tag() Tag

tag returns the tag of Sequence element.

fn (seq Sequence) payload() ![]u8

payload returns the payload of Sequence element.

fn (seq Sequence) encoded_len() int

encoded_len tells the length of serialized Sequence element in bytes.

fn (seq Sequence) fields() []Element

fields returns the Sequences fields.

fn (mut seq Sequence) set_size(size int) !

set_size sets maximal size of this sequence fields.

fn (mut seq Sequence) add_element(el Element) !

add_element adds an element el into Sequence fields. By default its allows adding element with the same tag.

fn (seq Sequence) is_sequence_of[T]() bool

is_sequence_of[T] checks whether this sequence is SequenceOf[T] type.

fn (seq Sequence) into_sequence_of[T]() !SequenceOf[T]

into_sequence_of[T] turns this sequence into SequenceOf[T] element.

struct SequenceOf[T] {
mut:
	size   int = default_sequence_size
	fields []T
}

ASN.1 SEQUENCE OF TYPE. SequenceOf[T] is an arrays of generic T, so the generic T should fullfill Element interface. We dont use generic aliases because generic type aliases are not yet implemented.

struct Set {
mut:
	//	maximal size of this set fields
	size int = default_set_size
	// fields is the elements of the set
	fields []Element
}

ASN.1 UNIVERSAL SET and SET OF TYPE.

SET and SET OF contains an unordered series of fields of one or more types. This differs from a SEQUENCE which contains an ordered list. in DER encoding, SET types elements are sorted into tag order, and, for SET OF types elements are sorted into ascending order of encoding.

fn (s Set) tag() Tag

tag returns the tag of Set element.

fn (s Set) payload() ![]u8

payload returns the payload of the Set element.

Note: Required for DER encoding.The encodings of the component values of a set value shall appear in an order determined by their tags. The canonical order for tags is based on the outermost tag of each type and is defined as follows: a) those elements or alternatives with universal class tags shall appear first, followed by those with application class tags, followed by those with context-specific tags, followed by those with private class tags; b) within each class of tags, the elements or alternatives shall appear in ascending order of their tag numbers.

fn (set Set) fields() []Element

fields return the arrays of element's content in the Set.fields.

fn (mut set Set) add_element(el Element) !

add_element adds an element el into Set. By default it allowing adds element with the same tag

fn (mut set Set) set_size(size int) !

set_size set internal maximal size of this set fields.

struct SetOf[T] {
mut:
	size   int = default_set_size
	fields []T
}

ASN.1 SET OF

struct Tag {
mut:
	class       TagClass = .universal
	constructed bool
	number      int
}

ASN.1 Tag identifier handling.

Tag represents identifier of the ASN.1 element (object). ASN.1 Tag number can be represented in two form, the short form and the long form. The short form for tag number below <= 30 and stored enough in single byte. The long form for tag number > 30, and stored in two or more bytes.

ASN.1 imposes no limit on the tag number, but the NIST Stable Implementation Agreements (1991) and its European and Asian counterparts limit the size of tags to 16383. see https://www.oss.com/asn1/resources/asn1-faq.html#tag-limitation We impose limit on the tag number to be in range 0..16383. Its big enough to accomodate and represent different of yours own tag number. Its represents 2 bytes length where maximum bytes arrays to represent tag number in multibyte (long) form is [u8(0x1f), 0xff, 0x7f] or 16383 in base 128.

fn (t Tag) tag_class() TagClass

tag_class return the ASN.1 class of this tag

fn (t Tag) is_constructed() bool

is_constructed tells us whether this tag is in constructed form or the primitive one, ie, not constructed.

fn (t Tag) tag_number() int

tag_number return the tag nunber of this tag

fn (t Tag) encode(mut dst []u8) !

encode serializes the tag into bytes array with default rule, ie, .der. Its serializes into dst bytes buffer or return error on fails.

fn (t Tag) equal(o Tag) bool

equal checks whether this tag is equal with the other tag

fn (t Tag) tag_size() int

tag_size informs us how many bytes needed to store this tag includes one byte marker if in the long form.

fn (t Tag) universal_tag_type() !TagType

universal_tag_type turns this Tag into available UNIVERSAL class of TagType, or return error if it is unknown number.

struct UtcTime {
pub:
	value string
}

ASN.1 UNIVERSAL CLASS OF UTCTIME TYPE.

For this time, UtcTime represented by simple string with format "YYMMDDhhmmssZ"- the six digits YYMMDD where YY is the two low-order digits of the Christian year,(RFC 5280 defines it as a range from 1950 to 2049 for X.509), MM is the month (counting January as 01), and DD is the day of the month (01 to 31).- the four digits hhmm where hh is hour (00 to 23) and mm is minutes (00 to 59); (SEE NOTE BELOW)

• the six digits hhmmss where hh and mm are as in above, and ss is seconds (00 to 59);
• the character Z;
• one of the characters + or -, followed by hhmm, where hh is hour and mm is minutes (NOT SUPPORTED)

NOTE

• Restrictions employed by DER, the encoding shall terminate with "Z".
• The seconds element shall always be present, and DER (along with RFC 5280) specify that seconds must be present,
• Fractional seconds must not be present.

Todo:- check for invalid representation of date and hhmmss part.

• represented UtcTime in time.Time

fn (utc UtcTime) tag() Tag

tag retursn the tag of the UtcTime element.

fn (utc UtcTime) payload() ![]u8

payload returns the payload of the UtcTime element.

fn (utc UtcTime) into_utctime() !time.Time

into_utctime turns this UtcTime into corresponding UTC time.

struct Utf8String {
pub:
	value string
}

ASN.1 UNIVERSAL CLASS OF UTF8STRING TYPE.

UTF8STRING is UTF8 unicode charset

fn (uts Utf8String) tag() Tag

tag returns the tag of Utf8String element.

fn (uts Utf8String) payload() ![]u8

payload returns the payload of Utf8String element.

struct VisibleString {
pub:
	value string
}

ASN.1 UNIVERSAL CLASS OF VISIBLESTRING TYPE.

The ASN.1 VisibleString type supports a subset of ASCII characters that does not include control characters.

fn (vst VisibleString) tag() Tag

tag returns the tag of VisibleString type element.

fn (vst VisibleString) payload() ![]u8

payload returns the payload of VisibleString type element.