---
name: asn1-sdk
description: Guide users to compile ASN.1 specifications into source code for C, C++, Java, C#, and Go using the ASN.1 SDK CLI. Use when users ask how to create ASN.1 projects, configure compiler targets, generate code, or handle encoding/decoding with the generated runtime.
---

# ASN.1 SDK

A skill for helping users compile ASN.1 protocol specifications into source code using the ASN.1 SDK (`asndt`) — a command-line toolkit that generates C, C++, Java, C#, and Go code complete with runtime encoding/decoding support.

## When to Use

- User wants to compile ASN.1 modules into source code for any supported language
- User needs help creating or configuring an ASN.1 project (`asn1.avn`)
- User wants to clean generated output from a project
- User asks about compiler options, type mappings, or code generation features
- User wants to understand how to encode/decode data with the generated code
- User needs to activate a license or troubleshoot compilation

## Quick Start

### Requirements

- Java 17 or later
- A valid ASN Lab license key for each compiler target
- Target-language build tools (JDK, C compiler, C++ compiler, .NET SDK, Go toolchain)

### Installation

Unpack the SDK archive and use the `asndt` script:

```bash
unzip asn1-sdk-3.14.15.zip
export PATH=/path/to/asn1-sdk/bin:$PATH
asndt
```

The distribution contains `bin/asndt.sh` (Linux/macOS), `bin/asndt.bat` (Windows), core JARs in `lib/core/`, and compiler plugins in `lib/plugins/`.

### Activate a License

```bash
asndt license
```

Choose **Activate license**, select the compiler target, and paste the license key. Licenses are stored in `~/.asnsdk/license.avn` (Linux/macOS) or `%APPDATA%\asnsdk\license.avn` (Windows).

### Create and Compile a Project

```bash
asndt create MyProject        # Create project skeleton
asndt compile MyProject       # Compile ASN.1 sources
asndt clean MyProject         # Clean generated output
```

This creates `MyProject/asn1.avn`, `src/`, and `build/`. Place `.asn` files under `src/`, configure compiler targets in `asn1.avn`, then compile.

## Project Configuration (`asn1.avn`)

The project file uses ASN.1 Value Notation (AVN). Key top-level fields:

| Field | Purpose |
|-------|---------|
| `name` | Project name |
| `version` | Project version |
| `description` | Human-readable description |
| `source` | Directory containing `.asn` files (e.g. `"src"`) |
| `output` | Directory for generated output (e.g. `"build"`) |
| `options` | Shared compiler options (e.g. naming templates) |
| `compilers` | Enabled compiler targets and target-specific options |
| `dependencies` | Optional dependent ASN.1 projects |
| `scripts` | Optional project scripts |

### Shared Options

| Field | Type | Description |
|-------|------|-------------|
| `naming-template` | SEQUENCE OF string | Templates for anonymous types. Variables: `${memberName}`, `${parentName}`, `${moduleName}`. |

### Minimal Multi-Language Example

```asn1
{
    name "MyProject",
    version "0.1.0",
    description "Example ASN.1 project",
    source "src",
    output "build",
    compilers {
        {
            id "asnjc",
            language "java",
            options {
                output-folder "java"
            }
        },
        {
            id "asncpp",
            language "c++",
            options {
                output-folder "c++",
                cpp-standard cpp17,
                using-module-name-as-namespace TRUE
            }
        }
    }
}
```

## Supported Encoding Rules

All compiler targets support these encoding rules through a consistent API:

| Encoding Rule | Constant | Description |
|--------------|----------|-------------|
| Basic Encoding Rules | BER (0) | Tag-Length-Value encoding |
| Canonical Encoding Rules | CER (1) | BER with canonical form restrictions |
| Distinguished Encoding | DER (2) | BER with unique encoding restrictions |
| Unaligned Packed Encoding | UPER (3) | Bit-level encoding without octet alignment |
| Aligned Packed Encoding | APER (4) | Bit-level encoding with octet alignment |
| Octet Encoding Rules | OER (8) | Octet-aligned encoding optimized for speed |
| XML Encoding Rules | XER (16) | XML-based encoding |
| JSON Encoding Rules | JER (32) | JSON-based encoding |

Availability depends on the target language runtime.

## Compiler Targets

### Java (`asnjc`)

Generated types are Java classes in packages derived from module names. Add the `asnrt` JAR to your classpath.

**Key Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output-folder` | string | `"java"` | Output directory |
| `mapping.integer` | ENUM | `automatic` | `automatic`, `long`, `big-integer` |
| `mapping.enumerated` | ENUM | `enum-type` | `automatic`, `enum-type`, `enums`, `singleton` |
| `mapping.real` | ENUM | `double` | `automatic`, `float`, `double` |
| `mapping.list` | ENUM | `automatic` | `automatic`, `array`, `array-list`, `linked-list`, `vector` |
| `lower-case-package` | BOOLEAN | TRUE | Convert module names to lower case |
| `package-prefix` | string | `""` | Prefix for generated package names |
| `generate.setters-getters` | BOOLEAN | FALSE | JavaBean-style setters/getters |
| `generate.clones` | BOOLEAN | FALSE | `clone()` methods |
| `generate.equals` | BOOLEAN | FALSE | `equals()` and `hashCode()` |
| `generate.prints` | BOOLEAN | FALSE | `toString()` methods |

**Example Configuration:**

```asn1
{
    id "asnjc",
    language "java",
    options {
        output-folder "java",
        mapping {
            integer automatic,
            enumerated automatic,
            real double,
            list automatic
        },
        lower-case-package TRUE,
        package-prefix "com.example",
        generate {
            setters-getters FALSE,
            clones FALSE,
            equals FALSE,
            prints FALSE
        }
    }
}
```

**Integer Mapping:** `automatic` → `BigInteger` when unconstrained, smallest `long`/`int`/`short` otherwise. `long` → `long`. `big-integer` → `BigInteger`.

**Enumerated Mapping:** `enum-type` → class with `public static final` constants (supports extensions). `enums` → Java `enum` (no extensions). `singleton` → singleton class.

**List Mapping:** `automatic` → `Vector` for CHOICE/SET lists, `ArrayList` otherwise. `array` → `T[]`. `array-list` → `ArrayList<T>`. `linked-list` → `LinkedList<T>`. `vector` → `Vector<T>`.

**Runtime Usage:**

```java
import org.asnlab.asndt.runtime.type.*;
import org.asnlab.asndt.runtime.conv.*;

// Encoding
MyPdu pdu = new MyPdu();
pdu.field1 = 42;
Buffer buffer = Buffer.allocate(1024, EncodingRules.ALIGNED_PACKED_ENCODING_RULES);
MyPdu.TYPE.encode(pdu, buffer, MyPdu.CONVERTER);
byte[] encoded = buffer.array();

// Decoding
Buffer buffer = Buffer.wrap(receivedBytes, EncodingRules.ALIGNED_PACKED_ENCODING_RULES);
MyPdu pdu = (MyPdu) MyPdu.TYPE.decode(buffer, MyPdu.CONVERTER);

// Error handling
try {
    MyPdu pdu = (MyPdu) MyPdu.TYPE.decode(buffer, MyPdu.CONVERTER);
} catch (AsnRuntimeException e) {
    // InvalidTagException, BufferUnderflowException, etc.
}

// Utilities
MyPdu copy = (MyPdu) MyPdu.TYPE.clone(original, MyPdu.CONVERTER);
boolean same = MyPdu.TYPE.equals(a, b, MyPdu.CONVERTER);
MyPdu.TYPE.print(pdu, MyPdu.CONVERTER, System.out);   // AVN format
MyPdu.TYPE.json(pdu, MyPdu.CONVERTER, System.out);    // JSON format
```

Encoding rule constants: `EncodingRules.BASIC_ENCODING_RULES`, `CANONICAL_ENCODING_RULES`, `DISTINGUISHED_ENCODING_RULES`, `UNALIGNED_PACKED_ENCODING_RULES`, `ALIGNED_PACKED_ENCODING_RULES`, `OCTET_ENCODING_RULES`, `XML_ENCODING_RULES`, `JSON_ENCODING_RULES`, `ASN_VALUE_NOTATION`.

Full reference: `org.asnlab.asndt.asnjc/doc/java-compiler-guide.md`

---

### C (`asncc`)

Generated types are plain C structs. Include the generated headers and link against the C runtime library (`asnrt.h`).

**Key Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output-folder` | string | `"c"` | Output directory |
| `mapping.integer` | ENUM | `automatic` | `automatic`, `automatic-int64`, `automatic-bigint`, `int32`, `int64`, `big-integer` |
| `mapping.real` | ENUM | `automatic` | `automatic`, `float`, `double` |
| `mapping.size-of-int` | INTEGER | 4 | Bytes of `int` on target platform |
| `mapping.size-of-long` | INTEGER | 8 | Bytes of `long` on target platform |
| `mapping.size-of-xlong` | INTEGER | 8 | Bytes of `long long` on target platform |
| `using-module-name-as-type-prefix` | BOOLEAN | FALSE | Prefix types with module name |
| `custom-type-prefix` | string | -- | Optional type name prefix |
| `dont-generate-names` | BOOLEAN | FALSE | Suppress named constant definitions |
| `generate.constraints` | BOOLEAN | FALSE | Constraint validation functions |
| `generate.sample-test` | BOOLEAN | FALSE | Sample test harness |
| `generate.frees` | BOOLEAN | FALSE | `free()` functions |
| `generate.equals` | BOOLEAN | FALSE | Equality comparison functions |
| `generate.prints` | BOOLEAN | FALSE | `print()` functions |

**Platform Integer Sizes:** Use `size-of-int`/`size-of-long`/`size-of-xlong` to match the target platform. Common defaults: 32-bit → `{4,4,8}`, 64-bit LP64 → `{4,8,8}`, 64-bit LLP64 → `{4,4,8}`.

**Runtime Usage:**

```c
#include "asnrt.h"
#include "MyModule.h"

// Encoding
MyPdu_t pdu = {0};
pdu.field1 = 42;
AsnBuffer* buf = alloc_buffer(1024, TRUE, ALIGNED_PACKED_ENCODING_RULES);
int rc = encode_object(buf, &pdu, &MYPDU_TYPE);
free_buffer(buf);

// Decoding
AsnBuffer* buf = wrap_buffer(receivedBytes, receivedLength, ALIGNED_PACKED_ENCODING_RULES);
MyPdu_t pdu = {0};
int rc = decode_object(buf, &pdu, &MYPDU_TYPE);
free_buffer(buf);

// Error handling (returns 0 on success)
switch (rc) {
    case 0:                 break;  // success
    case INVALID_TAG:       /* ... */
    case BUFFER_UNDERFLOW:  /* ... */
    case MISSING_COMPONENT: /* ... */
}

// Memory management
free_object(&pdu, &MYPDU_TYPE);

// Custom allocators
void* asn_alloc(size_t nitems, size_t size);
void  asn_free(void* block);

// Utilities
print_object(&pdu, &MYPDU_TYPE, printer);
```

Encoding rule constants: `BASIC_ENCODING_RULES`, `CANONICAL_ENCODING_RULES`, `DISTINGUISHED_ENCODING_RULES`, `UNALIGNED_PACKED_ENCODING_RULES`, `ALIGNED_PACKED_ENCODING_RULES`, `OCTET_ENCODING_RULES`, `JSON_ENCODING_RULES`, `ASN_VALUE_NOTATION`.

Full reference: `org.asnlab.asndt.asncc/doc/c-compiler-guide.md`

---

### C++ (`asncpp`)

Generated types are C++ classes/structs in namespaces. Include generated headers and link against the C++ runtime library (`AsnRuntime.h`). All runtime types are in the `asnrt` namespace.

**Key Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output-folder` | string | `"c++"` | Output directory |
| `mapping.integer` | ENUM | `automatic` | `automatic`, `int32`, `int64`, `big-integer` |
| `mapping.real` | ENUM | `automatic` | `automatic`, `float`, `double` |
| `mapping.choice` | ENUM | `union` | `union` (C++ union), `variant` (std::variant, C++17) |
| `mapping.size-of-int` | INTEGER | 4 | Bytes of `int` on target platform |
| `mapping.size-of-long` | INTEGER | 8 | Bytes of `long` on target platform |
| `mapping.size-of-xlong` | INTEGER | 8 | Bytes of `long long` on target platform |
| `cpp-standard` | ENUM | `cpp03` | `cpp03` or `cpp17` |
| `nullable-member` | ENUM | `shared-pointer` | `raw-pointer`, `unique-pointer`, `shared-pointer` |
| `using-module-name-as-namespace` | BOOLEAN | TRUE | Wrap types in module namespace |
| `namespace` | string | `""` | Additional namespace prefix |
| `precompiled-header` | string | `""` | Path to precompiled header |
| `generate.copy-constructor` | BOOLEAN | FALSE | Copy constructors |
| `generate.clone` | BOOLEAN | FALSE | `clone()` methods |
| `generate.frees` | BOOLEAN | TRUE | Destructors/free functions |
| `generate.equals` | BOOLEAN | FALSE | `operator==` |
| `generate.prints` | BOOLEAN | FALSE | `operator<<` stream output |

**Nullable Member Mapping:** Controls OPTIONAL fields: `raw-pointer` → `T*`, `unique-pointer` → `std::unique_ptr<T>`, `shared-pointer` → `std::shared_ptr<T>`.

**Runtime Usage:**

```cpp
#include "AsnRuntime.h"
#include "MyModule.h"
using namespace asnrt;

// Encoding
MyPdu pdu;
pdu.field1 = 42;
AsnBuffer* buf = alloc_buffer(1024, true, ALIGNED_PACKED_ENCODING_RULES);
try {
    encode_object(buf, &pdu, MyPdu::TYPE, MyPdu::CONVERTER);
} catch (const AsnException& e) {
    // e.getErrorCode(), e.getMessage()
}
free_buffer(buf);

// Decoding
AsnBuffer* buf = wrap_buffer(receivedBytes, receivedLength, ALIGNED_PACKED_ENCODING_RULES);
MyPdu pdu;
try {
    decode_object(buf, &pdu, MyPdu::TYPE, MyPdu::CONVERTER);
} catch (const AsnException& e) {
    // handle error
}
free_buffer(buf);

// Utilities
print_object(&pdu, MyPdu::TYPE, MyPdu::CONVERTER, &std::cout);
bool same = equals_to(&a, &b, MyPdu::TYPE, MyPdu::CONVERTER);
clone_object(&original, &copy, MyPdu::TYPE, MyPdu::CONVERTER);
free_object(&pdu, MyPdu::TYPE, MyPdu::CONVERTER);
```

Error codes: `INVALID_TAG`, `BUFFER_UNDERFLOW`, `MISSING_COMPONENT`, `NO_MATCH_INFO_OBJ`, `OUT_OF_MEMORY`, `INVALID_VALUE`.

Encoding rule constants: `BASIC_ENCODING_RULES`, `CANONICAL_ENCODING_RULES`, `DISTINGUISHED_ENCODING_RULES`, `UNALIGNED_PACKED_ENCODING_RULES`, `ALIGNED_PACKED_ENCODING_RULES`, `OCTET_ENCODING_RULES`, `JSON_ENCODING_RULES`, `ASN_VALUE_NOTATION`.

Full reference: `org.asnlab.asndt.asncpp/doc/cpp-compiler-guide.md`

---

### C# (`asncsc`)

Generated types are C# classes/structs in namespaces. Add a reference to the C# runtime library (`org.asnlab.asndt.asnrt` namespace).

**Key Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output-folder` | string | `"c#"` | Output directory |
| `mapping.integer` | ENUM | `automatic` | `automatic`, `int32`, `int64`, `big-integer` |
| `mapping.real` | ENUM | `double` | `automatic`, `float`, `double` |
| `lower-case-namespace` | BOOLEAN | TRUE | Convert module names to lower case |
| `namespace-prefix` | string | `""` | Prefix for generated namespaces |
| `generate.properties` | BOOLEAN | FALSE | Properties instead of public fields |
| `generate.clones` | BOOLEAN | FALSE | `Clone()` methods |
| `generate.equals` | BOOLEAN | TRUE | `Equals()` and `GetHashCode()` |
| `generate.prints` | BOOLEAN | FALSE | `ToString()` overrides |
| `generate.hash-code` | BOOLEAN | TRUE | `GetHashCode()` overrides |

**Integer Mapping:** `automatic` → `BigInteger` when unconstrained, smallest `long`/`int` otherwise. `int32` → `int`. `int64` → `long`. `big-integer` → `BigInteger`.

**Runtime Usage:**

```csharp
using org.asnlab.asndt.asnrt.type;
using org.asnlab.asndt.asnrt.conv;

// Encoding
var pdu = new MyPdu();
pdu.field1 = 42;
var buffer = AsnBuffer.Allocate(1024, EncodingRules.ALIGNED_PACKED_ENCODING_RULES);
MyPdu.TYPE.Encode(pdu, buffer, MyPdu.CONVERTER);
byte[] encoded = buffer.Array();

// Decoding
var buffer = AsnBuffer.Wrap(receivedBytes, EncodingRules.ALIGNED_PACKED_ENCODING_RULES);
var pdu = (MyPdu) MyPdu.TYPE.Decode(buffer, MyPdu.CONVERTER);

// Error handling
try {
    var pdu = (MyPdu) MyPdu.TYPE.Decode(buffer, MyPdu.CONVERTER);
} catch (AsnRuntimeException e) {
    // InvalidTagException, BufferUnderflowException, etc.
}

// Utilities
var copy = (MyPdu) MyPdu.TYPE.Clone(original, MyPdu.CONVERTER);
bool same = MyPdu.TYPE.Equals(a, b, MyPdu.CONVERTER);
MyPdu.TYPE.Print(pdu, MyPdu.CONVERTER, Console.Out);   // AVN format
string json = MyPdu.TYPE.Json(pdu, MyPdu.CONVERTER);   // JSON string
```

Encoding rule constants: `EncodingRules.BASIC_ENCODING_RULES`, `CANONICAL_ENCODING_RULES`, `DISTINGUISHED_ENCODING_RULES`, `UNALIGNED_PACKED_ENCODING_RULES`, `ALIGNED_PACKED_ENCODING_RULES`, `OCTET_ENCODING_RULES`, `XML_ENCODING_RULES`, `JSON_ENCODING_RULES`, `ASN_VALUE_NOTATION`.

Full reference: `org.asnlab.asndt.asncsc/doc/csharp-compiler-guide.md`

---

### Go (`asngc`)

Generated types are Go structs in packages. Import the generated package and runtime interface. Each generated module provides a `GetRuntime()` function.

**Key Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `output-folder` | string | `"go"` | Output directory |
| `mapping.integer` | ENUM | `automatic-int64` | `automatic`, `automatic-int64`, `automatic-bigint`, `int32`, `int64`, `big-integer` |
| `mapping.real` | ENUM | `automatic` | `automatic`, `float32`, `float64` |
| `generate.equals` | BOOLEAN | -- | `Equals` methods |
| `generate.prints` | BOOLEAN | -- | `String` methods |

**Integer Mapping:** `automatic`/`automatic-int64` → `int64`. `automatic-bigint`/`big-integer` → `*big.Int`. `int32` → `int32`. `int64` → `int64`.

**Runtime Usage:**

```go
import (
    "github.com/asnlab/asnrt"
    "example.com/myproject/mymodule"
)

// Encoding
pdu := mymodule.MyPdu{Field1: 42}
runtime := mymodule.GetRuntime()
buf, _ := runtime.Allocate(1024, asnrt.ALIGNED_PACKED_ENCODING_RULES)
err := runtime.Encode(buf, &pdu, mymodule.MYPDU_TYPE)
encoded := buf.Array()

// Decoding
runtime := mymodule.GetRuntime()
buf, _ := runtime.Wrap(receivedBytes, asnrt.ALIGNED_PACKED_ENCODING_RULES)
var pdu mymodule.MyPdu
err := runtime.Decode(buf, &pdu, mymodule.MYPDU_TYPE)

// Error handling
if err != nil {
    // handle error
}
```

Encoding rule constants: `asnrt.BASIC_ENCODING_RULES`, `CANONICAL_ENCODING_RULES`, `DISTINGUISHED_ENCODING_RULES`, `UNALIGNED_PACKED_ENCODING_RULES`, `ALIGNED_PACKED_ENCODING_RULES`, `OCTET_ENCODING_RULES`, `JSON_ENCODING_RULES`, `ASN_VALUE_NOTATION`.

Full reference: `org.asnlab.asndt.asngc/doc/go-compiler-guide.md`

---

## Full Workflow Example (MyHTTP)

The following ASN.1 module defines a simple HTTP request type:

```asn1
MyHTTP DEFINITIONS AUTOMATIC TAGS ::= BEGIN
   GetRequest ::= SEQUENCE {
      header-only   BOOLEAN,
      lock          BOOLEAN,
      accept-types  AcceptTypes,
      url           Url,
      ...,
      timestamp     GeneralizedTime
   }
   AcceptTypes ::= SET {
      standards   BIT STRING { html(0), plain-text(1), gif(2), jpeg(3) } (SIZE(4)) OPTIONAL,
      others      SEQUENCE OF VisibleString (SIZE(4)) OPTIONAL
   }
   Url ::= VisibleString (FROM("a".."z"|"A".."Z"|"0".."9"|"./-_~%#"))
END
```

Save this as `MyProject/src/MyHTTP.asn`. Configure `asn1.avn` with your target compilers (see language-specific sections above), then run:

```bash
asndt compile MyProject
```

Each language target produces the same BER-encoded bytes for this example. Generated output follows the pattern `<project>/<output>/<compiler-output-folder>/`.

## Important Notes

- The `asndt` CLI is the only entry point — use `create`, `compile`, `clean`, or `license`
- `clean` removes the configured `output` directory for a project without compiling, useful for ensuring no stale files remain before recompilation
- Compiler entries in `asn1.avn` are SEQUENCE OF elements, each with `id`, `language`, and `options`
- License keys are confidential — do not commit, publish, or share them
- Generated code and runtime libraries are subject to the ASN Lab license agreement
- Each generated type exposes a type descriptor and converter for encode/decode calls
- Encoding rules are selected by passing a constant when creating the buffer