# CryptoParser

An analysis-oriented cryptographic protocol parser and generator. Parses and composes TLS, SSL, SSH, DNSSEC, IKE, and HTTP security headers from raw bytes to typed Python objects. Not a comprehensive or secure implementation — designed for testing and analysis purposes.

## Files

### Project Root
- `pyproject.toml` — Build system, dependencies, metadata (setuptools + setuptools-scm)
- `setup.py` — Delegates to pyproject.toml
- `README.md` — Project overview, install instructions, license
- `CHANGELOG.rst` — Versioned changelog
- `CONTRIBUTING.rst` — Contribution guidelines
- `LICENSE.txt` — MPL-2.0

### Common Infrastructure (`cryptoparser/common/`)
- `parse.py` — Core parsing/composing engine: `ParserBinary`, `ParserText`, `ComposerBinary`, `ComposerText`, `ParsableBase`, `ByteOrder`
- `base.py` — Reusable parseable types: `Serializable`, `ProtocolVersionBase`, `VectorParsable`, `VariantParsable`, `Opaque`, `ListParsable`, enum parsers (1/2/3-byte)
- `field.py` — Structured text field parsing: `FieldParsableBase`, `NameValuePair`, quoted strings, URLs, datetimes, percentages, key=value components
- `exception.py` — Parser exceptions: `InvalidDataLength`, `NotEnoughData`, `TooMuchData`, `InvalidType`
- `classes.py` — Generic domain classes: `LanguageTag` (RFC 5646)
- `utils.py` — Utility: `get_leaf_classes()`, `bytes_to_hex_string()`
- `x509.py` — X.509 Certificate Transparency: `SignedCertificateTimestamp`, `SignedCertificateTimestampList`

### TLS/SSL (`cryptoparser/tls/`)
- `record.py` — TLS record layer (5-byte header: content type, version, fragment length), dispatches to subprotocol parsers
- `subprotocol.py` — TLS/SSL handshake messages: `ClientHello`, `ServerHello`, `Certificate`, `ServerKeyExchange`, `Finished`, `Alert`, `ApplicationData`, `ChangeCipherSpec`
- `extension.py` — TLS extensions: SNI, ALPN, supported groups, key share, signature algorithms, PSK, GREASE, and ~40 more
- `version.py` — TLS/SSL version handling: `TlsProtocolVersion`, `TlsVersionFactory`
- `ciphersuite.py` — Ciphersuite factories: `TlsCipherSuiteFactory`, `SslCipherKindFactory`
- `algorithm.py` — Algorithm factories: named curves, signature algorithms, EC point formats
- `grease.py` — GREASE (Generate Random Extensions And Sustain Extensibility) handling
- `ldap.py` — LDAP StartTLS protocol parser
- `mysql.py` — MySQL protocol parser (handshake, SSL request)
- `openvpn.py` — OpenVPN control channel packet parser
- `postgresql.py` — PostgreSQL StartTLS protocol parser
- `rdp.py` — RDP protocol parser (TPKT/X.224 encapsulation to extract TLS)

### SSH (`cryptoparser/ssh/`)
- `record.py` — SSH record layer (binary packet framing: length, padding, message code)
- `subprotocol.py` — SSH transport messages: `SshMessageKexInit`, `SshMessageKexDHInit`, `SshMessageKexDHReply`, `SshMessageNewKeys`
- `key.py` — SSH public/private key parsing: RSA, DSA, ECDSA, Ed25519, Ed448, X25519, X448; OpenSSH private key format, known_hosts, authorized_keys
- `version.py` — SSH version banner parsing: `SshVersion`, `SshProtocolVersion`, `SshVersionBanner`, `SshComment`

### DNSSEC (`cryptoparser/dnsrec/`)
- `record.py` — DNS resource records: DNSKEY, DS, RRSIG, NSEC, NSEC3, NSEC3PARAM, CDNSKEY, CDS, TLSA, SSHFP
- `txt.py` — DNS TXT record content: SPF, DKIM, DMARC, MTA-STS, TLSRPT, SMIMEA, CAA

### HTTP Headers (`cryptoparser/httpx/`)
- `header.py` — HTTP security headers: HSTS, CSP, HPKP, Expect-CT, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Feature-Policy, Permissions-Policy, Cross-Origin headers, Set-Cookie, Cache-Control, WWW-Authenticate
- `parse.py` — HTTP-specific field value components
- `version.py` — `HttpVersion` enum (HTTP/1.0, HTTP/1.1)

### IKE (`cryptoparser/ike/`)
- `isakmp.py` — ISAKMP header parser (cookies, version, exchange type, flags)
- `ikev1.py` — IKEv1 payloads: SA, Proposal, Transform, KE, ID, Cert, Auth, Nonce, Notify, Delete, VendorID
- `ikev2.py` — IKEv2 payloads: SA, Proposal, Transform, KE, IDi/IDr, Cert, Auth, Nonce, Notify, TS initiator/responder, Encrypted
- `common.py` — Common IKE data attributes (AF flag, transform types)
- `version.py` — ISAKMP version handling: `IsakmpVersion`, `IsakmpProtocolVersion`

### Tests (`test/`)
- `test/common/` — Common infrastructure tests: base classes, parsing engine, exceptions, field parsing, X.509
- `test/tls/` — TLS/SSL tests: records, handshakes, extensions, cipher suites, alerts, version, wrapped protocols
- `test/ssh/` — SSH tests: key parsing, records, subprotocols, version banners, cipher suites
- `test/dnsrec/` — DNS tests: DNSSEC binary records, TXT structured text
- `test/httpx/` — HTTP header tests: security headers, HTTP version
- `test/ike/` — IKE tests: IKEv1/IKEv2 payloads, SA/transform negotiation, ISAKMP header

## Architecture

The project uses a layered parser/composer design:

1. **Core** (`common/parse.py`) — `ParsableBase` abstract interface with `_parse()` returning `(object, bytes_consumed)`. `ParserBinary`/`ParserText` for input, `ComposerBinary`/`ComposerText` for output.
2. **Reusable types** (`common/base.py`) — Enum parsers (1/2/3-byte), vectors, variants, opaque blobs, lists, strings, protocol versions built on the core engine.
3. **Structured text** (`common/field.py`) — Name=value field parsing with typed components (strings, URLs, datetimes, quoted strings).
4. **Protocol modules** — Each protocol builds on common types to parse protocol-specific messages from raw bytes to typed Python objects.
5. **Enums/constants** — Defined in the `cryptodatahub` external library (submodule at `submodules/cryptodatahub/`).

## Key Patterns

- All parsable classes implement `_parse(cls, parseable,  bytes_consumed=None)` classmethod
- All composable classes implement `compose(self, composable)` method
- Protocol version classes implement `__lt__`, `__le__`, etc. for gradeable security assessment
- Factory classes wrap enum-based parsers (one-byte, two-byte) using `OneByteEnumParsable`/`TwoByteEnumParsable`
- `@attr.s` (attrs library) is used heavily for data classes with validators
