`asn1` module documentation.

About `asn1` module

asn1 is a pure V module for handling Abstract Syntax Notation One (ASN.1) [X.680] objects encoded in Distinguished Encoding Rules (DER) [X.690] encoding scheme.

About asn1 module
What is ASN.1
ASN.1 Encoding
Basic ASN.1 Type System
Supported ASN.1 type
Generic ASN.1 Object
Basic ASN.1 Constructor
Encoding of ASN.1 Object
Decoding of ASN.1 Bytes
- Decoding function
- Example
Module Index
- ASN.1 Class
- Tag Type
- NULL
- BOOLEAN
- INTEGER
- ENUMERATED
- BIT STRING
- OCTET STRING
- OBJECT IDENTIFIER
- UTF8STRING
- IA5STRING
- PRINTABLE STRING
- VISIBLE STRING
- UTCTIME
- GENERALIZED TIME
- Sequence Type
- Set Type
Reference

What is ASN.1

From Wikipedia says, Abstract Syntax Notation One (ASN.1) is a standard interface description language for defining data structures that can be serialized and deserialized in a cross-platform way. It is broadly used in telecommunications and computer networking, and especially in cryptography.

Encoding of ASN.1

Encoding of ASN.1 is a set of encoding rules that specify how to represent a data structure as a series of bytes. There are multiple rules available that describes way of serializing ASN.1 object. The standard ASN.1 encoding rules include:

Basic Encoding Rules (BER)
Distinguished Encoding Rules (DER)
Canonical Encoding Rules (CER)
Basic XML Encoding Rules (XER)
many other encoding rules availables.

See [X.690] for more information about ASN.1 encoding.

Note

This module only support the DER encoding

Basic of ASN.1 Type System

Fundamentally, DER encoding of ASN.1 is serialization of a Tag, Length and Value (TLV) triplets. Every ASN.1 object has a tag that represents what is type of the object. The Tag part specifies the type of the data structure being sent, the Length part specifies the number of bytes of content being transferred, and the Value part contains the content. Note that the Value part can be a triplet if it contains a constructed data type.

ASN.1 Tag

ASN.1 type has a tag which is byte or series of bytes that describing class of the ASN.1 object, constructed (contains other object) or primitive and a non negative tag number. In this v asn1 module, its support short form tag for tag number below 31 and long form tag (multi byte tag) for representing tag number bigger than 31. To represent tag, in this asn1 module was using this structure:

struct Tag {
mut:
	class       Class
	constructed bool
	number      int
}

Where Class represent class of ASN.1 type. There are four class of ASN.1 type represented in:

enum Class {
	universal = 0x00
	application = 0x01
	context = 0x02
	private = 0x03
}

Create new tag

Most of the time, you don't need create tag structure manually, all basic universal type constructor set it for you internally, but for convenience, you can create a new tag, with the following constructor:

fn new_tag(c Class, constructed bool, number int) Tag

where c is the ASN.1 class this object belong to, constructed boolean flag tells if this object constructed or primitive, and provided tag number.

Length handling

ASN.1 length indicates how many bytes you should read to get values or contents part. It always represents the total number of bytes in the object including all sub-objects but does not include the lengths of the identifier or of the length field itself.

ASN.1 length comes in two form: short and long form, short form fits in single byte for length between 0 and 127, and the others is long form in multi byte form. This module support both of them, but, its only limited to DER encoding of length, ie, use definite length encoding and use the smallest possible length representation.

Supported Basic ASN.1 Type

Basic ASN.1 type was a ASN.1 object which has universal class. It's currently supports following basic ASN1 type:

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

Generic ASN.1 Object

For the purposes of handling ASN.1 object in general way, we use ASN1Object that defined as:

struct ASN1Object {
	tag    Tag 
	values []u8
}

where:

tag is the tag of object, and
values is the raw bytes array (contents) of the object without tag and length part.

You can create ASN1Object object with the constructor, provided with parameters :

Class this object belong to,
constructed boolean flag that tell this object constructed or primitive,
tagnum is the tag number, and,
values is bytes array of contents.

fn new_asn_object(c Class, constructed bool, tagnum int, values []u8) ASN1Object

This object implements Encoder interface, so you can treat it like other ASN.1 object and serialize it to bytes.

Note

Most of the time, you don't need to use ASN1Object directly, but, the recommended way to create ASN.1 object was using most basic type constructor described in [Creating Basic ASN.1 Type] below.

Create Basic ASN.1 Type

You can use following function to create basic UNIVERSAL ASN.1 type. Most of the constructor return Encoder interfaces.

Note

By default, all basic constructor has ASN.1 UNIVERSAL class tag, and the tag number is universal tag number defined in TagType enum, where constructed flag set to true value by default on SEQUENCE (SEQUENCE OF) and SET (SET OF) type. Some of the tag number was not supported in this module.

No	Function	ASN.1 Object	Description
1	new_boolean	BOOLEAN
2	new_integer	INTEGER
3	new_bitstring	BITSTRING	its accepts arbitrary v string, not a bit string
4	new_octetstring	OCTET STRING
5	new_null	NULL
6	new_oid_from_string	OBJECT IDENTIFIER
7	new_enumerated	ENUMERATED
8	new_utf8string	UTF8STRING
9	new_sequence	SEQUENCE, SEQUENCE OF	for sequence of, you should ensure you add the same object to sequence elements.
10	new_set	SET, SET OF	likes a sequence of, ensure add the same object to set elements
11	new_numeric_string	NUMERIC STRING
12	new_printable_string	PRINTABLE STRING
13	new_ia5string	IA5STRING
14	new_utctime	UTCTIME
15	new_generalizedtime	GENERALIZED TIME
16	new_visiblestring	VISIBLESTRING

and for handling EXPLICIT or IMPLICIT tagged object, there are two availables constructor:

new_implicit_context for wraps ASN.1 object in implicit mode.
new_explicit_context for wraps ASN.1 object in explicit mode.

Encoding ASN.1 Object

This section describes a way to do serializing ASN.1 to bytes array, included serialized tag and length. The most important to facilitate encoding functionality of the ASN.1 object we use Encoder interface.

Encoder Interface

Encoder is a main interrface that wraps ASN.1 encoding functionality.
Mostly all of basic types in this module implements this interface.
Encoder interface defined as;

interface Encoder {
	// tag of the underlying ASN.1 object
	tag() Tag
	// length of ASN.1 object (without tag and length part)
	length() int
	// length of encoded bytes of the object (included tag and length part)
	size() int
	// Serializes object to bytes array with DER encoding
	encode() ![]u8
}

Serializing ASN.1 Object to Bytes

For serializing ASN.1 object to bytes array, do following step to get bytes:

create desired ASN.1 object by calling desired constructor.
call encode()! method of the created object in previous step.
get the bytes array ready to transfer.

Example #1

In the first example, we would create simple object identifier object from string and serializing it to bytes array. For other object, see Basic ASN.1 Constructor.

input := '1.2.840.113549'

src := new_oid_from_string(input)!

out := src.encode()!
exp := [u8(0x06), 0x06, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d]
assert out == exp

Example #2

In the second example, we would create more complex type, sequence contains other object.

// create universal type sequence
mut seq := new_sequence()

// add three object to the sequence elements.
seq.add(new_utf8string('Hello')!) 
seq.add(new_integer(i64(42))) 
seq.add(new_explicit_context(new_oid_from_string('1.3.6.1.3')!, 1))

// lets serialize it to bytes
out := seq.encode()!
assert out == [u8(0x30), 18, u8(12), 5, 72, 101, 108, 108, 111, u8(2), 1, 42, u8(0xA1), 6, 6, 4, 43, 6, 1, 3]

Example #3

In the third example, lets create more complex type where sequence contains another sequence.

// lets create first sequence
mut seq1 := new_sequence()
// add two primitive elements to the sequence
seq1.add(new_boolean(true))
seq1.add(new_boolean(false))

// lets create another sequences, where it contains primitive element and first sequence created above.
mut seq2 := new_sequence()
seq2.add(new_boolean(false))
seq2.add(seq1)
seq2.add(new_boolean(true))

// lets serialize it to bytes
out := seq2.encode()!
expected := [u8(0x30), 14, u8(0x01), 0x01, 0x00, u8(0x30), 6, 0x01, 0x01, 0xff, 0x01, 0x01, 0x00,
		u8(0x01), 0x01, 0xff]
// assert for right value
assert seq2.length() == 14
assert seq2.size() == 16
assert out == expected

Decoding ASN.1 Bytes

This section describes how to parse (decode) bytes of data encoded in ASN.1 DER encoding. This module export der_decode defined below as main routine to do parsing of DER encoded data. Its accepts bytes arrays encoded in DER in src params and returns Encoder interfaces object, so, you should cast it to get underlying type. By default, in context specific class, its try to read as tagged object, whether its explicit or implicit.

`der_decode` function

der_decode function signature as below:

fn der_decode(src []u8) !Encoder

--Example--

We're going to use above data in Example #3 as an example for der_decode functionality.

// the data we're going to decode, serialized in DER encoding.
data := [u8(0x30), 14, u8(0x01), 0x01, 0x00, u8(0x30), 6, 0x01, 0x01, 0xff, 0x01, 0x01,
		0x00, u8(0x01), 0x01, 0xff]

// lets call `der_decode` routine
out := der_decode(data)!
// lets cast it to sequence
seq := out.as_sequence()!
	

el0 := seq.elements[0].as_boolean()!
assert el0.value == false 

el1 := seq.elements[1].as_sequence()!
//dump(el1)
el2 := seq.elements[2].as_boolean()!
assert el2.value == true

If we dump el1 element, we exactly got the structure of sequence, with elements contains two bolean values, like we constructed in Example #3 above. Similar like this output:

el1: asn1.Sequence{
    tag: asn1.Tag{
        class: universal
        constructed: true
        number: 16
    }
    elements: [asn1.Encoder(asn1.Boolean{
        value: true
    }), asn1.Encoder(asn1.Boolean{
        value: false
    })]

Module Index

This section describes available functions, methods, or others structure to build and mixup functionality in this module.

Class

Class is ASN.1 tag class. Its represents scope of the type. ASN.1 specs says there are four ASN.1 class, ie, UNIVERSAL, APPLICATION, CONTEXT SPECIFIC, and PRIVATE class. Currently most of universal class type supported in this module, with limited support for other class.

enum Class {
	universal = 0x00
	application = 0x01
	context = 0x02
	private = 0x03
}

Files

DOCS.md

Latest commit

History

DOCS.md

File metadata and controls

asn1 module documentation.

About asn1 module

Table of Contents

What is ASN.1

Encoding of ASN.1

Basic of ASN.1 Type System

ASN.1 Tag

Create new tag

Length handling

Supported Basic ASN.1 Type

Generic ASN.1 Object

Create Basic ASN.1 Type

Encoding ASN.1 Object

Encoder Interface

Serializing ASN.1 Object to Bytes

Example #1

Example #2

Example #3

Decoding ASN.1 Bytes

der_decode function

--Example--

Module Index

Class

TagType

new_oid_from_string

new_visiblestring

new_utf8string

new_utctime

new_tag

new_set_with_class

new_set

new_sequence_with_class

new_sequence

new_asn_object

new_bitstring

new_boolean

new_enumerated

new_explicit_context

new_generalizedtime

new_ia5string

new_implicit_context

new_integer

new_null

new_numeric_string

new_octetstring

new_printable_string

read_explicit_context

contents

as_sequence

as_set

as_boolean

as_integer

as_bitstring

as_octetstring

as_null

as_oid

as_utf8string

as_numericstring

as_printablestring

as_ia5string

as_visiblestring

as_utctime

as_generalizedtime

Enumerated

tag

length

size

encode

GeneralizedTime

tag