Getting Started

Introduction

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:

• If you are using the trial version of Command Line ASN-1Step, use the -demo option to experience this tool's capabilities. The trial version of Command Line ASN-1Step does not allow you to load custom ASN.1 specifications but lets you work with built-in ASN.1 specifications.
• The sample files for Windows platforms are installed in the folder pointed to by the %ALLUSERSPROFILE% environment variable.
  

  By default, on Windows 7 and later, the samples are installed in

  C:\ProgramData\OSS Nokalva\asn1step\<platform name>\<version number>\samples

  The ASN-1Step samples are also available in the asn1step.samples.zip file in

  ..\Program Files\OSS Nokalva\asn1step\<platform name>\<version-number>\samples

  You can extract these samples in any folder of your choice and run them from there.

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.

Check ASN.1 Syntax

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.

Encode a Value to a File

This exercise shows how to create a binary or text file containing BER, DER, PER, UPER, OER, C-OER, 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"

Command Details

The general structure of a command to encode a value is:

asn1step input.asn
output.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] [-hexChars / -binChars]  -encodeValue <valuereference>

Where

• input.asn is the text file containing your ASN.1 specification.
• output.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] is the text or binary file to which the encoded value is written.
  The filename extension (e.g., .ber and .per) of the output file you specify determines which encoding rules are used to encode the value. For example, a .ber extension specifies that the Basic Encoding Rules (BER) will be used. Thus, the filename extension of the output file you specify is very important. However, the complete output filename is optional and can be replaced by an encoding rules option. For example, the following command is an alternative to the one at the beginning of this section:

  asn1step sample.asn -encodeValue myName -ber -hex

  By 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.
  Warning: Output filenames should be carefully chosen. ASN-1Step overwrites any files that have the same name as the specified output file. So, if you specify sample.ber as the output filename, any file in the working directory of the asn1step executable named sample.ber will be overwritten.
• -hexChar is an optional argument that instructs ASN-1Step to write the encoding to a text file in hexadecimal format.
• -binChar is an optional argument that instructs ASN-1Step to write the encoding to a text file in binary format.
  NOTE: If neither -hexChar nor -binChar is specified, then the encoding is written to a binary file as a sequence of bits.
• -encodeValue instructs ASN-1Step to encode a value (and not decode one). Whenever -encodeValue is specified, the value reference in the input ASN.1 specification to be encoded must also be specified.

List All Value References in an ASN.1 Specification

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.

Encode Values in a Text File

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.

Command Details

The general structure of a command to encode a value is:

asn1step input.asn
output.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] [-hexChars / -binChars]  -encodeValue <[pduId,]inputValueFile.txt>

Where

• pduId is the PDU identifier obtained from the table of all available PDU numbers and names that is displayed when you specify the -listPduId option. It can be omitted if the input text file contains one or more ASN.1 values in the form

  <valueName> <PduTypeName> ::= <value_notation>

• inputValueFile.txt is the text file containing one or more ASN.1 values in the form

  <valueName> <PduTypeName> ::= <value_notation>

  or just

  <value_notation>

• Other parameters are the same as outlined previously.

Decode a Value from a File

This exercise shows how to read a binary or text file containing BER, DER, PER, UPER, OER, C-OER, 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"

Command Details

The general structure of a command to decode a value is:

asn1step input.asn
input.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] [-hexChars / -binChars]  -decodePdu <PDU-name | PDU-number | 0
      [-ber/-cer/-der/-per/-uper/-oer/-coer/-xer/-cxer/-exer/-json/-asn1Value/-csv]>

Where

• input.asn is the text file containing your ASN.1 specification.
• input.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] is the text or binary file from which the encoded value is read.
  The filename extension (e.g., .ber and .per) of the input encoding file you specify determines which encoding rules are used to decode the value. For example, a .per extension specifies that the Packed Encoding Rules (PER) will be used. Thus, the filename extension of the input encoding file you specify is very important.
• -hexChar is an optional argument that informs ASN-1Step that input.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] is a text file that contains hexadecimal characters representing a BER, DER, PER, UPER, OER, C-OER, XER, CXER, E-XER, JSON, or CSV encoding.
• -binChar is an optional argument that informs ASN-1Step that input.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] is a text file that contains binary characters representing a BER, DER, PER, UPER, OER, C-OER, XER, CXER, E-XER, JSON, or CSV encoding.
  NOTE: If neither -hexChar nor -binChar is specified, then input.[ber/cer/der/per/uper/oer/coer/xer/cxer/exer/json/csv] is interpreted as a binary file.
• -decodePdu instructs ASN-1Step to decode a PDU (and not encode one). Whenever -decodePdu is specified, the PDU number or name of the ASN.1 type to be decoded must also be specified. However, the -decodePdu option can be omitted (except when using the Packed Encoding Rules), since it is the implied default. Alternatively, you can specify a zero ('0') argument immediately after the -decodePdu option to instruct ASN-1Step to automatically detect the PDU type of the input encoding.

Re-encode with Different Encoding Rules

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

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.

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

• Trying to decode invalid encoded data.
• Trying to decode from a binary input file but specified -hexChar or -binChar by mistake.
• Trying to decode from a text file but forgot to specify -hexChar or -binChar.
• Trying to decode a BER, DER, PER, UPER, OER, C-OER, XER, CXER, E-XER, JSON, or CSV encoding, but the input-encoding filename has the wrong extension (e.g., .ber for a PER encoding).

Test Encoding and Decoding of Value References

In this exercise, ASN-1Step will automatically perform the following steps and display the results without using any additional files:

1. Compile the sample ASN.1 syntax.
2. Retrieve a list of all value references whose types are PDUs from the sample ASN.1 specification.
3. Encode each value reference using the selected encoding rules.
4. Display the trace from the encode operation and the resulting encoded message in
   • Hexadecimal format for the binary encoding rules: BER, DER, CER, PER, UPER, OER, and C-OER.
   • XML format for XER, CXER, and E-XER.
   • JSON format for JSON encoding rules.
   • CSV format for CSVs.
5. Decode the encoded message from the previous step and display the trace.

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 sample encodings and decodings, while the -ber/-cer/-der/-per/-uper/-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.

---