x509_parser/
lib.rs

1//! [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE-MIT)
2//! [![Apache License 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE-APACHE)
3//! [![docs.rs](https://docs.rs/x509-parser/badge.svg)](https://docs.rs/x509-parser)
4//! [![crates.io](https://img.shields.io/crates/v/x509-parser.svg)](https://crates.io/crates/x509-parser)
5//! [![Download numbers](https://img.shields.io/crates/d/x509-parser.svg)](https://crates.io/crates/x509-parser)
6//! [![Github CI](https://github.com/rusticata/x509-parser/workflows/Continuous%20integration/badge.svg)](https://github.com/rusticata/x509-parser/actions)
7//! [![Minimum rustc version](https://img.shields.io/badge/rustc-1.67.1+-lightgray.svg)](#rust-version-requirements)
8//!
9//! # X.509 Parser
10//!
11//! A X.509 v3 ([RFC5280]) parser, implemented with the [nom](https://github.com/Geal/nom)
12//! parser combinator framework.
13//!
14//! It is written in pure Rust, fast, and makes extensive use of zero-copy. A lot of care is taken
15//! to ensure security and safety of this crate, including design (recursion limit, defensive
16//! programming), tests, and fuzzing. It also aims to be panic-free.
17//!
18//! The code is available on [Github](https://github.com/rusticata/x509-parser)
19//! and is part of the [Rusticata](https://github.com/rusticata) project.
20//!
21//! Certificates are usually encoded in two main formats: PEM (usually the most common format) or
22//! DER.  A PEM-encoded certificate is a container, storing a DER object. See the
23//! [`pem`](pem/index.html) module for more documentation.
24//!
25//! To decode a DER-encoded certificate, the main parsing method is
26//! `X509Certificate::from_der` (
27//! part of the [`FromDer`](prelude/trait.FromDer.html) trait
28//! ), which builds a
29//! [`X509Certificate`](certificate/struct.X509Certificate.html) object.
30//!
31//! An alternative method is to use [`X509CertificateParser`](certificate/struct.X509CertificateParser.html),
32//! which allows specifying parsing options (for example, not automatically parsing option contents).
33//!
34//! The returned objects for parsers follow the definitions of the RFC. This means that accessing
35//! fields is done by accessing struct members recursively. Some helper functions are provided, for
36//! example [`X509Certificate::issuer()`](certificate/struct.X509Certificate.html#method.issuer) returns the
37//! same as accessing `<object>.tbs_certificate.issuer`.
38//!
39//! For PEM-encoded certificates, use the [`pem`](pem/index.html) module.
40//!
41//! This crate also provides visitor traits: [`X509CertificateVisitor`](crate::visitor::X509CertificateVisitor).
42//!
43//! # Examples
44//!
45//! Parsing a certificate in DER format:
46//!
47//! ```rust
48//! use x509_parser::prelude::*;
49//!
50//! static IGCA_DER: &[u8] = include_bytes!("../assets/IGC_A.der");
51//!
52//! # fn main() {
53//! let res = X509Certificate::from_der(IGCA_DER);
54//! match res {
55//!     Ok((rem, cert)) => {
56//!         assert!(rem.is_empty());
57//!         //
58//!         assert_eq!(cert.version(), X509Version::V3);
59//!     },
60//!     _ => panic!("x509 parsing failed: {:?}", res),
61//! }
62//! # }
63//! ```
64//!
65//! To parse a CRL and print information about revoked certificates:
66//!
67//! ```rust
68//! # use x509_parser::prelude::*;
69//! #
70//! # static DER: &[u8] = include_bytes!("../assets/example.crl");
71//! #
72//! # fn main() {
73//! let res = CertificateRevocationList::from_der(DER);
74//! match res {
75//!     Ok((_rem, crl)) => {
76//!         for revoked in crl.iter_revoked_certificates() {
77//!             println!("Revoked certificate serial: {}", revoked.raw_serial_as_string());
78//!             println!("  Reason: {}", revoked.reason_code().unwrap_or_default().1);
79//!         }
80//!     },
81//!     _ => panic!("CRL parsing failed: {:?}", res),
82//! }
83//! # }
84//! ```
85//!
86//! See also `examples/print-cert.rs`.
87//!
88//! # Features
89//!
90//! - The `verify` feature adds support for (cryptographic) signature verification, based on `ring`.
91//!   It adds the
92//!   [`X509Certificate::verify_signature()`](certificate/struct.X509Certificate.html#method.verify_signature)
93//!   to `X509Certificate`.
94//!
95//! ```rust
96//! # #[cfg(feature = "verify")]
97//! # use x509_parser::certificate::X509Certificate;
98//! /// Cryptographic signature verification: returns true if certificate was signed by issuer
99//! #[cfg(feature = "verify")]
100//! pub fn check_signature(cert: &X509Certificate<'_>, issuer: &X509Certificate<'_>) -> bool {
101//!     let issuer_public_key = issuer.public_key();
102//!     cert
103//!         .verify_signature(Some(issuer_public_key))
104//!         .is_ok()
105//! }
106//! ```
107//!
108//! - The `validate` features add methods to run more validation functions on the certificate structure
109//!   and values using the [`Validate`](validate/trait.Validate.html) trait.
110//!   It does not validate any cryptographic parameter (see `verify` above).
111//!
112//! ## Rust version requirements
113//!
114//! `x509-parser` requires **Rustc version 1.67.1 or greater**, based on der-parser
115//! dependencies and for proc-macro attributes support.
116//!
117//! [RFC5280]: https://tools.ietf.org/html/rfc5280
118
119#![deny(/*missing_docs,*/
120        unstable_features,
121        unused_import_braces, unused_qualifications)]
122#![warn(
123    missing_debug_implementations,
124    /* missing_docs,
125    rust_2018_idioms,*/
126    unreachable_pub
127)]
128#![forbid(unsafe_code)]
129#![deny(rustdoc::broken_intra_doc_links)]
130#![doc(test(
131    no_crate_inject,
132    attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
133))]
134#![cfg_attr(docsrs, feature(doc_cfg))]
135
136pub mod certificate;
137pub mod certification_request;
138pub mod cri_attributes;
139pub mod error;
140pub mod extensions;
141pub mod objects;
142pub mod pem;
143pub mod prelude;
144pub mod public_key;
145pub mod revocation_list;
146pub mod signature_algorithm;
147pub mod signature_value;
148pub mod time;
149pub mod utils;
150#[cfg(feature = "validate")]
151#[cfg_attr(docsrs, doc(cfg(feature = "validate")))]
152pub mod validate;
153#[cfg(feature = "verify")]
154#[cfg_attr(docsrs, doc(cfg(feature = "verify")))]
155pub mod verify;
156pub mod visitor;
157pub mod x509;
158
159// reexports
160pub use asn1_rs;
161pub use der_parser;
162pub use der_parser::num_bigint;
163pub use nom;
164pub use oid_registry;
165
166use asn1_rs::FromDer;
167use certificate::X509Certificate;
168use error::X509Result;
169use revocation_list::CertificateRevocationList;
170
171/// Parse a **DER-encoded** X.509 Certificate, and return the remaining of the input and the built
172/// object.
173///
174///
175/// This function is an alias to [X509Certificate::from_der](certificate::X509Certificate::from_der). See this function
176/// for more information.
177///
178/// For PEM-encoded certificates, use the [`pem`](pem/index.html) module.
179#[inline]
180pub fn parse_x509_certificate(i: &[u8]) -> X509Result<X509Certificate> {
181    X509Certificate::from_der(i)
182}
183
184/// Parse a DER-encoded X.509 v2 CRL, and return the remaining of the input and the built
185/// object.
186///
187/// This function is an alias to [CertificateRevocationList::from_der](revocation_list::CertificateRevocationList::from_der). See this function
188/// for more information.
189#[inline]
190pub fn parse_x509_crl(i: &[u8]) -> X509Result<CertificateRevocationList> {
191    CertificateRevocationList::from_der(i)
192}
193
194/// Parse a DER-encoded X.509 Certificate, and return the remaining of the input and the built
195#[deprecated(
196    since = "0.9.0",
197    note = "please use `parse_x509_certificate` or `X509Certificate::from_der` instead"
198)]
199#[inline]
200pub fn parse_x509_der(i: &[u8]) -> X509Result<X509Certificate> {
201    X509Certificate::from_der(i)
202}
203
204/// Parse a DER-encoded X.509 v2 CRL, and return the remaining of the input and the built
205/// object.
206#[deprecated(
207    since = "0.9.0",
208    note = "please use `parse_x509_crl` or `CertificateRevocationList::from_der` instead"
209)]
210#[inline]
211pub fn parse_crl_der(i: &[u8]) -> X509Result<CertificateRevocationList> {
212    CertificateRevocationList::from_der(i)
213}