# Synta Examples
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Basic Examples](#basic-examples)
- [decode_integer.rs](#decode_integerrs)
- [encode_sequence.rs](#encode_sequencers)
- [oid_usage.rs](#oid_usagers)
- [parse_certificate.rs](#parse_certificaters)
- [Serde Examples](#serde-examples)
- [serde_usage.rs](#serde_usagers)
- [serde_cert.rs](#serde_certrs)
- [Utility Tools](#utility-tools)
- [asn1parse](#asn1parse)
- [generate_test_cert.rs](#generatetestcertrs)
- [Comparing with OpenSSL](#comparing-with-openssl)
- [Running All Examples](#running-all-examples)
- [See Also](#see-also)
This directory contains working examples demonstrating various features of the Synta ASN.1 library.
## Basic Examples
### decode_integer.rs
Demonstrates how to decode ASN.1 INTEGER values from DER-encoded data.
```bash
cargo run --example decode_integer
```
Shows encoding and decoding of:
- Small positive integers (42)
- Larger positive integers (1000)
- Negative integers (-1)
- Large integers (i64::MAX)
- Zero
### encode_sequence.rs
Shows how to build and encode ASN.1 SEQUENCE structures.
```bash
cargo run --example encode_sequence
```
Demonstrates:
- Simple sequences with multiple element types
- Nested sequences
- Roundtrip encoding/decoding
### oid_usage.rs
Working with ASN.1 Object Identifiers (OIDs).
```bash
cargo run --example oid_usage
```
Shows:
- Common cryptographic OIDs (RSA, SHA-256, ECDSA)
- OID encoding and decoding
- Accessing OID components
- X.509 extension OIDs
### parse_certificate.rs
Parses X.509 certificate structure using Synta.
```bash
cargo run --example parse_certificate
```
Demonstrates:
- Parsing certificate structure
- Navigating TBSCertificate
- Extracting signature algorithms
- Working with certificate fields
## Serde Examples
These examples require the `serde` feature flag.
### serde_usage.rs
Demonstrates JSON serialization and deserialization of all ASN.1 types using the optional `serde` feature.
```bash
cargo run --example serde_usage --features serde
```
Shows:
- Serializing primitive types (Boolean, Integer, Null, Real, OctetString, Utf8String, ObjectIdentifier, UtcTime, GeneralizedTime)
- Deserializing JSON strings back into typed ASN.1 values
- DER → JSON → DER round-trip for INTEGER
- `SequenceOf<Integer>` serializing as a JSON array
- `ExplicitTag<Integer>` preserving tag metadata in JSON
- Parsing a DER SEQUENCE into an `Element` tree and formatting it as pretty JSON
JSON format used for each type:
| `Boolean` | `true` / `false` |
| `Integer` | lowercase hex string, e.g. `"2a"` |
| `Null` | `null` |
| `OctetString` | lowercase hex string, e.g. `"deadbeef"` |
| `ObjectIdentifier` | dotted-decimal, e.g. `"1.2.840.113549"` |
| `SequenceOf<T>` | JSON array |
| `Element` | `{"type":"<Name>","value":<value>}` |
### serde_cert.rs
Loads `tests/vectors/test_certificate.pem`, parses it with synta into an `Element` tree, serializes the tree to JSON, then deserializes the JSON into a `serde_json::Value` and prints both trees for comparison.
```bash
cargo run --example serde_cert --features serde
```
Demonstrates:
- Inline PEM decoding (strip armor, base64-decode)
- Parsing a real X.509 certificate as a generic `Element` tree
- Serializing the full ASN.1 tree to pretty-printed JSON
- Deserializing JSON into `serde_json::Value` (used because `Element` carries borrowed slices and cannot implement `Deserialize`)
- Side-by-side tree comparison with node counting
- JSON round-trip data integrity check
## Utility Tools
### asn1parse
A standalone example that parses PEM or DER files and displays the ASN.1
structure in `openssl asn1parse`-compatible format.
```bash
# Parse a PEM file
cargo run --example asn1parse certificate.pem
# Parse a DER file
cargo run --example asn1parse certificate.der
# Parse with offset
cargo run --example asn1parse data.der --offset 4
```
Output format matches `openssl asn1parse`:
```
0:d= 0 hl= 4 l= 853 cons: SEQUENCE
4:d= 1 hl= 4 l= 573 cons: SEQUENCE
8:d= 2 hl= 2 l= 3 cons: cont [ 0 ]
10:d= 3 hl= 2 l= 1 prim: INTEGER :02
13:d= 2 hl= 4 l= 567 cons: SEQUENCE
17:d= 3 hl= 2 l= 9 prim: OBJECT :1.2.840.113549.1.1.11
```
Where:
- First column: byte offset in file
- `d=N`: depth in ASN.1 tree
- `hl=N`: header length (tag + length bytes)
- `l=N`: content length
- `cons`/`prim`: constructed or primitive
- Type and optional value
> **Note:** For the full-featured tool with multiple output modes, hex input
> (including hexdump/Wireshark/xxd format), and text mode that shows decoded
> string values alongside hex, use `synta-tool asn1parse` from the
> `synta-tools` crate instead.
### generate_test_cert.rs
Generates invalid test certificate files for testing ASN.1 parsing edge cases.
```bash
cargo run --example generate_test_cert
```
Creates:
- `tests/vectors/invalid_test_certificate.der` - DER-encoded certificate with invalid public key
- `tests/vectors/invalid_test_certificate.pem` - PEM-encoded certificate with invalid public key
**Important:** This example generates certificates that are structurally valid ASN.1 but cryptographically invalid. The public key and signature are stub values (9 bytes each), which is insufficient for real RSA keys. OpenSSL will reject these certificates with "Unable to load Public Key" errors.
**Purpose:**
- Testing ASN.1 parser handling of edge cases
- Demonstrating difference between ASN.1 structural validity and cryptographic validity
- Error handling tests for applications that perform cryptographic validation
**For valid test certificates**, use OpenSSL:
```bash
cd tests/vectors
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout test_key.pem -out test_certificate.pem \
-days 365 -subj "/CN=Test CA"
openssl x509 -in test_certificate.pem -outform DER -out test_certificate.der
```
The repository includes both:
- `test_certificate.{pem,der}` - Valid certificates (generated with OpenSSL)
- `invalid_test_certificate.{pem,der}` - Invalid certificates (generated with this example)
## Comparing with OpenSSL
You can compare the output of `asn1parse` with OpenSSL's `asn1parse`:
```bash
# Synta
cargo run --example asn1parse tests/vectors/test_certificate.pem
# OpenSSL
openssl asn1parse -in tests/vectors/test_certificate.pem -inform PEM
```
The outputs should match in structure, offsets, and lengths. Synta shows numeric OIDs while OpenSSL may show friendly names for common OIDs.
## Running All Examples
```bash
# Run all examples
cargo run --example decode_integer
cargo run --example encode_sequence
cargo run --example oid_usage
cargo run --example parse_certificate
# Serde examples (require --features serde)
cargo run --example serde_usage --features serde
cargo run --example serde_cert --features serde
# Generate test data and parse it
cargo run --example generate_test_cert
cargo run --example asn1parse tests/vectors/test_certificate.pem
```
## See Also
- [Usage Guide](../docs/usage.md) - Comprehensive usage guide
- [Performance](../docs/performance.md) - Benchmark results, optimization history, and methodology
- [API Documentation](https://docs.rs/synta) - Complete API reference