From 94f7e0867fb3367fe86b2220df414f9133d911ec Mon Sep 17 00:00:00 2001 From: Kenneth Lundin Date: Fri, 10 Sep 2010 09:57:45 +0200 Subject: Add warning about since long unsupported [{Cname,Val}] repr. of SEQUENCE/SET Othe minor corrections as well. --- lib/asn1/doc/src/asn1_ug.xml | 113 ++++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 51 deletions(-) (limited to 'lib/asn1/doc') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index f2cd073ec8..12d986308f 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -4,7 +4,7 @@
- 19972009 + 19972010 Ericsson AB. All Rights Reserved. @@ -22,7 +22,7 @@ Asn1 - ETX/DN/SP Kenneth. Lundin + Kenneth Lundin 1999-03-25 D @@ -41,17 +41,28 @@ decode functions to be used by Erlang programs sending and receiving ASN.1 specified data. Run-time functions used by the generated code. - Encoding rules supported are BER, the - specialized BER version DER and the basic form of - aligned and unaligned variants of PER. + The supported encoding rules are: + + + Basic Encoding Rules (BER) + + + Distinguished Encoding Rules (DER), a specialized form of BER that is used in security-conscious applications. + + + Packed Encoding Rules (PER) both the aligned and unaligned variant. + + +
Overview -

ASN.1 (Abstract Syntax Notation 1) defines the abstract - syntax of information. The purpose of ASN.1 is to have - a platform independent language to express types using a +

ASN.1 (Abstract Syntax Notation 1) is a formal language for describing data structures to be exchanged between distributed computer systems. + The purpose of ASN.1 is to have + a platform and programming language independent notation to express + types using a standardized set of rules for the transformation of values of a defined type, into a stream of bytes. This stream of bytes can then be sent on a communication channel set up by the @@ -102,20 +113,16 @@ [], free to download at http://www.oss.com/asn1/dubuisson.html .

-

Knowledge of Erlang programming is also essential and reading the book - Concurrent Programming in ERLANG, - [], is recommended. Part 1 of this is available on the web in - PDF format. -

Capability

This application covers all features of ASN.1 up to the 1997 - edition of the specification. In the 2002 edition some new - extensions came up of which there are support only for some of - them. ECN (Cncoding Control Notation) and XML notation are still - unsupported. Though, the other features of 2002 edition are + edition of the specification. In the 2002 edition of ASN.1 a number of + new features where introduced of which some are supported while + others are not. For example the + ECN (Encoding Control Notation) and XML notation are still + unsupported. Though, the other features of the 2002 edition are fully or partly supported as shown below:

@@ -308,7 +315,7 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn

Choice of encoding rules, if omitted ber is the default. The ber_bin and per_bin options allows for optimizations and are therefore recommended - instaed of the ber and per options.

+ instead of the ber and per options.

 -o OutDirectory @@ -629,7 +636,7 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). driver options does not affect the encode or decode result, just the time spent in run-time. When ber_bin and driver or per_bin, optimize and driver is - combined the C-code driver is used in choosen parts of encode / + combined the C-code driver is used in chosen parts of encode / decode procedure.

@@ -749,11 +756,11 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). you may want to continue running the old asn1 run-time functionality.Performance issues: If you have an asn1 system with a lot - of cross references you may gain in performance. Meassurements + of cross references you may gain in performance. Measurements must be done for each case.

You may choose either the plain multi file compilation that just - merges the choosen asn1 specs or the {inline,OutputModule} + merges the chosen asn1 specs or the {inline,OutputModule} that also includes the used asn1 run-time functionality.

For both cases you need to specify which asn1 specs you will compile in a module that must have the extension @@ -919,7 +926,7 @@ T5 ::= INTEGER (MIN<..-99) T6 ::= INTEGER {red(0),blue(1),white(2)}

The Erlang representation of an ASN.1 INTEGER is an integer or - an atom if a so called \011Named NumberList (see T6 above) + an atom if a so called Named Number List (see T6 above) is specified.

Below is an example of Erlang code which assigns values for the above types:

@@ -934,7 +941,7 @@ T6value3 = white ASN.1 defined types. This style of value can be passed directly to the encoder for transformation into a series of bytes.

The decoder will return an atom if the value corresponds to a - symbol in the Named NumberList.

+ symbol in the Named Number List.

@@ -978,8 +985,9 @@ N1 = 'NULL',

The enumerated type can be used, when the value we wish to describe, may only take one of a set of predefined values.

-DaysOfTheWeek ::= ENUMERATED { sunday(1),monday(2),tuesday(3),
-\011wednesday(4),thursday(5),friday(6),saturday(7) }
+DaysOfTheWeek ::= ENUMERATED { 
+    sunday(1),monday(2),tuesday(3),
+    wednesday(4),thursday(5),friday(6),saturday(7) }

For example to assign a weekday value in Erlang use the same atom as in the Enumerations of the type definition:

@@ -1273,11 +1281,14 @@ Pdu ::= SEQUENCE {

Values can be assigned in Erlang as shown below:

 MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}.
-

It is also possible to specify the value for each component in - a SEQUENCE or a SET as {ComponentName,Value}. It is not - recommended and is not supported if the flags per_bin or - ber_bin and optimize were used when the module was - compiled.

+ +

+ In very early versions of the asn1 compiler it was also possible to + specify the values of the components in + a SEQUENCE or a SET as a list of tuples {ComponentName,Value}. + This is no longer supported. +

+

The decode functions will return a record as result when decoding a SEQUENCE or a SET. @@ -1293,13 +1304,13 @@ MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}.

For instance, if the following types exists in a file "File.asn":

 Seq1 ::= SEQUENCE {
-\011a  INTEGER DEFAULT 1,
-\011b  Seq2 DEFAULT {aa TRUE, bb 15}
+    a INTEGER DEFAULT 1,
+    b Seq2 DEFAULT {aa TRUE, bb 15}
 }
 
 Seq2 ::= SEQUENCE {
-\011aa BOOLEAN,
-\011bb INTEGER
+    aa BOOLEAN,
+    bb INTEGER
 }

Some values and the corresponding encoding in an Erlang terminal @@ -1331,7 +1342,7 @@ ok

But, the DER encoding format has stronger requirements regarding - default\011values both for SET and SEQUENCE. A more elaborate and time + default values both for SET and SEQUENCE. A more elaborate and time expensive check of default values will take place. The following is an example with the same types and values as above but with der encoding format.

@@ -1409,7 +1420,7 @@ Bad ::= SET {i INTEGER, values is the same for SET as for SEQUENCE, and is supported by the compiler, see above.

Moreover, in DER the elements of a SET will be sorted. If a - component is an untagged choice the sorting have to take place + component is an un-tagged choice the sorting have to take place in run-time. This fact emphasizes the following recommendation if DER encoding format is used.

The concept of SET is an unusual @@ -1425,7 +1436,7 @@ Bad ::= SET {i INTEGER,

- Notes about Extendability for SEQUENCE and SET + Notes about Extend-ability for SEQUENCE and SET

When a SEQUENCE or SET contains an extension marker and extension components like this:

@@ -1498,9 +1509,9 @@ C2 ::= CHOICE {
       

         Extendable CHOICE
         
When a CHOICE contains an extension marker and the decoder detects
-          an unknown alternative of the CHIOCE the value is represented as:

+          an unknown alternative of the CHOICE the value is represented as:

         
-\011  {asn1_ExtAlt, BytesForOpenType}
+{asn1_ExtAlt, BytesForOpenType}
         

         
Where BytesForOpenType is a list of bytes constituting the 
           encoding of the "unknown" CHOICE alternative. 

@@ -1630,15 +1641,15 @@ V = #'Emb'{a=["qqqq",[1,2,255]],
         the record name is extended with an underscore and the component
         name. If the embedded structure is deeper with SEQUENCE, SET or
         CHOICE types in the line, each component-/alternative-name will
-        be added to the recordname.

+        be added to the record-name.

       
For example:

       
 Seq ::= SEQUENCE{
-    a\011CHOICE{
-\011b SEQUENCE {
-\011   c  INTEGER
-\011   }
-\011}
+    a CHOICE{
+        b SEQUENCE {
+           c  INTEGER
+        }
+    }
 }      

       
will result in the following record:

       
@@ -1650,10 +1661,10 @@ Seq ::= SEQUENCE{
       
 Seq ::= SEQUENCE {
     a SEQUENCE OF SEQUENCE {
-\011       b
+           b
                }
     c SET OF SEQUENCE {
-\011       d
+           d
                }
 }      

       
This results in the records:

@@ -1802,16 +1813,16 @@ GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
     
 StartMessage  ::= SEQUENCE {
     msgId  GENERAL-PROCEDURE.&id  ({GENERAL-PROCEDURES}),
-    content GENERAL-PROCEDURE.&Message\011({GENERAL-PROCEDURES}{@msgId}),
+    content GENERAL-PROCEDURE.&Message ({GENERAL-PROCEDURES}{@msgId}),
     }    

     
In the type StartMessage the constraint following the
       content field tells that in a value of type
       StartMessage the value in the content field must
-      come from the same object that is choosen by the msgId
+      come from the same object that is chosen by the msgId
       field.

     
So, the value #'StartMessage'{msgId="home",content="Any Printable String"} is legal to encode as a StartMessage
       value, while the value #'StartMessage'{msgId="remote", content="Some String"} is illegal since the constraint
-      in StartMessage tells that when you have choosen a value from a 
+      in StartMessage tells that when you have chosen a value from a 
       specific object in the object set GENERAL-PROCEDURES in the 
       msgId field you have to choose a value from that same object in
       the content field too. In this second case it should have been 
@@ -1831,7 +1842,7 @@ StartMessage  ::= SEQUENCE {
       information object sets. 
       A part of a definition can be supplied as a parameter. For
       instance, if a Type is used in a definition with certain
-      purpose, one want the typename to express the intention. This
+      purpose, one want the type-name to express the intention. This
       can be done with parameterization.

     
When many types (or an other ASN.1 entity) only differs in some
       minor cases, but the structure of the types are similar, only
-- 
cgit v1.2.3