Contents
After installing the ASN-1Step package, go to the samples directory. On the command line, enter:
cd samples
Do a directory listing and you will see the basic and standards subdirectories. Start with README.TXT in the basic subdirectory to learn how to operate the ASN-1Step program with a simple ASN.1 specification, PersonnelRecord.asn.
NOTES:
By default, on Windows 8.1 and later, the samples are installed in
C:\ProgramData\OSS Nokalva\asn1step\<platform name>\<version number>\samples
Following are some exercises that use the simple ASN.1 specification below to demonstrate the main operations you can do with Command Line ASN-1Step. To run these exercises, save the following ASN.1 syntax as a file named sample.asn in the samples directory.
sample.asn:
Module DEFINITIONS ::= BEGIN ASCII ::= IA5String myName ASCII ::= "OSS" END
To fully benefit from the ASN-1Step program you need to understand basic ASN.1 type and value notation. In the syntax above, the PDU (i.e., a type that can be encoded/decoded as an independent unit) is called ASCII. The value available for encoding/decoding is called myName.
This exercise shows how to perform a syntax check on an ASN.1 specification. To conduct a syntax check on sample.asn, issue the following command:
asn1step -pedantic -verbose sample.asn
After printing ASN-1Step license information, the result will be similar to the following:
C0284I: Syntax checking file 'sample.asn'. C0285I: Global checking abstract syntax. C0043I: 0 error messages, 0 warning messages, and 3 informatory messages issued.
The last message indicates that the input file successfully passed the syntax check.
If, instead, you received the following error message:
ASN-1STEP: Unable to open ossinfo file, "/asn1step/ossinfo"
Set the OSSINFO environment variable to point to its location:
export OSSINFO=<path-of-directory-containing-ossinfo-file> or setenv OSSINFO <path-of-directory-containing-ossinfo-file>
You must use the ossinfo file sent to you for ASN-1Step. Do not try to use an ossinfo file from a previous installation of the OSS ASN.1 Tools with your new installation of ASN-1Step.
If an error is returned when syntax checking an ASN.1 specification, you can look the error up in ASN-1Step Errors, OSS ASN.1 Compiler Errors, or OSS ASN.1 Runtime Errors to see possible causes and solutions.
Look at the sixth character of the Syntax Checker message code (e.g., C0284I) to determine whether the message issued was an error, warning, or informatory message. If the sixth character is E or S, the message points out a definite syntax error. If the sixth character is W, the message was issued to warn you of some oddity in your ASN.1 specification. Finally if the sixth character is I, the message merely informs you about something that might be of interest to you.
If warning and informatory messages are issued by the ASN-1Step syntax checker, this does not necessarily mean that there is a problem with your input ASN.1 specification. Warning and informatory messages are issued as a precautionary measure. You can turn off these messages by omitting -verbose and adding -noWarn to the command line.
This exercise shows how to create a binary or text file containing BER, DER, PER, UPER, OER, COER, XER, CXER, E-XER, JSON, or CSV encodings of a specified value reference. To create a text file containing the BER encoding of the myName value reference shown in sample.asn above, enter:
asn1step sample.asn sample.ber -hex -encodeValue myName
The result will be similar to the following:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: Encoding of valuereference 'myName' for PDU #1: Encoding to the file 'sample.ber' using BER encoding rule... ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS" Encoded successfully in 5 bytes: 16034F53 53
A small text file named sample.ber will have been created in the current directory. View the contents of this file with the following command:
more sample.ber
The following result
16034F53 53
is the hexadecimal representation of the encoding of
ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS"
The general structure of a command to encode a value is:
asn1step input.asn output.[ber/cer/der/per/uper/cper/cuper/oer/coer/xer/cxer/exer/json/csv] [-hexChars / -binChars] -encodeValue <valuereference|[pduId,]<inputValueNotationFile|inputPath>>
Where
asn1step sample.asn -encodeValue myName -ber -hexBy default, the output filename is derived from the encoding rules and the value reference sent for encoding. For the above command a text file named myName.ber will be produced.
The following command:
asn1step sample.asn -valueRefTable
lists all available value references in sample.asn:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: List of valid valuereferences and associated PDU numbers: 1 myName
In this case, the only available value reference is myName. If the input ASN.1 specification does not contain any value references available for encoding, none will be listed.
In addition to encoding value references specified directly in the input ASN.1 syntax, you can encode one or more values included in a separate text file whose name is passed to -encodeValue as a parameter. The file can contain one or more ASN.1 values in the form
<valueName> <PduTypeName> ::= <value_notation>
or just
<value_notation>
In the latter case, you must include a PDU identifier along with the text file name in the parameter passed to the -encodeValue option.
Example
sampleValueFile.txt:
sampleValueNotation ASCII ::= "OSS"
To create a text file containing the BER encoding for the value notation (that includes the PDU name) specified in sampleValueFile.txt for sample.asn shown above, simply enter:
asn1step sample.asn sample.ber -hex -encodeValue sampleValueFile.txt
The result should be the same sample.ber output previously generated for the encoding of the myName valuereference.
If you remove the assignment that includes the PDU name in sampleValueFile.txt as follows:
sampleValueFile.txt:
"OSS"
You must include the PDU identifier in the -encodeValue option so Asn-1Step knows the ASN.1 type of the value notation inside the file. The PDU identifier can be obtained from the table of all available PDU numbers and names in sample.asn.
Issue the command:
asn1step sample.asn -listPduId
The result will be similar to the following:
C0043I: 0 error messages issued, 0 warning or informatory messages issued. ASN1STEP: List of valid PDU numbers and associated PDU names: 1 ASCII
In this case, the only available PDU is ASCII which has a PDU number of 1.
To create a text file containing the BER encoding for the value specified in sampleValueFile.txt for sample.asn, enter:
asn1step sample.asn sample.ber -hex -encodeValue 1,sampleValueFile.txt
The result should be the same sample.ber output previously generated for the encoding of the myName valuereference.
The general structure of a command to encode a value is:
asn1step input.asn output.[ber/cer/der/per/uper/cper/cuper/oer/coer/xer/cxer/exer/json/csv] [-hexChars / -binChars] -encodeValue <[pduId,]inputValueFile.txt>
Where
<valueName> <PduTypeName> ::= <value_notation>
<valueName> <PduTypeName> ::= <value_notation>or just
<value_notation>
This exercise shows how to read a binary or text file containing BER, DER, PER, UPER, CPER, CUPER, OER, COER, XER, CXER, E-XER, JSON, or CSV encodings and display the corresponding decoded values in human-readable format. To decode the sample.ber text file that you created previously, issue the following command:
asn1step sample.asn sample.ber -hex -decodePdu ASCII
The result will be similar to the following:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: Decoding PDU #1 from file 'sample.ber': ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS" Successfully decoded 5 bytes. rec1value ASCII ::= "OSS"
The general structure of a command to decode a value is:
asn1step input.asn input.[ber/cer/der/per/uper/cper/cuper/oer/coer/xer/cxer/exer/json/csv] [-hexChars / -binChars] -decodePdu <PDU-name | PDU-number | 0>[,maxNum[,skippedNum]] [-ber/-cer/-der/-per/-uper/-cper/-cuper/-oer/-coer/-xer/-cxer/-exer/-json/-asn1Value/-csv]>
Where
The -decodePdu option allows you to re-encode an input encoding using a different set of encoding rules by specifying one of the available encoding rules options.
Example 1
asn1step sample.asn -decodePdu ASCII sample.ber -per -hex
The result will be similar to the following:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: Decoding PDU #1 from file 'sample.ber': ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS" Successfully decoded 5 bytes. rec1value ASCII ::= "OSS" ASN1STEP: Re-encoding of 'value' of the PDU #1: Encoding to the file 'sample.ber.per' using PER ALIGNED encoding rule... ASCII IA5String [length = 3.0] "OSS" Total encoded length = 4.0 Encoded successfully in 4 bytes: 034F5353
This command re-encodes the BER-encoded value in sample.ber using PER. By default, the output PER encoding is written to a file named sample.ber.per. You can use the -output option to specify another name for the output encoding file; if multiple input encoding files are specified, only the output file produced from the first input file will have its name affected.
Example 2
Create the inPath sub-directory and copy sample.ber there.
asn1step sample.asn -decodePdu ASCII -getFiles inPath,ber,hex -per -hex -putFiles outPath
The result will be similar to the following:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: Decoding PDU #1 from directory 'inPath': ASN1STEP: Decoding PDU #1 from file 'inPath/sample.ber': ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS" Successfully decoded 5 bytes. rec1value ASCII ::= "OSS" ASN1STEP: Re-encoding of 'value' of the PDU #1: Encoding to the file 'outPath/sample.ber.per' using PER ALIGNED encoding rule... ASCII IA5String [length = 3.0] "OSS" Total encoded length = 4.0 Encoded successfully in 4 bytes: 034F5353
This command reads all encoding files with the .ber extension from inPath, assuming that they have text hexadecimal format, inPath/sample.ber in our example, re-encodes BER-encoded values from each file using PER, and places PER-encoded messages in text files with hexadecimal format in the outPath directory which is created if it does not exist, outPath/sample.ber.per in our example. The command produces multiple output files for multiple input encoding files. You can specify a common name for the output files in the second parameter of the -putFiles option and an optional first file's number suffix. The output files are distinguished by underscore and a number suffix.
To display a table of all available PDU numbers and names in sample.asn, issue the command:
asn1step sample.asn -listPduId
The result will be similar to the following:
C0043I: 0 error messages issued, 0 warning and 0 informatory messages issued. ASN1STEP: List of valid PDU numbers and associated PDU names: 1 ASCII
In this case, ASCII is the only available PDU; it has a PDU number of 1. You can pass either the PDU name or number as the mandatory argument for -decodePdu. If the input ASN.1 specification does not contain any PDUs available for encoding, none will be listed.
If you receive error messages similar to the following when attempting to decode a PDU:
D0054S: PDU tag not recognized: [UNIVERSAL 17]. Decoding failed with return code = 5 D0054S: PDU tag not recognized: [UNIVERSAL 17].
Probable causes are
The -generateMessages option allows you to generate multiple ASN.1 values for a specified PDU using random initialization values for different nested ASN.1 types, encode them using a specified set of encoding rules, and save them in a single or multiple files.
Example 1
asn1step sample.asn -generateMessages ASCII,3 -ber -xer -randomLimits len,1,3
The result will be similar to the following:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: Generating up to 3 random unique messages for PDU #1: ASN1STEP: Creating decoded value #1... Encoding to the file 'ASCII_1.ber' using BER encoding rule... ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 1 "l" Encoded successfully in 3 bytes: 16016C Encoding to the file 'ASCII_1.xer' using XER encoding rule... ASCII IA5String [length = 1] "l" Total encoded length = 55 Encoded successfully in 55 bytes: <?xml version="1.0" encoding="UTF-8"?> <ASCII>l</ASCII> ASN1STEP: Creating decoded value #2... Encoding to the file 'ASCII_2.ber' using BER encoding rule... ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "qgi" Encoded successfully in 5 bytes: 16037167 69 Encoding to the file 'ASCII_2.xer' using XER encoding rule... ASCII IA5String [length = 3] "qgi" Total encoded length = 57 Encoded successfully in 57 bytes: <?xml version="1.0" encoding="UTF-8"?> <ASCII>qgi</ASCII> ASN1STEP: Creating decoded value #3... Encoding to the file 'ASCII_3.ber' using BER encoding rule... ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 2 "kl" Encoded successfully in 4 bytes: 16026B6C Encoding to the file 'ASCII_3.xer' using XER encoding rule... ASCII IA5String [length = 2] "kl" Total encoded length = 56 Encoded successfully in 56 bytes: <?xml version="1.0" encoding="UTF-8"?> <ASCII>kl</ASCII>
This command generates up to 3 unique ASN.1 values for PDU ASCII and encodes each value using BER and XER. The output BER and XER encodings are written to separate files with the names ASCII_1.ber, ASCII_2.ber, ASCII_3.ber, ASCII_1.xer, ASCII_2.xer, and ASCII_3.xer. The '-randomLimits len,1,3' part of the example limits the sizes of bit, octet, and character strings for unconstrained ASN.1 types between 1 and 3, inclusively.
Use the -putFiles option to change the output file location, specify a common file name prefix, and/or the first file number suffix for multiple files. For example, with the additional command line option '-putFiles outPath,myName,5', multiple files that contain a single encoded message are generated with the names outPath/myName_ 5.ber, outPath/myName_6.ber, outPath/myName_7.ber, outPath/myName_5.xer, outPath/myName_6.xer, and outPath/myName_7.xer.
Use the -output option to specify another name for the output encoding file where all encoded messages will be written to. For example, with the additional command line option '-output myName', two output files, myName.ber and myName.xer, are produced with 3 concatenated messages each.
In this exercise, ASN-1Step will generate CSV messages with all possible values of types for fields marked with the OSS.GenOrderedValues directive. Other fields will have fixed pre-defined values because the -noRandomLimits option is specified.
ASN.1 syntax in sample1.asn
--<OSS.GenOrderedValues Mod.PduType.enumer>-- --<OSS.GenOrderedValues Mod.PduType.choice>-- Mod DEFINITIONS ::= BEGIN PduType ::= SEQUENCE { enumer ENUMERATED { one, two, three }, integ INTEGER, choice CHOICE { alt1 BOOLEAN, alt2 NULL } } END
Issue the following command:
asn1step sample1.asn -generate PduType,7 -csv -noRandomLimits -output myName
Seven unique messages will be generated in the myName.csv file with fixed values for the integ (0), alt1 (FALSE), and alt2 (NULL) fields with different combinations of ordered values for the enumer and choice fields:
ASN1STEP: Generating up to 7 unique messages for PDU #1: ASN1STEP: Creating decoded value #1... Encoding to the file 'myName.csv' using CSV format... Global index for ordered value generation is '0'... Encoded successfully in 50 bytes: enumer,integ,choice_alt1,choice_alt2 one,0,FALSE, ASN1STEP: Creating decoded value #2... Encoding at the end of the file 'myName.csv' using CSV format... Global index for ordered value generation is '1'... Encoded successfully in 12 bytes: two,0,,NULL ASN1STEP: Creating decoded value #3... Encoding at the end of the file 'myName.csv' using CSV format... Global index for ordered value generation is '2'... Encoded successfully in 15 bytes: three,0,FALSE, ASN1STEP: Creating decoded value #4... Encoding at the end of the file 'myName.csv' using CSV format... Global index for ordered value generation is '3'... Encoded successfully in 12 bytes: one,0,,NULL ASN1STEP: Creating decoded value #5... Encoding at the end of the file 'myName.csv' using CSV format... Global index for ordered value generation is '4'... Encoded successfully in 13 bytes: two,0,FALSE, ASN1STEP: Creating decoded value #6... Encoding at the end of the file 'myName.csv' using CSV format... Global index for ordered value generation is '5'... Encoded successfully in 14 bytes: three,0,,NULL ASN1STEP: Creating decoded value #7... Encoding at the end of the file 'myName.csv' using CSV format... Global index for ordered value generation is '6'... Encoded successfully in 13 bytes: one,0,FALSE, 7 unique messages created and saved successfully.
In this exercise, ASN-1Step will automatically perform the following steps and display the results without using any additional files:
Issue the following command:
asn1step sample.asn -der -test
The result will be similar to the following:
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued. ASN1STEP: Running Encoder/Decoder test for valuereference 'myName' for PDU #1: ---------- Run 1 of the DER Encoder ---------- Flags passed: DEBUGPDU+AUTOMATIC_ENCDEC, NO BUFFER PROVIDED. Unencoded PDU... value ASCII ::= "OSS" Checking constraints... Constraints checking succeeded Tracing Information from the DER Encoder... ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS" PDU successfully encoded, in 5 bytes: 16034F53 53 ========== Run 1 of the DER Decoder ========== Flags passed: DEBUGPDU+AUTOMATIC_ENCDEC, NO BUFFER PROVIDED. Tracing Information from Decoder... ASCII IA5String: tag = [UNIVERSAL 22] primitive; length = 3 "OSS" PDU successfully decoded, in 24 bytes Decoded PDU... value ASCII ::= "OSS" Copying the Decoded PDU... Comparing the Original and Copied PDUs... Value comparison succeeded All values encoded and decoded successfully.
Note that the -test option instructs the ASN-1Step program to display traces from sample encodings and decodings, while the -ber/-cer/-der/-per/-uper/-cper/-cuper/-oer/-coer/xer/-cxer/-exer/-json/-csv options allow you to choose the encoding rules with which to conduct the test. You can specify more than one set of encoding rules or you can omit the encoding rules option entirely, in which case all the available encoding rules will be used one by one.
After you have completed the exercises in this section, you can find more advanced exercises in samples/standards.
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.