|
The Command Line |
Command-line Options |
Directives |
Converting to/from CSV Format |
Frequently Asked Questions
Sets a special representation for INTEGERs whose size is not supported by the operating system in use. By default, INTEGER types are represented as machine dependent 16-bit, 32-bit, or 64-bit numbers.
--<ASN1.HugeInteger absoluteReference>--
absoluteReference refers to an ASN.1 INTEGER type that will be represented using the HugeInteger representation, which consists of a series of octets that contain the integer in binary format.
We stand with Ukraine --<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--
LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
lengthOfSolarSystem INTEGER,
units ENUMERATED
{nm(-9), mkm (-6), mm(-3), cm(-2), m(0), km(3)} DEFAULT mm
}
END
For the ASN.1 syntax above, the XER encoding that contains the big INTEGER value of 5913000000000000000000 (which does not fit a 64-bit integer) is successfully decoded:
ASN1STEP: Decoding PDU #1 from file 'LengthData.xer':
<LengthData>
<lengthOfSolarSystem> 5913000000000000000000&l/lengthOfSolarSystem>
</LengthData>
Successfully decoded in 93 bytes.
rec1value LengthData ::=
{
lengthOfSolarSystem '01408B5BFB9554C40000'H
}
If the directive is not specified, ASN-1Step reports the following error while decoding:
D0023E: Integer or enumerated value too long: 1844674407370955161; check field 'lengthOfSolarSystem' of PDU #1 'LengthData' at line 2 position 42.
Specifies that one or more ASN.1 types should be treated as protocol data units. By default, all unreferenced types (defined types not referenced by any other type) are considered PDUs by ASN-1Step, so they can be encoded/decoded as complete units.
--<ASN1.PDU type [, type] ...>--
type is an absolute reference that specifies which ASN.1 types should be treated as PDUs.
The PDU directive can have three syntaxes:
--<ASN1.PDU Module.Type>--
Module DEFINITIONS ::= BEGIN
TypeRef ::= Type
Type ::= SET { b BOOLEAN }
END
In the example above, the SET type will be treated as a PDU, even though it is referenced in another type definition.
Passing the notation above through ASN-1Step with the following command:
asn1step filename -listPduIdentifiers
generates this output:
ASN1STEP: List of valid PDU numbers and associated PDU names:
1. Type
2. Type-setComponent-encodable
Specifies the year of the ASN.1 standard in use for a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source. By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.
--<ASN1.Version version moduleName [{ oid }]>--
version refers to a year that an ASN.1 standard was published by ITU-T (e.g., 1990, 1994, 1997, 2002, 2008, 2015, or 2021). moduleName is a mandatory operand that specifies the module to which the directive is applied. oid is an optional OBJECT IDENTIFIER for unique module identification.
--<ASN1.Version 2008 LengthModule>--
LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
INTEGER,
BOOLEAN
}
buffer LengthData ::= { 255, TRUE }
END
When the following command is executed for the notation above
asn1step filename -syntaxOnly -noRelaxedMode
ASN-1Step will print this warning message (among others):
"filename", line 5 (LengthModule): A0427W: Mixed 1990 and 2021 ASN.1 syntax: "missing identifier" on line 5
and "ASN1VER 2008 directive" on line 3.
INTEGER,
^
If the directive is commented out, no warnings are issued.
Identifies those parts of the ASN.1 input that are central to the application. All names (types, values, information objects, etc.) defined in the working set are directly available for use by the application. By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives present. See Default Determination of the Working Set below for details.
--<ASN1.WorkingSet WSName absoluteReference [, absoluteReference] ...>--
WSName is the name of the working set. Although required for consistency with other ASN.1 Tools, it is otherwise ignored. absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. When a module name is referenced, the ASN1.WorkingSet directive has the same effect as that of the OSS.ROOT directive: all unreferenced types in this module are considered PDUs.
Items in the ASN.1 specification that are not included in the working set are available to the application only when they are referenced from the working set.
A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set on its own.
To extend an existing working-set, specify another instance of the ASN1.WorkingSet directive containing the existing working-set name and the ASN.1 item to be added. In the following ASN.1, both module1 and module14 will be included in commonSet:
--<ASN1.WorkingSet commonSet module1>-- . . . --<ASN1.WorkingSet commonSet module14>--
Including a type reference in a working set does not necessarily make it a PDU. In the following ASN.1, MyWorkingSet does not explicitly include A.Foo; it is included implicitly since A.Foo is referenced by A.Bar. The result is two types in the working set that reference each other; so neither is a PDU (unless the implementation makes them so).
--<ASN1.WorkingSet MyWorkingSet A.Bar>--
A DEFINTIONS ::= BEGIN
Foo ::= SEQUENCE OF Bar
Bar ::= SEQUENCE {a INTEGER, b Foo OPTIONAL}
Z ::= BOOLEAN
ENDIn this example, Type1, Type2, and Type4 are directly available to the application as PDUs; Type3 is not.
--<ASN1.WorkingSet WSName Module2, Module3.Type4>--
Module2 DEFINITIONS ::= BEGIN
Type1 ::= SET {
typeComponent INTEGER,
b BOOLEAN
}
Type2 ::= INTEGER
END
Module3 DEFINITIONS ::= BEGIN
Type3 ::= SET {
aComponent INTEGER,
b BOOLEAN
}
Type4 ::= IA5String
END
ASN-1Step derives the working set by considering four types of directives, in the following order:
Based on the presence or absence of these directives in the input, ASN-1Step assumes one of these four modes:
Different sets of directives in the ASN.1 input determine which ASN.1 Compiler mode is used, as shown in the following table. 1 means a directive is present, 0 means a directive is absent, and 1/0 indicates that a directive can be present or absent with no effect on mode selection.
| Directive Types Present in Input | ASN.1 Compiler Mode | |||
|---|---|---|---|---|
| ASN1.WorkingSet | Other ASN1.* Directives | OSS.ROOT | Other OSS.* Directives | |
| 0 | 1 | 0 | 0 | Default Working Set |
| 0 | 0 | 0 | 0 | Root Default |
| 0 | 1/0 | 0 | 1 | |
| 1 | 1/0 | 1 | 1/0 | Working Set |
| 0 | 1 | 1 | 1/0 | |
| 1 | 1/0 | 0 | 1/0 | |
| 0 | 0 | 1 | 1/0 | Root |
These directives specify internal representations for ASN.1 REAL type values. By default, the ASN.1 REAL type is represented as a MixedReal.
--<OSS.DECIMAL [absoluteReference]>-- --<OSS.DOUBLE [absoluteReference]>-- --<OSS.MIXED [absoluteReference]>--
absoluteReference refers to a component in the ASN.1 syntax that is intended for the specified representation.
When the OSS.DECIMAL directive is used, the internal representation of a null-terminated character string is used with the following form:
[-]nnnnn.nnnnn[E[-]nnnnn]
When the OSS.DOUBLE directive is used, the C double data type is used to represent values.
When the OSS.MIXED directive is used, the value being encoded is represented as follows, permitting either a decimal or binary representation:
{ mantissa nnn, base {10|2}, exponent nnn.}
When specified globally, these directives can take an absolute reference that specifies which ASN.1 syntax component is intended for the desired representation.
When specified globally without an absolute reference, the OSS.DECIMAL and OSS.DOUBLE directives determine the default representation for all REAL types within their scope.
When specified locally, these directives do not take any arguments and only affect the type they are placed next to.
The following ASN.1 notation shows the various ways to determine the REAL type representation:
--<OSS.DECIMAL Module.DREAL>-- Module DEFINITIONS ::= BEGIN MREAL ::= REAL --<MIXED>-- DREAL ::= REAL -- DECIMAL due to the new style directive BREAL ::= REAL --<DOUBLE>-- r REAL ::= 3.14159265358979323846264338327950288 m MREAL ::= r d DREAL ::= r b BREAL ::= r END
Output excerpts from the "asn1step filename -test -per" command shows that the m and d values are encoded the same way without loss of precision, but b is printed and encoded differently due to its binary representation. Also, the number of bytes required to store the decoded value differs for m (pure decimal representation) and d (mixed decimal representation):
Tracing Information from Decoder...
MREAL REAL [length = 42.0]
"31415926535897932384626433832795028 ..."
Total encoded length = 43.0
PDU successfully decoded, in 64 bytes
...
Tracing Information from Decoder...
DREAL REAL [length = 42.0]
"31415926535897932384626433832795028 ..."
Total encoded length = 43.0
PDU successfully decoded, in 56 bytes
...
Tracing Information from Decoder...
BREAL REAL [length = 9.0]
884279719003555 * 2^-48
Total encoded length = 10.0
PDU successfully decoded, in 8 bytes
Instructs the compiler to use the definite or indefinite length form when encoding PDUs.
--<OSS.DEFINITE [absoluteReference]>--
--<OSS.INDEFINITE [absoluteReference]>--
absoluteReference refers to an ASN.1 component in the specification that is a PDU.
When specified globally, these directives require an absolute reference to the targeted PDU. If these directives are applied to non-PDU ASN.1 types there is no effect. When specified globally without an absolute reference, OSS.DEFINITE and OSS.INDEFINITE sets the type of length encoding for all PDUs in their scope. When specified locally, these directives do not take any arguments and affect only the type they are placed next to.
--<OSS.INDEFINITE>--
Module DEFINITIONS ::= BEGIN
DataPacket ::= SEQUENCE {
username IA5String,
userID INTEGER
}
dataPacket DataPacket ::= {username "John", userID 10}
END
The example above illustrates both directives. --<OSS.INDEFINITE>-- sets a global default for indefinite length encoding. Consequently, DataPacket will be encoded using the indefinite length form, since no other directives are applied to it. But if --<OSS.DEFINITE>-- is specified, DataPacket will be encoded using the definite length form. After passing these notations using the following command, see the output below.
asn1step filename -ber -encodeValue dataPacket
Output
In the first case, when --<OSS.INDEFINITE>-- is specified:
ASN1STEP: Encoding of valuereference 'dataPacket' for PDU #1:
Encoding to the file 'dataPacket.ber' using BER encoding rule...
DataPacket SEQUENCE: tag = [UNIVERSAL 16] constructed; length = indef
username IA5String: tag = [UNIVERSAL 22] primitive; length = 4
"John"
userID INTEGER: tag = [UNIVERSAL 2] primitive; length = 1
10
EOC
Encoded successfully in 13 bytes:
30801604 4A6F686E 02010A00 00
In the second case, when --<OSS.DEFINITE>-- is specified:
ASN1STEP: Encoding of valuereference 'dataPacket' for PDU #1:
Encoding to the file 'dataPacket.ber' using BER encoding rule...
DataPacket SEQUENCE: tag = [UNIVERSAL 16] constructed; length = 9
username IA5String: tag = [UNIVERSAL 22] primitive; length = 4
"John"
userID INTEGER: tag = [UNIVERSAL 2] primitive; length = 1
10
Encoded successfully in 11 bytes:
30091604 4A6F686E 02010A
The compiler uses the definite length form.
Instructs the compiler to generate a separate DTD (XML Data Type Definition) for a specified PDU. By default, no DTDs are produced by ASN-1Step unless the -dtd option is specified.
--<OSS.DTD [absoluteReference "NewName.dtd"]>--
absoluteReference refers to a PDU in the ASN.1 input for which to generate a separate XML DTD. NewName is an optional argument that specifies a new, full pathname for the generated DTD. When absoluteReference is not specified, a DTD will be produced for each and every PDU in the input syntax. This form of the OSS.DTD directive (i.e., a global directive application) is identical in behavior to the -dtd command-line option. Although the OSS.DTD directive can appear anywhere white space is allowed, the OSS prefix must be present.
When the -dtd compiler option is specified, a DTD for each PDU in the input is generated into a separate file whose name is derived from that of the PDU.
NOTE: You can use DTDs to make XER output produced by ossEncode() editable in a non-ASN.1-specific XML tool.
In the following example, two separate DTD files, StringType.dtd and AnotherNameForInt.dtd, are produced for their PDUs.
--<OSS.DTD XModule.StringType>--
--<OSS.DTD XModule.IntType "AnotherNameForInt.dtd">--
XModule DEFINITIONS ::= BEGIN
StringType ::= UTF8String
IntType ::= INTEGER
studentName ::= <StringType>John H. Doe</StringType>
studentAge ::= <IntType>23</IntType>
END
Enables support for DER (Distinguished Encoding Rules) applications that encode encrypted signatures. When OSS.ENCODABLE is applied to a CHOICE, SEQUENCE, or SET component, that component will be represented as an open type. Also, the type of the component becomes a PDU and can be encoded independently of the CHOICE, SEQUENCE, or SET in which it was embedded. By default, all components within a CHOICE, SEQUENCE, or SET are represented using their normal forms.
--<OSS.ENCODABLE [absoluteReference]>--
When specified globally, this directive requires an absolute reference to the targeted CHOICE, SEQUENCE, or SET component. When specified locally, this directive does not take any arguments and affects only the type that it is placed next to.
An encoded type to which the directive is applied will be skipped while decoding the PDU, so possible errors in it might be not reported.
Do not apply the OSS.ENCODABLE directive to a tagged type.
This directive does not work when PER or XML is in use.
OSS.ENCODABLE is applied at the local level in the following syntax:
--<OSS.ENCODABLE Module.A.data>--
Module DEFINITIONS ::= BEGIN
A ::= SEQUENCE {
id [0] INTEGER,
data [1] OCTET STRING
}
a A ::= { id 10, data '123456789ABCDEF'H }
END
Passing the syntax through ASN-1Step with this command
asn1step filename -listPduIdentifiers
generates the following:
ASN1STEP: List of valid PDU numbers and associated PDU names:
1 A
2 A-data-encodable
Note that a separate PDU tag was generated for the type marked with the OSS.ENCODABLE directive.
BOOLEAN types are encoded as numeric values of 0 and 1, instead of "true" and "false", when a GLOBAL-DEFAULTS MODIFIED-ENCODINGS encoding instruction is present. This is useful for
--<OSS.ExerNumericBoolean [absoluteReference]>--
absoluteReference refers to the affected type.
In the following example, the value p0 is encoded as <Presence>0</Presence> and not as <Presence>absent</Presence>:
--<OSS.ExerNumericBoolean Test.Presence>--
Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
Presence ::= BOOLEAN
p0 Presence ::= FALSE
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
TEXT Presence:false AS "absent"
TEXT Presence:true AS "present"
END
Enables or disables decoder support for the rules of extensibility, which state that when decoding a PDU all elements of a SET or SEQUENCE whose tags are not defined in the input abstract syntax must be silently ignored.
--<OSS.EXTENSIBLE [absoluteReference]>--
--<OSS.INEXTENSIBLE [absoluteReference]>--
When specified globally, these directives can take an absolute reference that refers to the affected BIT STRING, SEQUENCE, or SET type. If specified globally without an absolute reference, the OSS.EXTENSIBLE and OSS.INEXTENSIBLE directives determine how the decoder handles extensible elements. When specified locally, these directives do not take any arguments and affect only the type they are placed next to.
The OSS.EXTENSIBLE directive functions the same as the ASN.1 formal extension marker ("..."). You can use either the directive or the extension marker, but not both.
This example shows global and local use of the directives||; the local OSS.INEXTENSIBLE directive overrides the global OSS.EXTENSIBLE directive for Sample1.Name2.
--<OSS.EXTENSIBLE>--
Sample DEFINITIONS EXPLICIT TAGS ::= BEGIN
Name ::= SEQUENCE {
a INTEGER,
b BIT STRING
} --<PDU>--
NameI ::= Name --<INEXTENSIBLE>--
END
A Name type value that contains an unknown extension
Name.xer: <Name> <a>10</a> <b>011</b> <c>TRUE</c> </Name>
will be successfully decoded using the following command:
asn1step filename -decode Name Name.xer
Output
ASN1STEP: Decoding PDU #1 from file 'Name.xer':
Name SEQUENCE
a INTEGER [length = 2]
10
b BIT STRING [length = 3]
0x60
Total encoded length = 47
<Name> <a>10</a> <b>011</b> <c>TRUE</c> </Name>
Successfully decoded 47 bytes.
rec1value Name ::=
{
a 10,
b '011'B
}
However, decoding of the similar NameI type value will fail:
asn1step filename -decode NameI NameI.xer
Output
ASN1STEP: Decoding PDU #2 from file 'NameI.xer':
NameI SEQUENCE
a INTEGER [length = 2]
10
b BIT STRING [length = 3]
0x60
D0157E: Expecting value for a component of SET / SEQUENCE / CHOICE but XML tag
name does not match any component identifier: 'c'; check field 'b' (type:
BIT_STRING) of PDU #2 'NameI' at line 1 position 32.
10 011 TRUE
D0157E: Expecting value for a component of SET / SEQUENCE / CHOICE but XML tag
name does not match any component identifier: 'c'; check field 'b' (type:
BIT_STRING) of PDU #2 'NameI' at line 1 position 32.
S0012E: Decoding of PDU #2 failed with the return code '5'.
The local OSS.INEXTENSIBLE directive overrides the global OSS.EXTENSIBLE directive.
The OSS.INEXTENSIBLE directive is implied.
Affects how unknown values of extensible CHOICE types with a final XER USE-TYPE encoding instruction are decoded. Each unknown value contains the xsi:type attribute with an unrecognized value.
--<OSS.ExtensibleUseType>--
By default, the CHOICE data described above is decoded as data that matches the first alternative; all unknown elements or attributes are ignored. When OSS.ExtensibleUseType is present, the decoder treats such data as an unknown extension rather than a value of the first CHOICE alternative. The entire XML sub-element that matches the unknown extension is preserved in the special "unknown alternative" field by the decoder and can be safely re-encoded.
ASN.1 specification
Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
T ::= [USE-TYPE] CHOICE {
base SEQUENCE {i INTEGER},
e1 SEQUENCE {i INTEGER, b BOOLEAN},
...
} --<ExtensibleUseType>--
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
GLOBAL-DEFAULTS CONTROL-NAMESPACE
"http://www.w3.org/2001/XMLSchema-instance" PREFIX "xsi"
END
For the following XML document
<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4"> <i>1</i> <j>2</j> </T>
the decoder produces the following results:
Successfully decoded in 101 bytes.
rec1value T ::= base :
{
i 1
}
ASN1STEP: Re-encoding of 'value' of the PDU #1:
Encoding to the file 'T.exer.exer' using EXER encoding rule...
Encoded successfully in 58 bytes:
<?xml version="1.0" encoding="UTF-8"?>
<T>
<i>1</i>
</T>
Successfully decoded in 101 bytes. rec1value T ::= <unknown> ASN1STEP: Re-encoding of 'value' of the PDU #1: Encoding to the file 'T.exer.exer' using EXER encoding rule... Encoded successfully in 140 bytes: <?xml version="1.0" encoding="UTF-8"?> <T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4"> <i>1</i> <j>2</j> </T>
Instructs ASN-1Step to generate ordered values for a type, identified by absolute reference, when the -generateMessages option is specified. Optional parameters specify custom minimum and/or maximum limits on the values of the ASN.1 type properties, specified in the second column of the Table below. If one or both parameters are omitted, the limits from the -randomLimits option for the same ASN.1 property are used; otherwise, the global limits from the third column of the Table below are used.
Values of types marked with the OSS.GenOrderedValues directive are indexed sequentially and generated starting from the lower limit, then the lower limit plus 1, and ending with the lower limit plus the minimum between the maximum number of messages and the upper limit. The global index that starts from 0 is used to index values of all types that are marked with the OSS.GenOrderedValues directive. If the total number of values for a given type is less than the requested number of unique messages to be generated, a value corresponding to the lower limit is selected again while indices into the list of values for other types may continue to increase in an attempt to generate the requested number of unique messages.
If a type marked with the OSS.GenOrderedValues is constrained, values that satisfy constraints are selected from the range specified in the directive or assumed by default. If a current value of the global index results in a value of one of the marked types that violates constraints, which results in an invalid PDU message, ASN-1Step tries to generate a valid PDU value by increasing the global index by one, and so on until the next valid PDU message is created. Because the global index is common for values of all marked types, this may result in some missing valid values, which correspond to the skipped global indices, for other marked types. In some cases, when a PDU type is complex enough, those missed values may still be included in other generated messages if you increase the number of attempts to generate unique messages.
If a type is constrained with single values only, values are sequentially selected from the list of constraining single values. In this case, limits specified in the directive are ignored.
--<OSS.GenOrderedValues absoluteReference [minLimit[,maxlimit]]>--
absoluteReference refers to a type whose value generation is customized by the directive. See the list of supported ASN.1 types and their properties in the Table below. minLimit and maxLimit are integer numbers.
The following table includes the list of the supported ASN.1 type properties and their default value limits that will be used when one or both parameters are omitted in the directive and the -randomLimits option for the same ASN.1 property was not specified.
| ASN.1 Type | Property | Value Range Description and Default Values |
|---|---|---|
| BIT STRING | Length in bits | Specifies the limits on the number of bits in bstring values with the default range between 0 and 16. |
| CHOICE | Index of the alternative | Specifies the limits on the chosen alternative index in CHOICE type values with the default range between 0 and the number of alternatives minus 1. |
| ENUMERATED | Index of the enumerator | Specifies the limits on the enumerator index in ENUMERATED type values with the default range between 0 and the number of enumerators minus 1. |
| INTEGER | Integer value | Specifies the limits on integer values with the default range between -4096 and 4096. |
| OCTET STRING | Length in octets | Specifies the limits on the number of octets in bstring values with the default range between 0 and 16. |
| SET OF and SEQUENCE OF | Number of components | Specifies the limits on the number of component values with the default range between 0 and 4. |
| Restricted character strings | Length in characters | Specifies the limits on the number of characters in cstring values with the default range between 0 and 16. |
| Types with TableConstraint or ComponentRelationConstraint | Index of the constraining information object | Specifies the limits on the information object index in the constraining information object set to be selected in values of the type with the default range between 0 and the number of information objects minus 1. |
Values of ASN.1 types that are not marked with the OSS.GenOrderedValues directive or that are marked but their built-in types are not included in the first column in the above Table, and values of the ASN.1 properties of the included built-in types that are not included in the second column, are randomly generated based on global settings and on the -randomLimits settings, if specified, or have fixed values specified in the third column of the Table in the -generateMessages section if the -noRandomLimits option is specified.
The limits that are used in ordered value generation for types marked with the OSS.GenOrderedValues directive are determined as follows:
--<OSS.GenOrderedValues Mod.SeqType.enumer 0,1>--
--<OSS.GenOrderedValues Mod.SeqType.integ -1,1>--
Mod DEFINITIONS ::= BEGIN
SeqType ::= SEQUENCE {
enumer ENUMERATED { one, two, three },
integ INTEGER (-2..2)
}
END
Use the following command to generate 6 unique JSON messages with ordered values between one and two for the enumer field and ordered values -1, 0, 1 for the integ field:
asn1step input.asn -json -generateMessages SeqType,6
Instructs ASN-1Step to generate random values for a type, identified by absolute reference, when the -generateMessages option is specified. Optional parameters specify custom minimum and/or maximum limits on the values of the ASN.1 type properties, specified in the second column of the Table included in the OSS.GenOrderedValues section. If one or both parameters are omitted, the limits from the -randomLimits option for the same ASN.1 property are used; otherwise, the global limits from the third column of the Table from the OSS.GenOrderedValues directive section are used.
--<OSS.GenRandomValues absoluteReference [minLimit[,maxlimit]]>--
absoluteReference refers to a type whose value generation is customized by the directive. See the list of supported ASN.1 types and their properties in the Table from the OSS.GenOrderedValues directive section. minLimit and maxLimit are integer numbers.
Values for ASN.1 types that are not included in the first column of the mentioned Table, and values of the included built-in types whose ASN.1 properties are not included in the second column, are randomly generated based on global settings and on whether the -randomLimits and/or -noRandomLimits options are specified.
The limits that are used in random value generation for types marked with the OSS.GenRandomValues directive are determined as follows:
--<OOSS.GenRandomValues Mod.SeqType.enumer 2>--
--<OSS.GenRandomValues Mod.SeqType.integ -1>--
Mod DEFINITIONS ::= BEGIN
SeqType ::= SEQUENCE {
enumer ENUMERATED { zero, one, two, three },
integ INTEGER (-20..1)
}
END
Use the following command to generate 6 unique JSON messages with random values between zero, one, and two for the enumer field and between -1, 0, 1 for the integ field:
asn1step input.asn -json -generateMessages PduId,15 -noRandomLimits
Sets a special representation for integers whose size not supported by the operating system in use. By default, INTEGER types are represented as machine-dependent integers.
--<OSS.HUGE [absoluteReference]>--
When specified globally, absoluteReference refers to an INTEGER that requires the HugeInteger representation. When specified locally, OSS.HUGE takes no operands and affects only the type it is placed next to.
The HugeInteger representation consists of a series of octets containing the integer in binary format.
NOTE: HUGE INTEGER values are printed as OCTET STRING values.
HugeInt DEFINITIONS ::= BEGIN
A ::= INTEGER --<HUGE>--
END
For the ASN.1 notation above, the XER encoding of the big INTEGER value 123456789101112 (which does not fit a 64-bit integer) can be decoded successfully:
ASN1STEP: Decoding PDU #1 from file 'A.xer': <A>123456789101112</A> Successfully decoded in 22 bytes. rec1value A ::= '7048860F3A38'H
Identifies those types or components for which constraint checking should be disabled. The directive turns off all constraint checking for the type, which includes checking the default permitted alphabet for character strings. For ENUMERATED types, OSS.NoConstrain disables subtype constraints but does not disable enumerator validation. By default, constraint checking is turned on.
--<OSS.NoConstrain [absoluteReference]>--
When specified globally, absoluteReference refers to an ASN.1 type with a defined constraint. OSS.NoConstrain cannot be specified locally.
OSS.NoConstrain has no effect if -constraint is explicitly specified, except in the following situations:
All constraints for S are disabled in the following example. However, if the OSS.NoConstrain directive is omitted then the "asn1step filename -encodeValue badval" command prints out a message about constraint violation.
--<OSS.NoConstrain Module.S>--
Module DEFINITIONS ::= BEGIN
S ::= INTEGER (1..10 | 300)
END
In this example, PrintableString abc is passed without issuing a constraint violation error. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because it is composed of types that have OSS.NoConstrain applied.
--<OSS.NoConstrain Mod.ABConly>--
--<OSS.NoConstrain Mod.ShortString>--
--<OSS.PDU>--
Mod DEFINITIONS ::= BEGIN
ABConly ::= PrintableString (FROM ("A" | "B" | "C"))
abc ABConly ::= "The wrong string"
ShortString ::= PrintableString (SIZE(1 | 3 ))
shStr ShortString ::= "The long string"
ShortABCs ::= PrintableString (ABConly INTERSECTION ShortString)
shABC ShortABCs ::= "ABCDD"
END
The OSS.DEFAULTVALUE and OSS.NODEFAULTVALUE directives inform ASN-1Step whether items with the ASN.1 DEFAULT tag shall be handled as if they have the OPTIONAL tag instead. By default, OSS.DEFAULTVALUE is implied; types with the DEFAULT tag use the specified default value when absent from the encoding.
--<OSS.DEFAULTVALUE [absoluteReference]>--
--<OSS.NODEFAULTVALUE [absoluteReference]>--
When specified globally, absoluteReference can be present and refers to an ASN.1 type with a DEFAULT tag. When specified globally without an operand, these directives affect all types with the DEFAULT tag. When specified locally, the directives take no operands and affect only the types they are placed next to.
In general, you can specify a global OSS.NODEFAULTVALUE and then apply OSS.DEFAULTVALUE with absolute references for particular fields.
--<OSS.NODEFAULTVALUE Module.DataCard.a>--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
a [0] BOOLEAN DEFAULT TRUE,
b [1] BOOLEAN DEFAULT TRUE,
c [2] BOOLEAN
}
dataCard DataCard ::= { c FALSE }
END
After executing the following command
asn1step filename -encodeValue dataCard -cxer -noconstr
the following is printed. Note that a is represented as an OPTIONAL component because OSS.NODEFAULTVALUE is applied to it. On the other hand, b is still handled as a component with a default value, so it is present in the encoding because it is specified by the CXER encoding rules.
ASN1STEP: Encoding of valuereference 'dataCard' for PDU #1:
Encoding to the file 'dataCard.cxer' using CXER encoding rule...
DataCard SEQUENCE
b BOOLEAN [length = 7]
TRUE
c BOOLEAN [length = 8]
FALSE
Total encoded length = 50
Encoded successfully in 50 bytes:
<DataCard><b><true/></b><c><false/></c></DataCard>
Indicates whether an ASN.1 type can be sent or received as a protocol data unit. By default, unreferenced types (defined types not referenced by other types) are considered PDUs and can be encoded and decoded as complete units.
--<OSS.PDU [absoluteReference]>--
--<OSS.NOPDU [absoluteReference]>--
When specified globally, absoluteReference specifies the ASN.1 components that the directive will be applied to. When specified globally without an operand, the OSS.PDU and OSS.NOPDU directives set the default for all types within their scope. When specified locally, these directives take no operands and affect only the type they are placed next to.
The OSS.PDU and ASN1.PDU directives only affect types contained in root modules. To treat all input modules as root modules, either specify the -root compiler option (when compiling your ASN.1 syntax) or include the global OSS.ROOT directive in your ASN.1 specification.
--<OSS.PDU Module.NameString>--
Module DEFINITIONS ::= BEGIN
MiddleAgeClubCard ::= SEQUENCE {
name NameString,
phoneNumber PhoneString,
age AgeInt
}
NameString ::= IA5String (SIZE (40))
PhoneString ::= NumericString (SIZE (15)) --<PDU>--
AgeInt ::= INTEGER (45..54)
END
After passing the above notation through ASN-1Step with the command
asn1step filename -listPduIdentifiers
the following is generated:
ASN1STEP: List of valid PDU numbers and associated PDU names:
1 MiddleAgeClubCard
2 NameString
3 PhoneString
Notice how AgeInt is not marked to be a PDU, since it is referenced in the MiddleAgeClubCard SEQUENCE and it does not have a PDU directive applied to it.
Identifies the ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. Also, non-root modules exist only to supply external references to root modules. By default, the last ASN.1 input file specified on the command line contains the root module.
--<OSS.ROOT [moduleName[{objectIdentifier}]
[moduleName[{objectIdentifier}] ...]>--
OSS.ROOT can only be specified globally and takes one or more operands to identify ASN.1 modules. The operand can be a module reference (moduleName), or a module reference followed by a built-in objectIdentifier value. If no operands are provided, all input modules are considered root modules.
common.asn:
--<OSS.ROOT Common>--
Common DEFINITIONS ::= BEGIN
EXPORTS NameString,PhoneString,AgeInt;
IMPORTS;
NameString ::= IA5String
PhoneString ::= NumericString
AgeInt ::= INTEGER
END
application.asn:
Module DEFINITIONS ::= BEGIN
EXPORTS;
IMPORTS NameString,PhoneString,AgeInt FROM Common;
MiddleAgeClubCard ::= SEQUENCE {
name NameString,
phoneNumber PhoneString,
age AgeInt
}
mCard MiddleAgeClubCard ::= {name "test",phoneNumber "123",age 22}
END
When the common.asn file contains OSS.ROOT, the command
asn1step common.asn application.asn -listPduIdentifiers
prints out the following:
1. NameString 2. PhoneString 3. AgeInt
But if OSS.ROOT is missing then the output will be as follows:
1. MiddleAgeClubCard
Instructs the E-XER decoder to preserve wildcard contents in the decoded C value; allows checking of the digital signature of a wildcard after decoding.
--<OSS.SelfCompleteWildcard [absoluteReference>]--
OSS.SelfCompleteWildcard can be applied to types with a final XER ANY-ELEMENT encoding instruction. It can be specified for a single type, for a module, or globally.
When OSS.SelfCompleteWildcard is applied, the following is true:
If the wildcard contents were normalized according to the W3C Canonical XML specification, the decoded wildcard value will match the original XML value, which enables post-decoding validation of the wildcard's digital signature.
You can use OSS.SelfCompleteWildcard to speed up E-XER decoding of wildcards if you know in advance that they self-complete and do not use namespace or entity declarations from the outer XML document.
--<OSS.SelfCompleteWildcard M.Root.w>--
M DEFINITIONS XER INSTRUCTIONS ::= BEGIN
Root ::= SEQUENCE {
w [ANY-ELEMENT] UTF8String (CONSTRAINED BY {}) }
ENCODING-CONTROL XER
GLOBAL-DEFAULTS MODIFIED-ENCODINGS
NAMESPACE ALL AS "urn:Root" PREFIX "r"
END
For the following XML document, where n1:wildcard is an element wildcard
<Root xmlns="urn:Root"> <n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/> </Root>
the decoder produces what is literally the original:
<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>
Without OSS.SelfCompleteWildcard, the decoder produces what is the wildcard value by default:
<n1:wildcard xmlns:n2="urn:n2" xmlns:n1="urn:n1" xmlns="urn:Root" n2:at2="2" n1:at1="1"/>
Determines the internal representation of the ASN.1 INTEGER type. On a typical system, OSS.LONGLONG calls for a 64-bit integer. By default, when no subtype constraints are present, an ASN.1 INTEGER type is represented as a 32-bit C integer type. When a subtype constraint is present, the ASN-1Step chooses the smallest representation able to carry all required values.
--<OSS.LONGLONG [absoluteReference]>--
When specified globally, only INTEGERs without subtype constraints are affected. absoluteReference refers to an ASN.1 INTEGER type. When specified globally without an absolute reference, OSS.LONGLONG sets the default for all INTEGER types within its scope. When specified locally, the directive does not take any arguments and affects only the type it is placed next to. It also overrides any choices that ASN-1Step would have made based on a subtype constraint.
--<OSS.LONGLONG>-- Module DEFINITIONS ::= BEGIN LONGLONGInt ::= INTEGER llint LONGLONGInt ::= 223372036854775807 END
The ASN.1 notation above illustrates the global use of the OSS.LONGLONG directive. The XER encoding of the 223372036854775807 big INTEGER value (which does not fit a 32-bit integer) can be decoded successfully:
ASN1STEP: Decoding PDU #1 from file 'A.xer': <LONGLONGInt>223372036854775807</LONGLONGInt> Successfully decoded in 22 bytes. rec1value LONGLONGInt ::= 223372036854775807
Gives you more control over the XML stylesheets produced by ASN-1Step. This directive instructs ASN-1Step to generate a separate XML stylesheet with your specified filename for any PDU. By default, unless the -xsl option is specified, stylesheets are not produced. When -xsl is specified, a stylesheet for each input PDU is generated into a separate file with a name derived from that PDU.
--<OSS.Stylesheet [absoluteReference [OptionalNewName.xsl]]>--
absoluteReference refers to any PDU in the input ASN.1 that you want to generate a separate XML stylesheet for. When absoluteReference is not specified, a stylesheet is generated for every PDU in the input. OptionalNewName is an optional argument that allows you to specify a new name for the stylesheet that will be generated.
Stylesheets can be used to make the XER output of the encode() method more visually appealing when viewed in a web browser.
The OSS.Stylesheet directive can appear anywhere whitespace is allowed; however, the OSS prefix and an absolute reference is required.
For the following syntax, two separate stylesheet files are generated: StringType.xsl and AnotherNameForInt.xsl. Each contains default browser style information for their respective PDUs.
--<OSS.Stylesheet XModule.StringType>--
--<OSS.Stylesheet XModule.IntType "AnotherNameForInt.xsl">--
XModule DEFINITIONS ::= BEGIN
StringType ::= UTF8String
IntType ::= INTEGER
studentName ::= <StringType>John H. Doe</StringType>
studentAge ::= <IntType>23</IntType>
END
Disables printing of specific informatory and warning messages. This is useful when working with abstract syntaxes that are known to contain specifications that do not comply with the ASN.1 standard. By default, informatory and warning messages are suppressed when -noRelaxedMode is turned on.
--<OSS.SUPPRESS messageID[, messageID ...]>--
messageID identifies the message to be suppressed. It can be the full message identifier, such as A0178W, or only its numeric portion: 178. OSS.SUPPRESS can only be used globally and can take one or more messageIDs.
In the following example, message A0178W warns that the first digit of a number in a module definition should be non-zero:
--<OSS.SUPPRESS A0178W>--
Sample DEFINITIONS ::= BEGIN
Age ::= INTEGER
legalAge Age ::= 021
END
The directive's only effect is to suppress the following warning message:
"filename.asn", line 4 (Sample): A0178W: The first digit should not be zero unless the number is a single digit.
legalAge Age ::= 021
^
C0043I: 0 error messages, 1 warning message and 0 informatory messages issued.
Instructs ASN-1Step to skip extra trailing elements in a SET OF or SEQUENCE OF type, which can speed up decoding of certain large PDUs.
--<OSS.Truncate absoluteReference maxlimit>--
When specified globally, absoluteReference refers to the SET OF or SEQUENCE OF type for which all elements with an index greater than maxLimit should be ignored. maxLimit is an integer number between 1 and 16384. The OSS.Truncate directive cannot be specified locally.
--<OSS.Truncate Mod.Records 3000>--
Mod DEFINITIONS ::= BEGIN
Records ::= SEQUENCE OF Employee
Employee ::= SEQUENCE {
name IA5String,
position IA5String,
salary REAL
}
END
The notation above demonstrates use of the OSS.Truncate directive. The decoder will only process 3000 elements of the Records type. This type of truncation is useful when you are sure that
Allows ASN-1Step to ignore some fields of ASN.1 SEQUENCE or SET types. The OSS.USERFIELD directive instructs the encoder to skip the field. It instructs the decoder to perceive an error upon receipt of a value which appears in the same context and has the same tag as the user field. By default, no user field is generated.
--<OSS.USERFIELD [absoluteReference]>--
When specified globally, absoluteReference refers to a field in an ASN.1 SET or SEQUENCE type. When specified locally, this directive takes no operands and only affects the type that it is placed next to.
User fields can only appear in ASN.1 SEQUENCE or SET types and must be marked as either OPTIONAL or DEFAULT.
User fields are subjected to the same ASN.1 restrictions as non-user fields.
Some user fields declared as OPTIONAL might not have bit masks generated for them.
--<OSS.USERFIELD Module.DataCard.controlGroup>--
Module DEFINITIONS ::= BEGIN
DataCard ::= SEQUENCE {
controlGroup BOOLEAN DEFAULT FALSE ,
name PrintableString,
numberOfCars INTEGER (1..5)
}
dataCard DataCard ::= {controlGroup TRUE,name "John",numberOfCars 1}
END
When the above notation is passed through ASN-1Step using the
asn1step <filename> -per -test
command, the following is printed during encoding:
value DataCard ::=
{
name "John",
numberOfCars 1
}
...
Total encoded length = 6.0
PDU successfully encoded, in 6 bytes:
044A6F68 6E00
and decoding:
value DataCard ::=
{
name "John",
numberOfCars 1
}
The encoder and decoder behave as if the controlGroup field above was not present.
This documentation applies to release 10.5 and later of ASN-1Step®.
Copyright © 2024 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of ASN-1Step is associated with a specific license and related unique license number. That license determines, among other things, what functions of ASN-1Step are available to you.