• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!-- cargo-sync-readme start -->
2
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE-MIT)
4[![Apache License 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE-APACHE)
5[![docs.rs](https://docs.rs/x509-parser/badge.svg)](https://docs.rs/x509-parser)
6[![crates.io](https://img.shields.io/crates/v/x509-parser.svg)](https://crates.io/crates/x509-parser)
7[![Download numbers](https://img.shields.io/crates/d/x509-parser.svg)](https://crates.io/crates/x509-parser)
8[![Github CI](https://github.com/rusticata/x509-parser/workflows/Continuous%20integration/badge.svg)](https://github.com/rusticata/x509-parser/actions)
9[![Minimum rustc version](https://img.shields.io/badge/rustc-1.46.0+-lightgray.svg)](#rust-version-requirements)
10
11# X.509 Parser
12
13A X.509 v3 ([RFC5280]) parser, implemented with the [nom](https://github.com/Geal/nom)
14parser combinator framework.
15
16It is written in pure Rust, fast, and makes extensive use of zero-copy. A lot of care is taken
17to ensure security and safety of this crate, including design (recursion limit, defensive
18programming), tests, and fuzzing. It also aims to be panic-free.
19
20The code is available on [Github](https://github.com/rusticata/x509-parser)
21and is part of the [Rusticata](https://github.com/rusticata) project.
22
23Certificates are usually encoded in two main formats: PEM (usually the most common format) or
24DER.  A PEM-encoded certificate is a container, storing a DER object. See the
25[`pem`](https://docs.rs/x509-parser/latest/x509_parser/pem/index.html) module for more documentation.
26
27To decode a DER-encoded certificate, the main parsing method is
28[`X509Certificate::from_der`] (
29part of the [`FromDer`](https://docs.rs/x509-parser/latest/x509_parser/traits/trait.FromDer.html) trait
30), which builds a
31[`X509Certificate`](https://docs.rs/x509-parser/latest/x509_parser/certificate/struct.X509Certificate.html) object.
32
33An alternative method is to use [`X509CertificateParser`](https://docs.rs/x509-parser/latest/x509_parser/certificate/struct.X509CertificateParser.html),
34which allows specifying parsing options (for example, not automatically parsing option contents).
35
36The returned objects for parsers follow the definitions of the RFC. This means that accessing
37fields is done by accessing struct members recursively. Some helper functions are provided, for
38example [`X509Certificate::issuer()`](https://docs.rs/x509-parser/latest/x509_parser/certificate/struct.X509Certificate.html#method.issuer) returns the
39same as accessing `<object>.tbs_certificate.issuer`.
40
41For PEM-encoded certificates, use the [`pem`](https://docs.rs/x509-parser/latest/x509_parser/pem/index.html) module.
42
43# Examples
44
45Parsing a certificate in DER format:
46
47```rust
48use x509_parser::prelude::*;
49
50static IGCA_DER: &[u8] = include_bytes!("../assets/IGC_A.der");
51
52let res = X509Certificate::from_der(IGCA_DER);
53match res {
54    Ok((rem, cert)) => {
55        assert!(rem.is_empty());
56        //
57        assert_eq!(cert.version(), X509Version::V3);
58    },
59    _ => panic!("x509 parsing failed: {:?}", res),
60}
61```
62
63To parse a CRL and print information about revoked certificates:
64
65```rust
66#
67#
68let res = CertificateRevocationList::from_der(DER);
69match res {
70    Ok((_rem, crl)) => {
71        for revoked in crl.iter_revoked_certificates() {
72            println!("Revoked certificate serial: {}", revoked.raw_serial_as_string());
73            println!("  Reason: {}", revoked.reason_code().unwrap_or_default().1);
74        }
75    },
76    _ => panic!("CRL parsing failed: {:?}", res),
77}
78```
79
80See also `examples/print-cert.rs`.
81
82# Features
83
84- The `verify` feature adds support for (cryptographic) signature verification, based on `ring`.
85  It adds the
86  [`X509Certificate::verify_signature()`](https://docs.rs/x509-parser/latest/x509_parser/certificate/struct.X509Certificate.html#method.verify_signature)
87  to `X509Certificate`.
88
89```rust
90/// Cryptographic signature verification: returns true if certificate was signed by issuer
91#[cfg(feature = "verify")]
92pub fn check_signature(cert: &X509Certificate<'_>, issuer: &X509Certificate<'_>) -> bool {
93    let issuer_public_key = issuer.public_key();
94    cert
95        .verify_signature(Some(issuer_public_key))
96        .is_ok()
97}
98```
99
100- The `validate` features add methods to run more validation functions on the certificate structure
101  and values using the [`Validate`](https://docs.rs/x509-parser/latest/x509_parser/validate/trait.Validate.html) trait.
102  It does not validate any cryptographic parameter (see `verify` above).
103
104## Rust version requirements
105
106`x509-parser` requires **Rustc version 1.46 or greater**, based on nom 7
107dependencies and for proc-macro attributes support.
108
109[RFC5280]: https://tools.ietf.org/html/rfc5280
110<!-- cargo-sync-readme end -->
111
112## Changes
113
114See [CHANGELOG.md](CHANGELOG.md)
115
116# License
117
118Licensed under either of
119
120 * Apache License, Version 2.0
121   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
122 * MIT license
123   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
124
125at your option.
126
127## Contribution
128
129Unless you explicitly state otherwise, any contribution intentionally submitted
130for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
131dual licensed as above, without any additional terms or conditions.
132