21 releases
0.7.0 | Jun 27, 2024 |
---|---|
0.6.1 | Nov 10, 2023 |
0.5.9 | Aug 8, 2023 |
0.5.8 | Mar 3, 2023 |
0.1.2 | Nov 13, 2021 |
#242 in Encoding
2,731 downloads per month
Used in 3 crates
120KB
3K
SLoC
Hampi - Rust ASN.1 Toolkit
The Goal of this project is to implement an ASN.1 Compiler in Rust which can generate Rust bindings for different ASN.1 specifications, which can be used in various protocol implementations in Rust. Also, support for different ASN.1 encoding rules like DER, BER, PER is planned to be implemented as ASN.1 codecs.
While it is certainly desirable to have a fully compliant ASN.1 Compiler, initial focus of the project is to be able to generate code that can be used in other software. First goal is to work with 3GPP specifications for protocols like Radio Network Access Protocl (RANAP), S1 Application protocl (S1AP) and NG Application Protocol (NGAP). Consequently current implementation also focuses on codecs used by these specifications viz. Aligned Packed Encoding Rules (APER).
The use cases targeted by this implementation are similar to the use cases targeted by asn1c
compiler, which generates C
bindings from the ASN.1 Specifications.
This project is divided into three crates -
-
asn1-compiler
: This crate provides the actual ASN.1 Compiler. Typically a utility (hampi-rs-asn1c
) will generate Rust structures starting with ASN.1 Specifications. Basic working features required to work with the 3GPP specifications is provided by the compiler, this includes Parameterized Types, Information Object Classes and Type Constraints. -
asn1-codecs
: Support for different encodings supported by individual ASN.1 specifications is provided in this crate. Currently basic APER/UPER Codecs are supported. Every Codec is supported as atrait
implementing respective 'encode' and 'decode' functions. Support for different 'encoding rules' will be implemented in this crate and then the derive macros will utilize this code to actually generate the encoding support for Rust Structures generated by the compiler above. -
asn1_codecs_derive
: This crate provides thederive
macros for the codecs inasn-codecs
. The code generated usingasn-compiler
can be directed toderive
appropriate codecs by passing the flags during compilation.
Supported Codecs
- APER
- UPER
Supported Protocols
Following protocols are currently supported.
- RANAP - Code generation and RANAP PDU encode/decode.
- S1AP - Code generation and S1AP PDU decode.
- NGAP - Code generation and NGAP PDU encode/decode.
- E2AP - Code generation
- SUPL - Code generation
- RRC - Code generation and RRC PDU decode.
- E2SM - Code generation and encode/decode functionality.
Getting Started
build.rs
Support
Typically the compiler can be invoked also using build.rs
mechanism. An example build.rs
is provided in the examples/
sub project. And the code generated through this build.rs
can be integrated into your project. Examples of that is provided in examples/tests/
directory.
Using CLI tool
A tool hampi-rs-asn1c
can be installed using cargo install asn1-compiler
and then following the CLI usage.
cargo install asn1-compiler
hampi-rs-asn1c --help
Running Test Cases
- Test cases can be run through
cargo test
.
Generating ASN.1 spec files
Currently there are two ways of generating the 'ASN.1' spec files from the '.docx' specifications (This mainly applies to 3GPP specifications).
- Using the script inside
examples/specs/parse_specs.py
. This is recommended way. (note: this requires installation ofdocx
orpython-docx
in the case of Python3). - Using the rust binary
extract-asn-spec
. Note: this is not the recommended way and your mileage may vary. Eventual goal is to make this the default way - so as to also have abuild.rs
integration. But this is for now a work in progress. This is not available by default and is enabled only with a feature flagrs-specs-gen
.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-Apache or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
Dependencies
~2.5MB
~61K SLoC