'\" t .\" This documentation, which is part of the afnix writing .\" system distribution, is free and can be distributed as .\" long as this copyright notice is left intact. .\" .\" This documentation is distributed in the hope that it .\" will be useful, but without any warranty; without even .\" the implied warranty of merchantability and fitness .\" for a particular purpose. In no event, shall the .\" copyright holder be liable for any direct, incident .\" incidental or special damages arising in any way out .\" of the use of this documentation. .\" .\" Copyright (c) 1999-2017 Amaury Darsch .\" .TH itu 3 2018-07-20 AFNIX "AFNIX Module" .SH NAME itu - standard telecom module .SH STANDARD TELECOM MODULE The Standard Telecommodule is an original implementation of various standards managed by the International Telecommunictaion Union (ITU). At the heart of this module is the Abstract Syntax Notation(ASN.1) which is widely used to model data records and store certificates. .PP .B Abstract syntax notation .br The abstract syntax notation (ASN.1) is standardized by the ITU to express a normal form of communication. The ASN.1 is in fact the de-facto standard for representing X509 certificate and is the only justification to provide the support for such complex representation. .PP .I Encoding rules .br This implementation supports all encoding forms as defined by the ITU, namely the Basic Encoding Rule(BER), the Canonical Encoding Rule(CER) and the Distinguished Encoding Rule(DER). The DER form is by far the most widely used. .PP .I ASN objects .br All objects as defined by the ITU are supported in this implementation, including the ability to create custom OID. .TS l l. Object Description AsnBoolean Boolean primitive AsnInteger Integer primitive AsnBits Bit string AsnOctets Octet string AsnBmp Bmp string AsnIas IA5 string AsnNums Numeric string AsnPrts Printable string AsnUtfs Unicode string AsnUnvs Universal string AsneNull Null primitive AsneEoc End-of-Content primitive AsnGtm Generalized time primitive AsnUtc Utc time primitive AsnSequence Asn node Sequence AsnSet Asn node Set AsnOid Asn object identifier Set AsnRoid Asn object relative identifier Set .TE .sp .PP .I Using ASN.1 objects .br Using ASN.1 object is particularly straightfoward. One can directly creates a particular object by invoking the appropriate constructor. .sp .nf # create an asn boolean node trans abn (afnix:itu:AsnBoolean true) # check the node type assert true (afnix:itu:asn-node-p abn) assert true (afnix:itu:asn-boolean-p abn) .fi .sp Writing the object can be done into a buffer or an output stream. Note that the default encoding is the DER encoding. .sp .nf # write into a buffer trans buf (Buffer) abn:write buf # check the buffer content assert "0101FF" (buf:format) .fi .sp Building an ASN.1 representation can be achieved by parsing a buffer or an input stream. This is done by filling a buffer and requesting a buffer node mapping. .sp .nf # parse the buffer and check const anb (afnix:itu:AsnBuffer buf) # map the node to a boolean trans abn (anb:node-map) # check the node assert true (afnix:itu:asn-node-p abn) assert true (afnix:itu:asn-boolean-p abn) .fi .sp With more complex structure, it is likely that a sequence object will be returned by the buffer node mapper. Once the sequence object is created, each node can be accessed by index like any other container. .SH STANDARD TELECOM REFERENCE .PP .B AsnNode .br The AsnNodeclass is the base class used to represent the asn tree. The structure of the node is defined in ITU-T X.690 recommendation. This implementation supports 64 bits tag number with natural machine length encoding. The Canonical Encoding Rule (CER) and Distinguished Encoding Rule (DER) are defined by the class. Since ASN.1 provides several encoding schemes, the class is designed to be as generic as possible but does not provides the mechanism for changing from one representation to another although it is perfectly valid to read a DER representation and write it in the CER form. .PP .I Predicate .br .sp .RS asn-node-p .RE .PP .I Inheritance .br .sp .RS Object .RE .PP .I Constants .br .sp .RS .B BER .br The BERconstant defines the Basic Encoding Rulenode encoding. .RE .sp .RS .B CER .br The CERconstant defines the Canonical Encoding Rulenode encoding. .RE .sp .RS .B DER .br The DERconstant defines the Distinguished Encoding Rulenode encoding. .RE .sp .RS .B UNIVERSAL .br The UNIVERSALconstant defines the node universal class. .RE .sp .RS .B APPLICATION .br The APPLICATIONconstant defines the node application class. .RE .sp .RS .B CONTEXT-SPECIFIC .br The CONTEXT-SPECIFICconstant defines the node context specific class. .RE .sp .RS .B PRIVATE .br The PRIVATEconstant defines the node private class. .RE .PP .I Methods .br .sp .RS .B reset -> none (none) .br The resetmethod reset a node to its default value. .RE .sp .RS .B length -> Integer (none) .br The lengthmethod returns the total node length in bytes. .RE .sp .RS .B get-class -> UNIVERSAL|APPLICATION|CONTEXT-SPECIFIC|PRIVATE (none) .br The get-classmethod returns the node class. .RE .sp .RS .B primitive-p -> Boolean (none) .br The primitive-preturns true if the node is a primitive. .RE .sp .RS .B constructed-p -> Boolean (none) .br The constructed-preturns true if the node is a constructed node. .RE .sp .RS .B get-tag-number -> Integer (none) .br The get-tag-number-preturns node tag number. .RE .sp .RS .B get-content-length -> Integer (none) .br The get-content-length-preturns node content length. .RE .sp .RS .B write -> none (none|OutputStream|Buffer) .br The writemethod write the asn node contents as well as the child nodes to an output stream argument or a buffer. Without argument, the node is written to the interpreter output stream. With one argument, the node is written to the specified stream or buffer. .RE .PP .B AsnOctets .br The AsnOctetsclass is the asn object class that encodes the octet string type. This type can be encoded either as a primitive or as constructed at sender's option. In CER form, the primitive form is used when the content length is less than 1000 octets, and the constructed form is used otherwise. The DER form will always use the primitive form. .PP .I Predicate .br .sp .RS asn-octets-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnOctets (none) .br The AsnOctetsconstructor creates a default asn octets string node. .RE .sp .RS .B AsnOctets (String|Buffer) .br The AsnOctetsconstructor creates an asn octets string node by string of buffer object. .RE .PP .I Methods .br .sp .RS .B to-buffer -> Buffer (none) .br The to-buffermethod returns a Bufferobject as an octet string representation. .RE .PP .B AsnBuffer .br The AsnBufferclass is the asn object class that provides a generic implementation of an asn structure. The class acts as a simple encoder and decoder with special facilities to retarget the buffer content. .PP .I Predicate .br .sp .RS asn-buffer-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnBuffer (none) .br The AsnBufferconstructor creates a default asn buffer node. .RE .sp .RS .B AsnBuffer (InputStream|Buffer|Bitset) .br The AsnBufferconstructor creates an asn buffer node from an input stream, a buffer or a bitset. .RE .PP .I Methods .br .sp .RS .B reset -> none (none) .br The resetmethod reset the buffer. .RE .sp .RS .B parse -> Boolean (InputStream|Buffer|Bitset) .br The parsemethod parse a node represented by an input stream, a buffer or a bitset. .RE .sp .RS .B node-map -> AsnNode (none) .br The node-mapmethod returns a node mapping of this buffer. .RE .sp .RS .B get-content-buffer -> Buffer (none) .br The get-content-buffermethod returns the asn buffer content as a buffer object. .RE .PP .B AsnNull .br The AsnNullclass is the asn object class that encodes the null primitive. This primitive has a unique encoding. The length is always 0 and there is no content octet. .PP .I Predicate .br .sp .RS asn-null-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnNull (none) .br The AsnNullconstructor creates a default asn null node. .RE .PP .B AsnEoc .br The AsnEocclass is the asn object class that encodes the eoc or end-of-content primitive. This primitive is almost never used but its encoding is used with the indefinite length encoding. .PP .I Predicate .br .sp .RS asn-eoc-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnEoc (none) .br The AsnEocconstructor creates a default asn eoc node. .RE .PP .B AsnBoolean .br The AsnBooleanclass is the asn object class that encodes the boolean primitive. This primitive has a unique encoding with the CER or DER rule, but the BER rule can support any byte value for the true value. .PP .I Predicate .br .sp .RS asn-boolean-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnBoolean (none) .br The AsnBooleanconstructor creates a default asn boolean node. .RE .sp .RS .B AsnBoolean (Boolean) .br The AsnBooleanconstructor creates an asn boolean node from a boolean object. .RE .PP .I Methods .br .sp .RS .B to-boolean -> Boolean (none) .br The to-booleanmethod returns a Booleanobject as the asn node representation. .RE .PP .B AsnInteger .br The AsnIntegerclass is the asn object class that encodes the integer primitive. This primitive has a unique encoding with the CER or DER rule. All encoding use a signed 2-complement form. .PP .I Predicate .br .sp .RS asn-integer-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnInteger (none) .br The AsnIntegerconstructor creates a default asn integer node. .RE .sp .RS .B AsnInteger (Integer|Relatif) .br The AsnIntegerconstructor creates an asn integer node from an integer or relatif object. .RE .PP .I Methods .br .sp .RS .B to-relatif -> Relatif (none) .br The to-relatifmethod returns a Relatifobject as the asn node representation. .RE .PP .B AsnBits .br The AsnBitsclass is the asn object class that encodes the bit string type. This type can be encoded either as a primitive or as constructed at sender's option. In CER form, the primitive form is used when the content length is less than 1000 octets, and the constructed form is used otherwise. The DER form will always use the primitive form. .PP .I Predicate .br .sp .RS asn-bits-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnBits (none) .br The AsnBitsconstructor creates a default asn bits node. .RE .sp .RS .B AsnBits (String|Bitset) .br The AsnBitsconstructor creates an asn bits node from a string or a bitset. .RE .PP .I Methods .br .sp .RS .B to-bits -> Bitset (none) .br The to-bitsmethod returns a Bitsetobject as a bit string representation. .RE .PP .B AsnBmps .br The AsnBmpsclass is the asn object class that encodes the asn bmp string primitive also known as the UCS-2 type string. This string is implemented, after conversion as an octet string. Consequently the rules for encoding in CER and DER modes are applied. .PP .I Predicate .br .sp .RS asn-bmps-p .RE .PP .I Inheritance .br .sp .RS AsnOctets .RE .PP .I Constructors .br .sp .RS .B AsnBmps (none) .br The AsnBmpsconstructor creates a default asn string (BMP) node. .RE .sp .RS .B AsnBmps (String) .br The AsnBmpsconstructor creates an asn string (BMP) node from a string. .RE .PP .I Methods .br .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a Stringobject as a node representation. .RE .PP .B AsnIas .br The AsnIasclass is the asn object class that encodes the IA5 string primitive. This string is implemented, after conversion as an octet string. Consequently the rules for encoding in CER and DER modes are applied. .PP .I Predicate .br .sp .RS asn-ias-p .RE .PP .I Inheritance .br .sp .RS AsnOctets .RE .PP .I Constructors .br .sp .RS .B AsnIas (none) .br The AsnIasconstructor creates a default asn string (IA5) node. .RE .sp .RS .B AsnIas (String) .br The AsnIasconstructor creates an asn string (IA5) node from a string. .RE .PP .I Methods .br .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a Stringobject as a node representation. .RE .PP .B AsnNums .br The AsnNumsclass is the asn object class that encodes the asn numeric string primitive. This string is implemented, after conversion as an octet string. Consequently the rules for encoding in CER and DER modes are applied. .PP .I Predicate .br .sp .RS asn-nums-p .RE .PP .I Inheritance .br .sp .RS AsnOctets .RE .PP .I Constructors .br .sp .RS .B AsnNums (none) .br The AsnNumsconstructor creates a default asn string (NUMERIC) node. .RE .sp .RS .B AsnNums (String) .br The AsnNumsconstructor creates an asn string (NUMERIC) node from a string. .RE .PP .I Methods .br .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a Stringobject as a node representation. .RE .PP .B AsnPrts .br The AsnPrtsclass is the asn object class that encodes the asn printable string primitive. This string is implemented, after conversion as an octet string. Consequently the rules for encoding in CER and DER modes are applied. .PP .I Predicate .br .sp .RS asn-prts-p .RE .PP .I Inheritance .br .sp .RS AsnOctets .RE .PP .I Constructors .br .sp .RS .B AsnPrts (none) .br The AsnPrtsconstructor creates a default asn string (PRINTABLE) node. .RE .sp .RS .B AsnPrts (String) .br The AsnPrtsconstructor creates an asn string (PRINTABLE) node from a string. .RE .PP .I Methods .br .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a Stringobject as a node representation. .RE .PP .B AsnUtfs .br The AsnUtfsclass is the asn object class that encodes the asn utf string primitive. This string is implemented as an octet string. Consequently the rules for encoding in CER and DER modes are applied. .PP .I Predicate .br .sp .RS asn-utfs-p .RE .PP .I Inheritance .br .sp .RS AsnOctets .RE .PP .I Constructors .br .sp .RS .B AsnUtfs (none) .br The AsnUtfsconstructor creates a default asn string (UNICODE) node. .RE .sp .RS .B AsnUtfs (String) .br The AsnUtfsconstructor creates an asn string (UNICODE) node from a string. .RE .PP .I Methods .br .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a Stringobject as a node representation. .RE .PP .B AsnUnvs .br The AsnUnvsclass is the asn object class that encodes the universal string primitive also known as the UCS-4 type string. This string is implemented, after conversion as an octet string. Consequently the rules for encoding in CER and DER modes are applied. .PP .I Predicate .br .sp .RS asn-unvs-p .RE .PP .I Inheritance .br .sp .RS AsnOctets .RE .PP .I Constructors .br .sp .RS .B AsnUnvs (none) .br The AsnUnvsconstructor creates a default asn string (UNIVERSAL) node. .RE .sp .RS .B AsnUnvs (String) .br The AsnUnvsconstructor creates an asn string (UNIVERSAL) node from a string. .RE .PP .I Methods .br .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a Stringobject as a node representation. .RE .PP .B AsnGtm .br The AsnGtmclass is the asn object class that encodes the generalized time primitive. This primitive is encoded from its equivalent string representation. Although, the constructed mode is authorized, it does not make that much sense to use it. .PP .I Predicate .br .sp .RS asn-gtm-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnGtm (none) .br The AsnGtmconstructor creates a default asn gtm node. .RE .sp .RS .B AsnGtm (String) .br The AsnGtmconstructor creates an asn gtm node from a string. .RE .PP .I Methods .br .sp .RS .B utc-p -> Boolean (none) .br The utc-ppredicate returns true if the time is expressed in UTC mode. .RE .sp .RS .B to-time -> Integer (none) .br The to-timemethod returns a time representation of this asn node. .RE .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a string representation of this asn node. .RE .PP .B AsnUtc .br The AsnUtcclass is the asn object class that encodes the utc time primitive. This primitive is encoding from its equivalent string representation. Although, the constructed mode is authorized, it does not make that much sense to use it. .PP .I Predicate .br .sp .RS asn-utc-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnUtc (none) .br The AsnUtcconstructor creates a default asn utc node. .RE .sp .RS .B AsnUtc (String) .br The AsnUtcconstructor creates an asn utc node from a string. .RE .PP .I Methods .br .sp .RS .B utc-p -> Boolean (none) .br The utc-ppredicate returns true if the time is expressed in UTC mode. .RE .sp .RS .B to-time -> Integer (none) .br The to-timemethod returns a time representation of this asn node. .RE .sp .RS .B to-string -> String (none) .br The to-stringmethod returns a string representation of this asn node. .RE .PP .B AsnSequence .br The AsnSequenceclass is the asn object class that encodes the sequence constructed type. The order of elements is preserved in the encoding of the sequence. .PP .I Predicate .br .sp .RS asn-sequence-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnSequence (none) .br The AsnSequenceconstructor creates an empty asn sequence node. .RE .PP .I Methods .br .sp .RS .B node-length -> Integer (none) .br The node-lengthmethod returns the number of nodes in the sequence. .RE .sp .RS .B node-add -> none (AsnNode) .br The node-addmethod adds a node to the sequence. .RE .sp .RS .B node-get -> AsnNode (Integer) .br The node-getmethod returns an asn node by index. .RE .PP .B AsnSet .br The AsnSetclass is the asn object class that encodes the set constructed type. The order of elements is not important in a set. .PP .I Predicate .br .sp .RS asn-set-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnSet (none) .br The AsnSetconstructor creates an empty asn set node. .RE .PP .I Methods .br .sp .RS .B node-length -> Integer (none) .br The node-lengthmethod returns the number of nodes in the set. .RE .sp .RS .B node-add -> none (AsnNode) .br The node-addmethod adds a node to the set. .RE .sp .RS .B node-get -> AsnNode (Integer) .br The node-getmethod returns an asn node by index. .RE .PP .B Oid .br The Oidclass is a base class that represents the X500 object identifier which is used in the ASN.1 encoding and in the X509 standard. An oid is simply represented by a vector of subidentifiers. .PP .I Predicate .br .sp .RS oid-p .RE .PP .I Inheritance .br .sp .RS Object .RE .PP .I Constructors .br .sp .RS .B Oid (Integer|...) .br The Oidconstructor creates an oid from a sequence of integers. .RE .PP .I Methods .br .sp .RS .B reset -> none (none) .br The resetmethod resets the oid object to its null empty state. .RE .sp .RS .B length -> Integer (none) .br The lengthmethod returns the length of the oid. .RE .sp .RS .B add -> none (Integer|...) .br The addmethod adds one or more sub-indentifiers to the oid. .RE .sp .RS .B get -> Integer (Integer) .br The getmethod returns an oid sub-identifier by index. .RE .sp .RS .B format -> String (none) .br The formatmethod returns a string representation of the oid. .RE .PP .B AsnOid .br The AsnOidclass is the asn object class that encodes the object identifier primitive. This primitive has a unique encoding with the CER or DER rule. The oid is built as a vector of subidentifiers (sid). Each sid is represented as an octa (64 bits) value. .PP .I Predicate .br .sp .RS asn-oid-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnOid (Integer|...) .br The AsnOidconstructor creates an asn oid from a sequence of sid. .RE .PP .I Methods .br .sp .RS .B sid-length -> Integer (none) .br The lengthmethod returns the length of the oid. .RE .sp .RS .B sid-add -> none (Integer) .br The sid-addmethod adds a sid the oid object. .RE .sp .RS .B sid-get -> Integer (Integer) .br The sid-getmethod returns a sid by oid index. .RE .sp .RS .B get-oid -> Oid (none) .br The get-oidmethod returns an oid object as the asn oid representation. .RE .PP .B AsnRoid .br The AsnRoidclass is the asn object class that encodes the object relative identifier primitive. This primitive has a unique encoding with the CER or DER rule. The oid is built as a vector of subidentifiers (sid). Each sid is represented as an octa (64 bits) value. The difference with the oid object is to be found in the encoding of the first 2 sid. .PP .I Predicate .br .sp .RS asn-roid-p .RE .PP .I Inheritance .br .sp .RS AsnNode .RE .PP .I Constructors .br .sp .RS .B AsnRoid (Integer|...) .br The AsnRoidconstructor creates an asn roid from a sequence of sid. .RE .PP .I Methods .br .sp .RS .B sid-length -> Integer (none) .br The lengthmethod returns the length of the oid. .RE .sp .RS .B sid-add -> none (Integer) .br The sid-addmethod adds a sid the oid object. .RE .sp .RS .B sid-get -> Integer (Integer) .br The sid-getmethod returns a sid by oid index. .RE .sp .RS .B get-oid -> Oid (none) .br The get-oidmethod returns an oid object as the asn oid representation. .RE .PP .I Functions .br .sp .RS .B asn-random-bits -> none (Integer) .br The exitfunction creates a random asn bit string. The argument is the number of bits in the random string. .RE .sp .RS .B asn-random-octets -> none (Integer) .br The exitfunction creates a random asn octet string. The integer argument is the number of octets in the string. .RE