[![Pipeline](https://gitlab.com/coroner/cryptoparser/badges/master/pipeline.svg)](https://gitlab.com/coroner/cryptoparser/-/pipelines/master/latest)
[![Test Coverage](https://coveralls.io/repos/gitlab/coroner/cryptoparser/badge.svg?branch=master)](https://coveralls.io/gitlab/coroner/cryptoparser/)
[![Documentation](https://readthedocs.org/projects/cryptoparser/badge/?version=latest)](https://cryptoparser.readthedocs.io)

<!-- documentation-summary-start -->
**CryptoParser** is a cryptographic protocol
([IKE](https://en.wikipedia.org/wiki/Internet_Key_Exchange),
[SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0,_2.0,_and_3.0),
[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security),
[SSH](https://en.wikipedia.org/wiki/Secure_Shell),
[DNSSEC](https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions)) and security-related protocol piece
([HTTP headers](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields)) parser and generator. It is neither a
comprehensive nor a secure implementation of any cryptographic protocol. The goal is to support testing cryptographic
libraries or analysing cryptography-related settings of application servers such as
[CryptoLyzer](https://cryptolyzer.readthedocs.io/) does.

**Use CryptoParser when you need to parse handshake messages** — it implements the wire format of ISAKMP, IKEv1, IKEv2,
SSL 2.0, SSL 3.0, TLS 1.0 to TLS 1.3, and SSH 2.0, so a message can be read field by field instead of being handed to a
connection-oriented library.

**Use CryptoParser when you need to generate messages a library refuses to send** — analysis means triggering special
and corner cases, so messages can be composed with deprecated, experimental, or plainly invalid values that an
implementation aiming for secure connections would reject.

**Use CryptoParser when you need parsed HTTP security headers** — beyond wire format parsing it parses individual
headers, so directives are available as typed values rather than as strings.

**Use CryptoParser when you need DNSSEC record parsing** — DNSSEC records are parsed into the same kind of typed
structures as the protocol messages.
<!-- documentation-summary-end -->

<!-- documentation-strength-start -->
The strength of CryptoParser is that it is backed by the most comprehensive algorithm identifier database available
([CryptoDataHub](https://cryptodatahub.readthedocs.io)). This makes it possible to recognize rarely used, deprecated,
non-standard, or experimental algorithms that are not supported by any version of OpenSSL, GnuTLS, LibreSSL, or
wolfSSL.
<!-- documentation-strength-end -->

## Why CryptoParser?

<!-- documentation-comparison-start -->
- **Analysis oriented** — the library implements only the parts of a protocol that analysis needs, and deliberately
  keeps the parts that make a message invalid.
- **No OpenSSL dependency** — the protocol implementation is its own, so what can be parsed or generated is not limited
  by what a cryptographic library is willing to do.
- **Typed values, not byte offsets** — algorithm identifiers, protocol versions, and header directives are parsed into
  enumerations and attribute classes.
- **Symmetric parsing and composing** — every parsable piece can also be composed back to its wire format.
<!-- documentation-comparison-end -->

## Usage

### uv

```shell
uv add cryptoparser
```

```python
from cryptoparser.tls.version import TlsProtocolVersion

# parse a protocol version from its wire format
TlsProtocolVersion.parse_exact_size(b'\x03\x03')
# TLS 1.2

# compose a protocol version back to its wire format
TlsProtocolVersion.parse_exact_size(b'\x03\x04').compose()
# bytearray(b'\x03\x04')
```

## Support

**Python implementations**

- CPython 3.9+
- PyPy 3.9+

**Operating systems**

- Linux
- macOS
- Windows

## Documentation

Detailed [documentation](https://cryptoparser.readthedocs.io) is available on the project's
[Read the Docs](https://readthedocs.com) site.

## License

The [code](https://gitlab.com/coroner/cryptoparser) is available under the terms of
[Mozilla Public License Version 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL 2.0).

A non-comprehensive but straightforward description of MPL 2.0 can be found at the
[Choose an open source license](https://choosealicense.com/licenses#mpl-2.0) website.

## Credits

- [NLnet Foundation](https://nlnet.nl) and [NGI Assure](https://www.assure.ngi.eu), supports the project part of the
  [Next Generation Internet](https://ngi.eu) initiative.
