### Install asn1tools

Source: http://asn1tools.readthedocs.org/en/latest

Install the package using pip.

```bash
pip install asn1tools
```

--------------------------------

### Install prerequisites

Source: http://asn1tools.readthedocs.org/en/latest

Installs the necessary Python packages for the project using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Define ASN.1 Specification

Source: http://asn1tools.readthedocs.org/en/latest

Example ASN.1 specification defining a Foo protocol with Question and Answer messages.

```asn1
Foo DEFINITIONS ::= BEGIN

    Question ::= SEQUENCE {
        id        INTEGER,
        question  IA5String
    }

    Answer ::= SEQUENCE {
        id        INTEGER,
        answer    BOOLEAN
    }

END
```

--------------------------------

### Run tests

Source: http://asn1tools.readthedocs.org/en/latest

Executes the test suite for the project using make.

```bash
make test
```

--------------------------------

### Use the asn1tools Shell

Source: http://asn1tools.readthedocs.org/en/latest

Interactive shell for compiling specifications and converting data between formats.

```bash
> asn1tools shell

Welcome to the asn1tools shell!

$ help
Commands:
  compile
  convert
  exit
  help
$ compile tests/files/foo.asn
$ convert Question 300e0201011609497320312b313d333f
question Question ::= {
    id 1,
    question "Is 1+1=3?"
}
$ compile --output-codec xer tests/files/foo.asn
$ convert Question 300e0201011609497320312b313d333f
<Question>
    <id>1</id>
    <question>Is 1+1=3?</question>
</Question>
$ compile -o uper tests/files/foo.asn
$ convert Question 300e0201011609497320312b313d333f
01010993cd03156c5eb37e
$ exit
>
```

--------------------------------

### Compile and Encode/Decode with Python

Source: http://asn1tools.readthedocs.org/en/latest

Compile an ASN.1 file and perform encoding/decoding operations using different codecs.

```python
>>> import asn1tools
>>> foo = asn1tools.compile_files('tests/files/foo.asn')
>>> encoded = foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
>>> encoded
bytearray(b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?')
>>> foo.decode('Question', encoded)
{'id': 1, 'question': 'Is 1+1=3?'}
```

```python
>>> import asn1tools
>>> foo = asn1tools.compile_files('tests/files/foo.asn', 'per')
>>> encoded = foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
>>> encoded
bytearray(b'\x01\x01\tIs 1+1=3?')
>>> foo.decode('Question', encoded)
{'id': 1, 'question': 'Is 1+1=3?'}
```

--------------------------------

### Generate C source code with fuzzer support

Source: http://asn1tools.readthedocs.org/en/latest

Generates OER C source code along with fuzz testing C source code for libFuzzer. Requires a recent version of clang.

```bash
> asn1tools generate_c_source --namespace oer --generate-fuzzer tests/files/c_source/c_source.asn
Successfully generated oer.h and oer.c.
Successfully generated oer_fuzzer.c and oer_fuzzer.mk.

Run "make -f oer_fuzzer.mk" to build and run the fuzzer. Requires a
recent version of clang.
```

--------------------------------

### Compile ASN.1 Files

Source: http://asn1tools.readthedocs.org/en/latest

Compile one or more ASN.1 specification files into a Specification object. The codec can be specified, and a cache directory can be used to speed up recompilation.

```python
>>> foo = asn1tools.compile_files('foo.asn')
```

```python
>>> foo = asn1tools.compile_files('foo.asn', cache_dir='my_cache')
```

--------------------------------

### Convert Data via Command Line

Source: http://asn1tools.readthedocs.org/en/latest

Convert encoded data between different formats using the convert subcommand.

```bash
> asn1tools convert tests/files/foo.asn Question 300e0201011609497320312b313d333f
question Question ::= {
    id 1,
    question "Is 1+1=3?"
}
>
```

```bash
> asn1tools convert -i uper -o xer tests/files/foo.asn Question 01010993cd03156c5eb37e
<Question>
    <id>1</id>
    <question>Is 1+1=3?</question>
</Question>
>
```

```bash
> asn1tools convert -i uper -o jer tests/files/foo.asn Question 01010993cd03156c5eb37e
{
    "id": 1,
    "question": "Is 1+1=3?"
}
>
```

```bash
> cat encoded.txt
2018-02-24 11:22:09
300e0201011609497320312b313d333f
2018-02-24 11:24:15
300e0201021609497320322b323d353f
> cat encoded.txt | asn1tools convert tests/files/foo.asn Question -
2018-02-24 11:22:09
question Question ::= {
    id 1,
    question "Is 1+1=3?"
}
2018-02-24 11:24:15
question Question ::= {
    id 2,
    question "Is 2+2=5?"
}
>
```

--------------------------------

### Convert PCCH-Message with cache

Source: http://asn1tools.readthedocs.org/en/latest

Demonstrates converting an encoded PCCH-Message from UPER to GSER using the --cache-dir option. Subsequent calls are significantly faster due to caching.

```bash
> time asn1tools convert --cache-dir my_cache -i uper tests/files/3gpp/rrc_8_6_0.asn PCCH-Message 28
pcch-message PCCH-Message ::=
    message c1 : paging :
        {
            systemInfoModification true,
            nonCriticalExtension
                {}
        }

real    0m2.090s
user    0m1.977s
sys     0m0.032s
> time asn1tools convert --cache-dir my_cache -i uper tests/files/3gpp/rrc_8_6_0.asn PCCH-Message 28
pcch-message PCCH-Message ::=
    message c1 : paging :
        {
            systemInfoModification true,
            nonCriticalExtension
                {}
        }

real    0m0.276s
user    0m0.197s
sys     0m0.026s
>
```

--------------------------------

### Compile ASN.1 Files

Source: http://asn1tools.readthedocs.org/en/latest

Compiles ASN.1 specification files into a Specification object for encoding and decoding. Supports various codecs and caching.

```APIDOC
## compile_files

### Description
Compiles given ASN.1 specification file(s) and returns a `Specification` object that can be used to encode and decode data structures with the given codec.

### Method
`asn1tools.compile_files(filenames, codec='ber', any_defined_by_choices=None, encoding='utf-8', cache_dir=None, numeric_enums=False)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **filenames** (list of str) - Required - A list of paths to the ASN.1 specification files.
- **codec** (str) - Optional - The codec to use. Defaults to 'ber'. Supported codecs: 'ber', 'der', 'gser', 'jer', 'oer', 'per', 'uper', 'xer'.
- **any_defined_by_choices** (any) - Optional - Used for handling ANY DEFINED BY constructs.
- **encoding** (str) - Optional - The text encoding for reading files. Defaults to 'utf-8'.
- **cache_dir** (str or None) - Optional - Directory to cache compiled files. Defaults to None (no cache).
- **numeric_enums** (bool) - Optional - If True, enumeration values will be numeric strings instead of strings. Defaults to False.

### Request Example
```python
# Basic usage
spec = asn1tools.compile_files('foo.asn')

# With cache directory
spec = asn1tools.compile_files('foo.asn', cache_dir='my_cache')
```

### Response
#### Success Response (200)
- **Specification** (object) - A `Specification` object that can be used for encoding and decoding.
```

--------------------------------

### Generate OER C source code

Source: http://asn1tools.readthedocs.org/en/latest

Generates OER C source code (header and implementation files) from an ASN.1 specification. Requires all types to have a known maximum size.

```bash
> asn1tools generate_c_source --namespace oer tests/files/c_source/c_source.asn
Successfully generated oer.h and oer.c.
```

--------------------------------

### Generate UPER C source code

Source: http://asn1tools.readthedocs.org/en/latest

Generates UPER C source code (header and implementation files) from an ASN.1 specification. Requires all types to have a known maximum size.

```bash
> asn1tools generate_c_source --codec uper --namespace uper tests/files/c_source/c_source.asn
Successfully generated uper.h and uper.c.
```

--------------------------------

### Parse ASN.1 Files

Source: http://asn1tools.readthedocs.org/en/latest

Parse one or more ASN.1 specification files and return their contents as a dictionary. This dictionary can then be compiled using `compile_dict()`. The encoding argument specifies the text encoding.

```python
foo = asn1tools.parse_files('foo.asn')
```

--------------------------------

### Parse ASN.1 and convert data

Source: http://asn1tools.readthedocs.org/en/latest

Parses an ASN.1 specification into a Python dictionary file, then uses this file to convert encoded data from BER to GSER.

```bash
> asn1tools parse tests/files/foo.asn foo.py
> asn1tools convert foo.py Question 300e0201011609497320312b313d333f
question Question ::=
    {
        id 1,
        question "Is 1+1=3?"
    }
>
```

--------------------------------

### Parse ASN.1 from String

Source: http://asn1tools.readthedocs.org/en/latest

Parse a given ASN.1 specification string and return its contents as a dictionary. This dictionary can then be compiled using `compile_dict()`.

```python
with open('foo.asn') as fin:
    foo = asn1tools.parse_string(fin.read())
```

--------------------------------

### asn1tools.parse_files

Source: http://asn1tools.readthedocs.org/en/latest

Parses ASN.1 specification files into a dictionary.

```APIDOC
## asn1tools.parse_files

### Description
Parses given ASN.1 specification file(s) and returns a dictionary of their contents, which can be used with compile_dict().

### Parameters
- **filenames** (str or list) - Required - The path or list of paths to the ASN.1 files.
- **encoding** (str) - Optional - The text encoding. Defaults to 'utf-8'.
```

--------------------------------

### Compile ASN.1 from String

Source: http://asn1tools.readthedocs.org/en/latest

Compile a given ASN.1 specification string into a Specification object. The codec can be one of 'ber', 'der', 'gser', 'jer', 'oer', 'per', 'uper', and 'xer'. Set `numeric_enums=True` for numeric enumeration values.

```python
with open('foo.asn') as fin:
    foo = asn1tools.compile_string(fin.read())
```

--------------------------------

### Compile ASN.1 from Dictionary

Source: http://asn1tools.readthedocs.org/en/latest

Compile an ASN.1 specification dictionary into a Specification object. The codec can be one of 'ber', 'der', 'gser', 'jer', 'oer', 'per', 'uper', and 'xer'. Set `numeric_enums=True` for numeric enumeration values.

```python
foo = asn1tools.compile_dict(asn1tools.parse_files('foo.asn'))
```

--------------------------------

### asn1tools.compile_dict

Source: http://asn1tools.readthedocs.org/en/latest

Compiles an ASN.1 specification dictionary into a Specification object.

```APIDOC
## asn1tools.compile_dict

### Description
Compiles a given ASN.1 specification dictionary and returns a Specification object for encoding and decoding.

### Parameters
- **specification** (dict) - Required - The ASN.1 specification dictionary.
- **codec** (str) - Optional - The codec to use. Defaults to 'ber'.
- **any_defined_by_choices** (dict) - Optional - Choices for any defined by fields.
- **numeric_enums** (bool) - Optional - If True, uses numeric enumeration values instead of strings. Defaults to False.
```

--------------------------------

### Access Specification Modules

Source: http://asn1tools.readthedocs.org/en/latest

Access types within specific modules of the compiled specification using the 'modules' dictionary. This is useful when dealing with multiple modules or types with the same name across modules.

```python
>>> question = foo.modules['Foo']['Question']
>>> question
Sequence(Question, [Integer(id), IA5String(question)])
```

--------------------------------

### asn1tools.compile_string

Source: http://asn1tools.readthedocs.org/en/latest

Compiles an ASN.1 specification string into a Specification object for encoding and decoding.

```APIDOC
## asn1tools.compile_string

### Description
Compiles a given ASN.1 specification string and returns a Specification object that can be used to encode and decode data structures.

### Parameters
- **string** (str) - Required - The ASN.1 specification string.
- **codec** (str) - Optional - The codec to use (e.g., 'ber', 'der', 'gser', 'jer', 'oer', 'per', 'uper', 'xer'). Defaults to 'ber'.
- **any_defined_by_choices** (dict) - Optional - Choices for any defined by fields.
- **numeric_enums** (bool) - Optional - If True, uses numeric enumeration values instead of strings. Defaults to False.
```

--------------------------------

### Decode Data with Specification

Source: http://asn1tools.readthedocs.org/en/latest

Decode ASN.1 encoded bytes back into Python data structures using the 'decode' method of the Specification object. Constraint checking can be optionally enabled.

```python
>>> foo.decode('Question', b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?')
{'id': 1, 'question': 'Is 1+1=3?'}
```

--------------------------------

### Specification Object Methods

Source: http://asn1tools.readthedocs.org/en/latest

Methods available on the Specification object for encoding and decoding ASN.1 data.

```APIDOC
## Specification Object

### Description
The `Specification` object is used to encode and decode ASN.1 types. Instances are created by `compile_files()`, `compile_string()`, and `compile_dict()`.

### Attributes
- **types** (dict): A dictionary of all unique types in the specification. Types found in multiple modules are excluded.
- **modules** (dict): A dictionary of all modules in the specification, including types found in multiple modules.

### Methods
#### encode
Encodes given dictionary data as the specified type name and returns the encoded data as a bytes object.

- **Method**: `Specification.encode(name, data, check_types=True, check_constraints=False, **kwargs)`
- **Parameters**:
  - **name** (str) - The name of the ASN.1 type to encode.
  - **data** (dict) - The data to encode, as a Python dictionary.
  - **check_types** (bool) - If True, checks data against expected Python types. Defaults to True.
  - **check_constraints** (bool) - If True, checks data against ASN.1 constraints. Defaults to False.
- **Returns**: bytes - The encoded data.
- **Example**:
  ```python
  encoded_data = foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
  ```

#### decode
Decodes given bytes object data as the specified type name and returns the decoded data as a dictionary.

- **Method**: `Specification.decode(name, data, check_constraints=False)`
- **Parameters**:
  - **name** (str) - The name of the ASN.1 type to decode.
  - **data** (bytes) - The data to decode.
  - **check_constraints** (bool) - If True, checks decoded data against ASN.1 constraints. Defaults to False.
- **Returns**: dict - The decoded data.
- **Example**:
  ```python
  decoded_data = foo.decode('Question', b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?')
  ```

#### decode_with_length
Decodes given bytes object data as the specified type name and also returns the byte length of the decoded data.

- **Method**: `Specification.decode_with_length(name, data, check_constraints=False)`
- **Parameters**:
  - **name** (str) - The name of the ASN.1 type to decode.
  - **data** (bytes) - The data to decode.
  - **check_constraints** (bool) - If True, checks decoded data against ASN.1 constraints. Defaults to False.
- **Returns**: tuple - A tuple containing the decoded data (dict) and the length (int).
- **Example**:
  ```python
  decoded_data, length = foo.decode_with_length('Question', b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?')
  ```

#### decode_length
Decodes the length of given data. Returns None if not enough data was provided.

- **Method**: `Specification.decode_length(data)`
- **Parameters**:
  - **data** (bytes) - The data to decode the length from.
- **Returns**: int or None - The decoded length, or None if insufficient data.
- **Example**:
  ```python
  length = foo.decode_length(b'\x30\x0e\x02\x01\x01')
  ```
```

--------------------------------

### Access Specification Types

Source: http://asn1tools.readthedocs.org/en/latest

Access specific types within the compiled specification using the 'types' dictionary. This provides a direct mapping of type names to their definitions.

```python
>>> question = foo.types['Question']
>>> question
Sequence(Question, [Integer(id), IA5String(question)])
```

--------------------------------

### asn1tools.parse_string

Source: http://asn1tools.readthedocs.org/en/latest

Parses an ASN.1 specification string into a dictionary.

```APIDOC
## asn1tools.parse_string

### Description
Parses a given ASN.1 specification string and returns a dictionary of its contents.

### Parameters
- **string** (str) - Required - The ASN.1 specification string.
```

--------------------------------

### Encode Data with Specification

Source: http://asn1tools.readthedocs.org/en/latest

Encode Python data structures into ASN.1 encoded bytes using the 'encode' method of the Specification object. Type and constraint checking can be enabled or disabled.

```python
>>> foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?'
```

--------------------------------

### Decode Data with Length

Source: http://asn1tools.readthedocs.org/en/latest

Decode ASN.1 encoded bytes and also return the byte length of the decoded data using 'decode_with_length'. This is particularly useful for BER encoded data with indefinite lengths.

```python
>>> foo.decode_with_length('Question',
...                             b'0\x0e\x02\x01\x01\x16\x09Is 1+1=3?')
({'id': 1, 'question': 'Is 1+1=3?'}, 16)
```

--------------------------------

### Decode Length from Data

Source: http://asn1tools.readthedocs.org/en/latest

Decode only the length from BER or DER encoded data using 'decode_length'. This method returns None if not enough data is provided to determine the length.

```python
>>> foo.decode_length(b'\x30\x0e\x02\x01\x01')
16
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.