src/pem.rs - platform/external/rust/crates/x509-parser - Gitiles

 //! Decoding functions for PEM-encoded data
 //!
 //! A PEM object is a container, which can store (amongst other formats) a public X.509
 //! Certificate, or a CRL, etc. It contains only printable characters.
 //! PEM-encoded binary data is essentially a beginning and matching end tag that encloses
 //! base64-encoded binary data (see:
 //! <https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail>).
 //!
 //! # Examples
 //!
 //! To parse a certificate in PEM format, first create the `Pem` object, then decode
 //! contents:
 //!
 //! ```rust,no_run
 //! use x509_parser::pem::Pem;
 //! use x509_parser::x509::X509Version;
 //!
 //! static IGCA_PEM: &str = "../assets/IGC_A.pem";
 //!
 //! # fn main() {
 //! let data = std::fs::read(IGCA_PEM).expect("Could not read file");
 //! for pem in Pem::iter_from_buffer(&data) {
 //!     let pem = pem.expect("Reading next PEM block failed");
 //!     let x509 = pem.parse_x509().expect("X.509: decoding DER failed");
 //!     assert_eq!(x509.tbs_certificate.version, X509Version::V3);
 //! }
 //! # }
 //! ```
 //!
 //! This is the most direct method to parse PEM data.
 //!
 //! Another method to parse the certificate is to use `parse_x509_pem`:
 //!
 //! ```rust,no_run
 //! use x509_parser::pem::parse_x509_pem;
 //! use x509_parser::parse_x509_certificate;
 //!
 //! static IGCA_PEM: &[u8] = include_bytes!("../assets/IGC_A.pem");
 //!
 //! # fn main() {
 //! let res = parse_x509_pem(IGCA_PEM);
 //! match res {
 //!     Ok((rem, pem)) => {
 //!         assert!(rem.is_empty());
 //!         //
 //!         assert_eq!(pem.label, String::from("CERTIFICATE"));
 //!         //
 //!         let res_x509 = parse_x509_certificate(&pem.contents);
 //!         assert!(res_x509.is_ok());
 //!     },
 //!     _ => panic!("PEM parsing failed: {:?}", res),
 //! }
 //! # }
 //! ```
 //!
 //! Note that all methods require to store the `Pem` object in a variable, mainly because decoding
 //! the PEM object requires allocation of buffers, and that the lifetime of X.509 certificates will
 //! be bound to these buffers.

 use crate::certificate::X509Certificate;
 use crate::error::{PEMError, X509Error};
 use crate::parse_x509_certificate;
 use nom::{Err, IResult};
 use std::io::{BufRead, Cursor, Seek, SeekFrom};

 /// Representation of PEM data
 #[derive(PartialEq, Debug)]
 pub struct Pem {
     /// The PEM label
     pub label: String,
     /// The PEM decoded data
     pub contents: Vec<u8>,
 }

 #[deprecated(since = "0.8.3", note = "please use `parse_x509_pem` instead")]
 pub fn pem_to_der(i: &[u8]) -> IResult<&[u8], Pem, PEMError> {
     parse_x509_pem(i)
 }

 /// Read a PEM-encoded structure, and decode the base64 data
 ///
 /// Return a structure describing the PEM object: the enclosing tag, and the data.
 /// Allocates a new buffer for the decoded data.
 ///
 /// Note that only the *first* PEM block is decoded. To iterate all blocks from PEM data,
 /// use [`Pem::iter_from_buffer`].
 ///
 /// For X.509 (`CERTIFICATE` tag), the data is a certificate, encoded in DER. To parse the
 /// certificate content, use `Pem::parse_x509` or `parse_x509_certificate`.
 pub fn parse_x509_pem(i: &[u8]) -> IResult<&'_ [u8], Pem, PEMError> {
     let reader = Cursor::new(i);
     let res = Pem::read(reader);
     match res {
         Ok((pem, bytes_read)) => Ok((&i[bytes_read..], pem)),
         Err(e) => Err(Err::Error(e)),
     }
 }

 impl Pem {
     /// Read the next PEM-encoded structure, and decode the base64 data
     ///
     /// Returns the certificate (encoded in DER) and the number of bytes read.
     /// Allocates a new buffer for the decoded data.
     ///
     /// Note that a PEM file can contain multiple PEM blocks. This function returns the
     /// *first* decoded object, starting from the current reader position.
     /// To get all objects, call this function repeatedly until `PEMError::MissingHeader`
     /// is returned.
     ///
     /// # Examples
     /// ```
     /// let file = std::fs::File::open("assets/certificate.pem").unwrap();
     /// let subject = x509_parser::pem::Pem::read(std::io::BufReader::new(file))
     ///      .unwrap().0
     ///     .parse_x509().unwrap()
     ///     .tbs_certificate.subject.to_string();
     /// assert_eq!(subject, "CN=lists.for-our.info");
     /// ```
     pub fn read(mut r: impl BufRead + Seek) -> Result<(Pem, usize), PEMError> {
         let mut line = String::new();
         let label = loop {
             let num_bytes = r.read_line(&mut line)?;
             if num_bytes == 0 {
                 // EOF
                 return Err(PEMError::MissingHeader);
             }
             if !line.starts_with("-----BEGIN ") {
                 line.clear();
                 continue;
             }
             let mut iter = line.split_whitespace();
             let label = iter.nth(1).ok_or(PEMError::InvalidHeader)?;
             break label;
         };
         let label = label.split('-').next().ok_or(PEMError::InvalidHeader)?;
         let mut s = String::new();
         loop {
             let mut l = String::new();
             let num_bytes = r.read_line(&mut l)?;
             if num_bytes == 0 {
                 return Err(PEMError::IncompletePEM);
             }
             if l.starts_with("-----END ") {
                 // finished reading
                 break;
             }
             s.push_str(l.trim_end());
         }

         let contents = base64::decode(&s).or(Err(PEMError::Base64DecodeError))?;
         let pem = Pem {
             label: label.to_string(),
             contents,
         };
         Ok((pem, r.seek(SeekFrom::Current(0))? as usize))
     }

     /// Decode the PEM contents into a X.509 object
     pub fn parse_x509(&self) -> Result<X509Certificate, ::nom::Err<X509Error>> {
         parse_x509_certificate(&self.contents).map(|(_, x509)| x509)
     }

     /// Returns an iterator over the PEM-encapsulated parts of a buffer
     ///
     /// Only the sections enclosed in blocks starting with `-----BEGIN xxx-----`
     /// and ending with `-----END xxx-----` will be considered.
     /// Lines before, between or after such blocks will be ignored.
     ///
     /// The iterator is fallible: `next()` returns a `Result<Pem, PEMError>` object.
     /// An error indicates a block is present but invalid.
     ///
     /// If the buffer does not contain any block, iterator will be empty.
     pub fn iter_from_buffer(i: &[u8]) -> PemIterator<Cursor<&[u8]>> {
         let reader = Cursor::new(i);
         PemIterator { reader }
     }

     /// Returns an iterator over the PEM-encapsulated parts of a reader
     ///
     /// Only the sections enclosed in blocks starting with `-----BEGIN xxx-----`
     /// and ending with `-----END xxx-----` will be considered.
     /// Lines before, between or after such blocks will be ignored.
     ///
     /// The iterator is fallible: `next()` returns a `Result<Pem, PEMError>` object.
     /// An error indicates a block is present but invalid.
     ///
     /// If the reader does not contain any block, iterator will be empty.
     pub fn iter_from_reader<R: BufRead + Seek>(reader: R) -> PemIterator<R> {
         PemIterator { reader }
     }
 }

 /// Iterator over PEM-encapsulated blocks
 ///
 /// Only the sections enclosed in blocks starting with `-----BEGIN xxx-----`
 /// and ending with `-----END xxx-----` will be considered.
 /// Lines before, between or after such blocks will be ignored.
 ///
 /// The iterator is fallible: `next()` returns a `Result<Pem, PEMError>` object.
 /// An error indicates a block is present but invalid.
 ///
 /// If the buffer does not contain any block, iterator will be empty.
 #[allow(missing_debug_implementations)]
 pub struct PemIterator<Reader: BufRead + Seek> {
     reader: Reader,
 }

 impl<R: BufRead + Seek> Iterator for PemIterator<R> {
     type Item = Result<Pem, PEMError>;

     fn next(&mut self) -> Option<Self::Item> {
         if let Ok(&[]) = self.reader.fill_buf() {
             return None;
         }
         let reader = self.reader.by_ref();
         let r = Pem::read(reader).map(|(pem, _)| pem);
         if let Err(PEMError::MissingHeader) = r {
             None
         } else {
             Some(r)
         }
     }
 }

 #[cfg(test)]
 mod tests {
     use super::*;

     #[test]
     fn read_pem_from_file() {
         let file = std::io::BufReader::new(std::fs::File::open("assets/certificate.pem").unwrap());
         let subject = Pem::read(file)
             .unwrap()
             .0
             .parse_x509()
             .unwrap()
             .tbs_certificate
             .subject
             .to_string();
         assert_eq!(subject, "CN=lists.for-our.info");
     }
 }
	//! Decoding functions for PEM-encoded data
	//!
	//! A PEM object is a container, which can store (amongst other formats) a public X.509
	//! Certificate, or a CRL, etc. It contains only printable characters.
	//! PEM-encoded binary data is essentially a beginning and matching end tag that encloses
	//! base64-encoded binary data (see:
	//! <https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail>).
	//!
	//! # Examples
	//!
	//! To parse a certificate in PEM format, first create the `Pem` object, then decode
	//! contents:
	//!
	//! ```rust,no_run
	//! use x509_parser::pem::Pem;
	//! use x509_parser::x509::X509Version;
	//!
	//! static IGCA_PEM: &str = "../assets/IGC_A.pem";
	//!
	//! # fn main() {
	//! let data = std::fs::read(IGCA_PEM).expect("Could not read file");
	//! for pem in Pem::iter_from_buffer(&data) {
	//! let pem = pem.expect("Reading next PEM block failed");
	//! let x509 = pem.parse_x509().expect("X.509: decoding DER failed");
	//! assert_eq!(x509.tbs_certificate.version, X509Version::V3);
	//! }
	//! # }
	//! ```
	//!
	//! This is the most direct method to parse PEM data.
	//!
	//! Another method to parse the certificate is to use `parse_x509_pem`:
	//!
	//! ```rust,no_run
	//! use x509_parser::pem::parse_x509_pem;
	//! use x509_parser::parse_x509_certificate;
	//!
	//! static IGCA_PEM: &[u8] = include_bytes!("../assets/IGC_A.pem");
	//!
	//! # fn main() {
	//! let res = parse_x509_pem(IGCA_PEM);
	//! match res {
	//! Ok((rem, pem)) => {
	//! assert!(rem.is_empty());
	//! //
	//! assert_eq!(pem.label, String::from("CERTIFICATE"));
	//! //
	//! let res_x509 = parse_x509_certificate(&pem.contents);
	//! assert!(res_x509.is_ok());
	//! },
	//! _ => panic!("PEM parsing failed: {:?}", res),
	//! }
	//! # }
	//! ```
	//!
	//! Note that all methods require to store the `Pem` object in a variable, mainly because decoding
	//! the PEM object requires allocation of buffers, and that the lifetime of X.509 certificates will
	//! be bound to these buffers.

	use crate::certificate::X509Certificate;
	use crate::error::{PEMError, X509Error};
	use crate::parse_x509_certificate;
	use nom::{Err, IResult};
	use std::io::{BufRead, Cursor, Seek, SeekFrom};

	/// Representation of PEM data
	#[derive(PartialEq, Debug)]
	pub struct Pem {
	/// The PEM label
	pub label: String,
	/// The PEM decoded data
	pub contents: Vec<u8>,
	}

	#[deprecated(since = "0.8.3", note = "please use `parse_x509_pem` instead")]
	pub fn pem_to_der(i: &[u8]) -> IResult<&[u8], Pem, PEMError> {
	parse_x509_pem(i)
	}

	/// Read a PEM-encoded structure, and decode the base64 data
	///
	/// Return a structure describing the PEM object: the enclosing tag, and the data.
	/// Allocates a new buffer for the decoded data.
	///
	/// Note that only the first PEM block is decoded. To iterate all blocks from PEM data,
	/// use [`Pem::iter_from_buffer`].
	///
	/// For X.509 (`CERTIFICATE` tag), the data is a certificate, encoded in DER. To parse the
	/// certificate content, use `Pem::parse_x509` or `parse_x509_certificate`.
	pub fn parse_x509_pem(i: &[u8]) -> IResult<&'_ [u8], Pem, PEMError> {
	let reader = Cursor::new(i);
	let res = Pem::read(reader);
	match res {
	Ok((pem, bytes_read)) => Ok((&i[bytes_read..], pem)),
	Err(e) => Err(Err::Error(e)),
	}
	}

	impl Pem {
	/// Read the next PEM-encoded structure, and decode the base64 data
	///
	/// Returns the certificate (encoded in DER) and the number of bytes read.
	/// Allocates a new buffer for the decoded data.
	///
	/// Note that a PEM file can contain multiple PEM blocks. This function returns the
	/// first decoded object, starting from the current reader position.
	/// To get all objects, call this function repeatedly until `PEMError::MissingHeader`
	/// is returned.
	///
	/// # Examples
	/// ```
	/// let file = std::fs::File::open("assets/certificate.pem").unwrap();
	/// let subject = x509_parser::pem::Pem::read(std::io::BufReader::new(file))
	/// .unwrap().0
	/// .parse_x509().unwrap()
	/// .tbs_certificate.subject.to_string();
	/// assert_eq!(subject, "CN=lists.for-our.info");
	/// ```
	pub fn read(mut r: impl BufRead + Seek) -> Result<(Pem, usize), PEMError> {
	let mut line = String::new();
	let label = loop {
	let num_bytes = r.read_line(&mut line)?;
	if num_bytes == 0 {
	// EOF
	return Err(PEMError::MissingHeader);
	}
	if !line.starts_with("-----BEGIN ") {
	line.clear();
	continue;
	}
	let mut iter = line.split_whitespace();
	let label = iter.nth(1).ok_or(PEMError::InvalidHeader)?;
	break label;
	};
	let label = label.split('-').next().ok_or(PEMError::InvalidHeader)?;
	let mut s = String::new();
	loop {
	let mut l = String::new();
	let num_bytes = r.read_line(&mut l)?;
	if num_bytes == 0 {
	return Err(PEMError::IncompletePEM);
	}
	if l.starts_with("-----END ") {
	// finished reading
	break;
	}
	s.push_str(l.trim_end());
	}

	let contents = base64::decode(&s).or(Err(PEMError::Base64DecodeError))?;
	let pem = Pem {
	label: label.to_string(),
	contents,
	};
	Ok((pem, r.seek(SeekFrom::Current(0))? as usize))
	}

	/// Decode the PEM contents into a X.509 object
	pub fn parse_x509(&self) -> Result<X509Certificate, ::nom::Err<X509Error>> {
	parse_x509_certificate(&self.contents).map(\|(_, x509)\| x509)
	}

	/// Returns an iterator over the PEM-encapsulated parts of a buffer
	///
	/// Only the sections enclosed in blocks starting with `-----BEGIN xxx-----`
	/// and ending with `-----END xxx-----` will be considered.
	/// Lines before, between or after such blocks will be ignored.
	///
	/// The iterator is fallible: `next()` returns a `Result<Pem, PEMError>` object.
	/// An error indicates a block is present but invalid.
	///
	/// If the buffer does not contain any block, iterator will be empty.
	pub fn iter_from_buffer(i: &[u8]) -> PemIterator<Cursor<&[u8]>> {
	let reader = Cursor::new(i);
	PemIterator { reader }
	}

	/// Returns an iterator over the PEM-encapsulated parts of a reader
	///
	/// Only the sections enclosed in blocks starting with `-----BEGIN xxx-----`
	/// and ending with `-----END xxx-----` will be considered.
	/// Lines before, between or after such blocks will be ignored.
	///
	/// The iterator is fallible: `next()` returns a `Result<Pem, PEMError>` object.
	/// An error indicates a block is present but invalid.
	///
	/// If the reader does not contain any block, iterator will be empty.
	pub fn iter_from_reader<R: BufRead + Seek>(reader: R) -> PemIterator<R> {
	PemIterator { reader }
	}
	}

	/// Iterator over PEM-encapsulated blocks
	///
	/// Only the sections enclosed in blocks starting with `-----BEGIN xxx-----`
	/// and ending with `-----END xxx-----` will be considered.
	/// Lines before, between or after such blocks will be ignored.
	///
	/// The iterator is fallible: `next()` returns a `Result<Pem, PEMError>` object.
	/// An error indicates a block is present but invalid.
	///
	/// If the buffer does not contain any block, iterator will be empty.
	#[allow(missing_debug_implementations)]
	pub struct PemIterator<Reader: BufRead + Seek> {
	reader: Reader,
	}

	impl<R: BufRead + Seek> Iterator for PemIterator<R> {
	type Item = Result<Pem, PEMError>;

	fn next(&mut self) -> Option<Self::Item> {
	if let Ok(&[]) = self.reader.fill_buf() {
	return None;
	}
	let reader = self.reader.by_ref();
	let r = Pem::read(reader).map(\|(pem, _)\| pem);
	if let Err(PEMError::MissingHeader) = r {
	None
	} else {
	Some(r)
	}
	}
	}

	#[cfg(test)]
	mod tests {
	use super::*;

	#[test]
	fn read_pem_from_file() {
	let file = std::io::BufReader::new(std::fs::File::open("assets/certificate.pem").unwrap());
	let subject = Pem::read(file)
	.unwrap()
	.0
	.parse_x509()
	.unwrap()
	.tbs_certificate
	.subject
	.to_string();
	assert_eq!(subject, "CN=lists.for-our.info");
	}
	}