Try compiling some ASN.1 online.
The rasn-compiler library is a parser combinator that parses ASN.1 specifications and outputs bindings for ASN.1 data
elements using pluggable backends. Currently, the compiler can output:
- rust bindings to be used with the
rasncrate - typescript type definitions for JER-encoded ASN.1 data elements
The compiler heavily relies on the great library nom for its basic parsers. The parser has been designed to generate bindings for ASN.1 and it should not be used as a validating tool for ASN.1 modules.
In order to compile ASN.1 in your build process, invoke the rasn-compiler in your
build.rs build script.
// build.rs build script
use std::path::PathBuf;
use rasn_compiler::prelude::*;
fn main() {
// Initialize the compiler with the rust/rasn backend.
// To use the typescript backend, initialize the compiler using
// `Compiler::<TypescriptBackend, _>::new()`
match Compiler::<RasnBackend, _>::new()
// add a single ASN1 source file
.add_asn_by_path(PathBuf::from("spec_1.asn"))
// add several ASN1 source files
.add_asn_sources_by_path(vec![
PathBuf::from("spec_2.asn"),
PathBuf::from("spec_3.asn"),
].iter())
// set an output path for the generated rust code
.set_output_path(PathBuf::from("./asn/generated.rs"))
// you may also compile literal ASN1 snippets
.add_asn_literal(format!(
"TestModule DEFINITIONS AUTOMATIC TAGS::= BEGIN {} END",
"My-test-integer ::= INTEGER (1..128)"
))
.compile() {
Ok(warnings /* Vec<Box<dyn Error>> */) => { /* handle compilation warnings */ }
Err(error /* Box<dyn Error> */) => { /* handle unrecoverable compilation error */ }
}
}The compiler backends can be configured by instantiating the compiler using the Compiler::new_with_config constructor.
The RasnBackend configuration supports the following parameters:
- opaque_open_types:
bool: [Default:false] ASN.1 Open Types are represented as therasn::types::Anytype, which holds a binarycontent. Ifopaque_open_typesisfalse, the compiler will generate additional de-/encode methods for all rust types that hold an open type. For example, bindings for aSEQUENCEwith a field of Open Type value will include a method for explicitly decoding the Open Type field. Non-opaque open types are still experimental. If you have trouble generating correct bindings, switch back to opaque open types. - default_wildcard_imports:
bool: [Default:false] The compiler will try to match module import dependencies of the ASN.1 module as close as possible, importing only those types from other modules that are imported in the ASN.1 module. If thedefault_wildcard_importsis set totrue, the compiler will instead always import the entire module using the wildcard*for each module that the input ASN.1 module imports from.
The compiler's backend can be replaced with a custom backend to generate bindings for a different language or framework.
Backends must implement the Backend trait that rasn-compiler exports.
// build.rs build script
use std::path::PathBuf;
use rasn_compiler::prelude::*;
// The `Backend` trait requires the implementor to implement `Default`
#[derive(Default)]
struct CustomBackend;
impl Backend for CustomBackend {
type Config = ();
const FILE_EXTENSION: &'static str = ".ext";
fn generate_module(
&self,
top_level_declarations: Vec<ToplevelDefinition>,
) -> Result<GeneratedModule, GeneratorError> {
Ok(GeneratedModule::empty())
}
fn generate(
&self,
tld: ToplevelDefinition
) -> Result<String, GeneratorError> {
Ok(String::new())
}
fn config(&self) -> &Self::Config {
&()
}
fn from_config(config: Self::Config) -> Self {
CustomBackend
}
}
fn main() {
// Initialize the compiler
match Compiler::<CustomBackend, _>::new()
// add a single ASN1 source file
.add_asn_by_path(PathBuf::from("spec_1.asn"))
// add several ASN1 source files
.add_asn_sources_by_path(vec![
PathBuf::from("spec_2.asn"),
PathBuf::from("spec_3.asn"),
].iter())
// set an output path for the generated rust code
.set_output_path(PathBuf::from("./asn/generated.rs"))
// you may also compile literal ASN1 snippets
.add_asn_literal(format!(
"TestModule DEFINITIONS AUTOMATIC TAGS::= BEGIN {} END",
"My-test-integer ::= INTEGER (1..128)"
))
.compile() {
Ok(warnings /* Vec<Box<dyn Error>> */) => { /* handle compilation warnings */ }
Err(error /* Box<dyn Error> */) => { /* handle unrecoverable compilation error */ }
}
}The rasn-compiler provides a CLI application that can be activated with the cli cargo feature. Run
./rasn_compiler_cli -h for usage info.
ASN1 is a complex standard, and not all of its features and encoding rules are supported, yet.
Currently, rasn supports the following encoding rules:
- Basic Encoding Rules (BER)
- Canonical Encoding Rules (CER)
- Distinguished Encoding Rules (DER)
- Aligned Packed Encoding Rules (APER)
- Unaligned Packed Encoding Rules (UPER)
- JSON Encoding Rules (JER)
rasn and the rasn-compiler support the following ASN1 features:
NULLtype and valueBOOLEANtype and valueNumericStringtype and valueVisibleStringtype and valueIA5Stringtype and valueGeneralStringtype and valueUTF8Stringtype and valueBMPStringtype and valuePrintableStringtype and valueBIT STRINGtype and value (hex- and bitstring declations)OCTET STRINGtype and value (hex- and bitstring declations)OBJECT IDENTIFIERtype and valueRELATIVE-OIDtype and valueSEQUENCEtype and valueSETtype and valueSEQUENCE OFtype and valueSET OFtype and valueENUMERATEDtype and valueCHOICEtype and valueUTCTimetype and valueGeneralizedTimetype and value
- Single value constraints
- Value range constraints
- Contained subtype constraints
- Size constraints
- Permitted alphabet constraints
- Constraint set operations
- Table constraints
DEFAULTmember valuesCOMPONENTS OFnotation- Choice selection type notation (e.g.
option-1 < Example-choice) - extensions and extension groups
- Parameterization (the
rasn-compilercreates rust representations for invocations of the parameterized data elements in the given spec, i.e. it does not preserve the parameterization itself) - Information Object Classes (however, they are not represented in the rust bindings)
- Information Objects
- Information Object Sets
If you have trouble generating correct bindings:
- try playing around with the compiler configuration that can be passed to the
Compiler::new_with_configconstructor - open an issue here, if possible with a sample of the problematic ASN.1 spec
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent