asn1 module documentation.[!CAUTION] This module is marked as an experimental, so, its a subject to change (even rapidly). Use it with caution, submit when found a bug and gives yours feedback and review.
asn1 moduleasn1 is a experimental pure V module for handling Abstract Syntax Notation One (ASN.1) [X.680] objects encoded in Distinguished Encoding Rules (DER) [X.690] encoding scheme.
This document is intended to serve as documentation (actually as a note) of
internal details of this asn1 module.
Its describes some parts of the module in the way is implemented,
the lack and also issues or limitation we have found around it.
asn1 moduleFrom 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 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:
NoteThis module only support the DER encoding
Fundamentally, DERencoding 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.
Every ASN.1 type has a tag which acts as an identifier of some ASN.1 element. The tag 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.
ASN.1 Tag identifier was represented by this compact structure, ie,
struct Tag {
mut:
class TagClass
constructed bool
number int
}
Where TagClass represent class of ASN.1 type. There are four class of ASN.1 type represented in:
enum TagClass {
universal = 0x00
application = 0x01
context_specific = 0x02
private = 0x03
}
There are two form how the ASN.1 tag was represented, ie, short form tag for tag number below 31 and long form tag (multi byte tag) for representing tag number bigger than 31.
This module support both of form, but the size (length) is limited to max_tag_length constant,
currently set to 3 bytes length. This effectively limits the tag number supported by this
module to be in 0..16.383 number ranges. See comment on core.v file for the background on this.
When your tag has a class of universal type, your tag nunber also be limited to be under 255,
hopefully if your tag is universal type, just use universal type supported by this module.
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 Tag.new(c TagClass, 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.
You can serialize (encode) your tga with method defined in this module,
fn (t Tag) encode(mut dst []u8) !
By default, encode would try to serialize tag in DER rule into destination buffer provided in
dst, or returns error on fails.
This module provides routine for reading tag from bytes. You can use
fn Tag.from_bytes(bytes []u8) !(Tag, []u8)
It would create a tag from bytes, return a tag and remaining bytes (bytes after tag) on success, or returns error on fails.
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.
The standard of X.690 ITU document defines two length types
Note This module only support definite length but its only limited to DER encoding of length. Theoretically, definite length support for very big number for length value, ie, value between 0 and 2^1008-1, but in this module, this limited to defined constant,ASN.1 length was represented in a simple type, ie,max_definite_length_countset to 6 bytes currently, andmax_definite_length_valueset to builtinmax_int.
type Length = int
fn Length.new(v int) !Length
fn Length.from_bytes(bytes []u8) !(Length, []u8)
This module provides method to serialize the length into destination buffer,
fn (v Length) encode(mut dst []u8) !
At the core for support handling element in generic and concise way, a fundamental
and abstracted way provided in this module is an Element interface, dedined as:
interface Element {
tag() Tag
payload() ![]u8
}
where the tag acts as an identifier of the element and payload tells the value's part
of the element. The payload methods of the Element does not dictates on how your element
generates payload. Its up to specific encoding rules or other constraints.
Note Most of the functions or methods defined in this module was accept or return an
Element. Most of them is implemented with DER encoding in mind, so, your custom element hopefylly would be supported by this functions (methods) if your element correctly implemented required constraints in this module.
Its possible to build payload for complex structure, your own defined struct contains multiples
field of elements with the help of function on this modules. Of course, you can build
your payload manually, but this asn1 module has provides helper routine to do that, in the form:
fn make_payload[T](val T, kd KeyDefault) ![]u8
Note
Tis struct contains one or more fields that fullfills Element interface.- KeyDefault is map of
field.namekey with some element value (only the field has DEFAULT keyword) to setup default value.
Its would produces only element's payload without tag or length bytes included. When your structures does not contains the fields that fullfills interfaces, it would produces and return empty bytes.
This modules provides several functions for serializing ASN.1 Element, in three forms, ie:
fn encode(el Element) ![]u8
fn encode_with_options(el Element, opt string) ![]u8
fn encode_with_field_options(el Element, fo FieldOptions) ![]u8
All of three's functions produces bytes result on success or error on fails. The two latest form is serialization routines intended for serializing element with wrapping, optional or default semantic to existing element, gives you a extra flexibility to the serialization (deserialization) process. For more information in detail, see FieldOptions
A PrintableString containing “hi” was serialized into 13 02 68 69.
obj := asn1.PrintableString.new('hi')!
output := asn1.encode(obj)!
assert output == [u8(0x13), 0x02, 0x68, 0x69]
When your element is tagged type element, defined with [5] IMPLICIT PrintableString, you can pass
a string option into encode, ie:
output := encode_with_options(obj, 'context_specific:5;implicit;inner:19')!
assert output == [u8(0x85), 0x02, 0x68, 0x69]
Or when its a explicit tagged element defined as [5] EXPLICIT PrintableString
output := encode_with_options(obj, 'context_specific:5;explicit;inner:0x13')!
assert output == [u8(0xA5), 0x04, 0x13, 0x02, 0x68, 0x69]
For deserialization purposes, this module provides functions with similar in serialization parts, ie, in the form:
fn decode(src []u8) !Element
fn decode_with_options(bytes []u8, opt string) !Element
fn decode_with_field_options(bytes []u8, fo FieldOptions) !Element
Technically, the deserialization mechanism is reverse of serialization process.
When you pass an options to decode routine, you should ensure its a same options
used for serialization in encode part, or the decode would result in undefined behaviour
if its differs.
The decode function families, accepts DER serialized bytes, and an options
(if its should be) and return some Element, or return error on fails.
When you get result an Element from decode routine, you can get underlying object
by calling into_object method on the element.
fn (el Element) into_object[T]() !T
Examples:
el := asn1.decode([u8(0x13), 0x02, 0x68, 0x69])!
ps := el.into_object[asn1.PrintableString]()!
So, its also happens to pass an options string when this bytes comes from serialized tagged type element,
bytes := [u8(0xA5), 0x04, 0x13, 0x02, 0x68, 0x69]
obj := asn1.decode_with_options(bytes, 'context_specific:5;explicit;inner:0x13')!
For supporting more complex scenarios, inspired by the same options used in go version of
asn1 module, this module comes with support configures serialization (deserialization) process
through configuration options stored in FieldOptions structure.
Consider some Certificate structure represents more complex ASN.1 schemas from RFC 5280,
Certificate ::= SEQUENCE {
tbsCertificate TBSCertificate,
signatureAlgorithm AlgorithmIdentifier,
signatureValue BIT STRING
}
TBSCertificate ::= SEQUENCE {
version [0] EXPLICIT Version DEFAULT v1,
serialNumber CertificateSerialNumber,
signature AlgorithmIdentifier,
issuer Name,
validity Validity,
subject Name,
subjectPublicKeyInfo SubjectPublicKeyInfo,
issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL
}
This schema required support for other machinery in the form of tagged element
with wrapping semantic, OPTIONAL keyword handling, and DEFAULT keyword handling,
Its supported through the FieldOptions structures defined as:
struct FieldOptions {
mut:
// For wrapping purposes
cls string
tagnum int = -1
mode string
inner string
// for OPTIONAL handling
optional bool
present bool
// FOR DEFAULT handling
has_default bool
default_value ?Element
}
The main purpose of this options structures is used for:
There are two constructor for construct a FieldOptions, ie
fn FieldOptions.from_string(s string) !FieldOptions
fn FieldOptions.from_attrs(attrs []string) !FieldOptions
The first function allowing you pass a string as an options, likes an examples above. Examples:
fo := FieldOptions.from_string('context_specific:5;explicit;inner:0x13')!
fo := FieldOptions.from_string('context_specific:5;explicit;inner:0x13;optional')!
The second form, is gives more controllable options, and its allowing tag your field of struct with the supported options, Examples :
struct PersonnelRecord {
mut:
name asn1.OctetString @[context_specific: 0; implicit; inner: 4]
location asn1.Integer @[context_specific: 1; implicit; inner: 2]
age asn1.Integer @[context_specific: 2; implicit; inner: 2]
}
attrs := ['context_specific: 0', 'implicit', 'inner: 4']
fo := FieldOptions.from_attrs(attrs)!
// and then you can pass the options to serialization phase
out := asn1.encode_with_field_options(p.name, fo)!
The field optional and present of the FieldOptions was used for handling element
with OPTINAL keyword within element definition.
The mean of the flags:
optional bit was set into true, thats mean, the element treated as element
with OPTIONAL semantic.present bit was set into true, this optional element mean was present in
the encoding data, by default optional was not included in the encoding phase (not present)Element with DEFAULT keyword, by DER encoding rule, when the element is equal with default value provided, its not present in the serialized bytes. For this purposes, before serialization, you should call:
fn (el Element) set_default_value(mut fo FieldOptions, value Element) !
to setup default value within the options for the current element, or would be error
if has_default flag is set but default value is not availables.
See field_options.v for more detail on this options.
Basic ASN.1 type was a ASN.1 object which has universal class. It's currently supports following basic ASN1 type:
big.Integer)Most Universal class of ASN.1 type supported in this modules comes with builtin constructor. You should use this constructor when you hope an universal type. Its comes with common signature of the constructor (not at all, but most of them), see module doc for detail.
fn T.new(value) !T
fn T.from_string(string) !T // for string-based type
fn T.from_int(int) !T // for integer-based
fn T.from_bigint(bigint) !T // for integer with big.Integer
When your element is non-universal class, this module has a limited support for this type of element. Its represented in several structures, defined as :
pub 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
}
pub struct ContextElement {
RawElement
}
pub struct ApplicationElement {
RawElement
}
pub struct PrivateELement {
RawElement
}
Intended usage for this non-universal class is for wrapping semantic, instead create your own non-universal manually. For examples, if you have some element (maybe non-universal), you want create non-universal element from this element, you can call (for creating private type element) routine :
fn PrivateELement.from_element(inner Element, tagnum int, mode TaggedMode) !PrivateELement
Its currently support nested wrapping, but the unwrapping process should do by your self.
Warning There are some limitation on this wrapping,
- You can't wrap into universal class
- You can't wrap an Optional Element.
See other_element.v on the repo for more details on this.