synta 0.2.6

# Shared Test Utilities

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Modules](#modules)
  - [`repo.rs` - Repository Management](#repors-repository-management)
  - [`parsing.rs` - Certificate Parsing](#parsingrs-certificate-parsing)
  - [`stats.rs` - Statistics Collection](#statsrs-statistics-collection)
- [Usage in Tests](#usage-in-tests)
- [Usage in Benchmarks](#usage-in-benchmarks)
- [Algorithm OID Reference](#algorithm-oid-reference)
  - [Signature Algorithms](#signature-algorithms)
  - [Public Key Algorithms](#public-key-algorithms)
- [File Extensions](#file-extensions)
- [Vector storage](#vector-storage)
- [Network Requirements](#network-requirements)
- [See Also](#see-also)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

This module provides shared infrastructure for both tests and benchmarks, ensuring consistent certificate handling across the project.

## Modules

### `repo.rs` - Repository Management

Handles git repository cloning and certificate file discovery.

**Key Components:**
- `RepoConfig` - Configuration for test repositories
- `setup_repository()` - Clone or reuse existing repositories
- `find_certificate_files_in_repo()` - Recursively find certificate files

**Supported Repositories:**
- `RepoConfig::CRYPTOGRAPHY` - Python Cryptography project (200+ certificates)
- `RepoConfig::LAMPS_ML_DSA` - IETF LAMPS ML-DSA certificates
- `RepoConfig::LAMPS_ML_KEM` - IETF LAMPS ML-KEM certificates

### `parsing.rs` - Certificate Parsing

Provides certificate parsing and algorithm identification.

**Key Components:**
- `parse_pem()` - Extract DER data from PEM format
- `parse_certificate_file()` - Parse PEM or DER certificate files
- `identify_cert_type()` - Identify signature and public key algorithms
- `CertType` - Classification of certificate algorithms
- `count_nodes()` - Count ASN.1 nodes in parsed tree

**Supported Algorithms:**
- Traditional: RSA, ECDSA, DSA, Ed25519, Ed448
- Post-Quantum: ML-DSA-44/65/87, ML-KEM-512/768/1024

### `stats.rs` - Statistics Collection

Tracks parsing results and generates summaries.

**Key Components:**
- `ParseStats` - Statistics tracker
- `print_summary()` - Format and display results
- `print_failed_files()` - List parsing failures

## Usage in Tests

```rust
mod test_utils;

use test_utils::{
    setup_repository, find_certificate_files_in_repo,
    parse_certificate_file, identify_cert_type,
    ParseStats, RepoConfig,
};

#[test]
fn my_test() {
    let repo_dir = setup_repository(&RepoConfig::CRYPTOGRAPHY).unwrap();
    let files = find_certificate_files_in_repo(&repo_dir, &RepoConfig::CRYPTOGRAPHY);

    for path in files {
        let (element, nodes) = parse_certificate_file(&path).unwrap();
        let cert_type = identify_cert_type(&element);
        println!("Parsed {} nodes, type: {}", nodes, cert_type.display());
    }
}
```

## Usage in Benchmarks

```rust
#[path = "../tests/test_utils/mod.rs"]
mod test_utils;

use test_utils::{setup_repository, find_certificate_files_in_repo, parse_certificate_file, RepoConfig};

fn bench_certificates(c: &mut Criterion) {
    let repo_dir = setup_repository(&RepoConfig::LAMPS_ML_DSA).unwrap();
    let files = find_certificate_files_in_repo(&repo_dir, &RepoConfig::LAMPS_ML_DSA);

    for path in files {
        c.bench_function("parse", |b| {
            b.iter(|| parse_certificate_file(&path));
        });
    }
}
```

## Algorithm OID Reference

### Signature Algorithms

| Algorithm | OID | Security |
|-----------|-----|----------|
| RSA       | 1.2.840.113549.1.1.* | Classical |
| ECDSA     | 1.2.840.10045.4.* | Classical |
| Ed25519   | 1.3.101.112 | Classical |
| Ed448     | 1.3.101.113 | Classical |
| DSA       | 1.2.840.10040.4.* | Classical |
| ML-DSA-44 | 2.16.840.1.101.3.4.3.17 | PQC Level 2 |
| ML-DSA-65 | 2.16.840.1.101.3.4.3.18 | PQC Level 3 |
| ML-DSA-87 | 2.16.840.1.101.3.4.3.19 | PQC Level 5 |

### Public Key Algorithms

| Algorithm | OID | Security |
|-----------|-----|----------|
| ML-KEM-512  | 2.16.840.1.101.3.4.4.1 | PQC Level 1 |
| ML-KEM-768  | 2.16.840.1.101.3.4.4.2 | PQC Level 3 |
| ML-KEM-1024 | 2.16.840.1.101.3.4.4.3 | PQC Level 5 |

## File Extensions

Supported certificate file extensions:
- `.pem` - PEM format (base64 encoded)
- `.der` - DER format (binary)
- `.crt` - Certificate files (PEM or DER)
- `.pub` - Public key files (SubjectPublicKeyInfo)

## Vector storage

External repositories are stored under `tests/vectors/` (the same location
as the committed test certificate files):

| Directory                                   | Contents                      |
|---------------------------------------------|-------------------------------|
| `tests/vectors/cryptography/`               | Python Cryptography x509      |
| `tests/vectors/dilithium-certificates/`     | LAMPS ML-DSA example certs    |
| `tests/vectors/kyber-certificates/`         | LAMPS ML-KEM example certs    |

These directories are listed in `.gitignore`.  Populate them by running:

```bash
bash tests/vectors/fetch.sh
```

`setup_repository()` checks for a pre-fetched directory first.  If not
found, it clones the repository into the same location on demand (requires
git and network access).  Subsequent calls reuse the existing directory.

## Network Requirements

First run (without pre-fetched vectors) requires:
- Git installed and in PATH
- Network access to github.com
- ~5-10 seconds for shallow clone

Subsequent runs use the on-disk directory and require no network access.

## See Also

- [../README.md](../README.md) - Test suite documentation
- [../../benches/README.md](../../benches/README.md) - Benchmark suite using these utilities
- [../../docs/POST_QUANTUM_OIDS.md](../../docs/POST_QUANTUM_OIDS.md) - Post-quantum cryptography OID reference