pem_rfc7468/
lib.rs

1#![no_std]
2#![cfg_attr(docsrs, feature(doc_auto_cfg))]
3#![doc = include_str!("../README.md")]
4#![doc(
5    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
6    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
7)]
8#![deny(unsafe_code)]
9#![warn(
10    clippy::integer_arithmetic,
11    clippy::mod_module_files,
12    clippy::panic,
13    clippy::panic_in_result_fn,
14    clippy::unwrap_used,
15    missing_docs,
16    rust_2018_idioms,
17    unused_lifetimes,
18    unused_qualifications
19)]
20
21//! # Usage
22//!
23#![cfg_attr(feature = "std", doc = " ```")]
24#![cfg_attr(not(feature = "std"), doc = " ```ignore")]
25//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
26//! /// Example PEM document
27//! /// NOTE: do not actually put private key literals into your source code!!!
28//! let example_pem = "\
29//! -----BEGIN PRIVATE KEY-----
30//! MC4CAQAwBQYDK2VwBCIEIBftnHPp22SewYmmEoMcX8VwI4IHwaqd+9LFPj/15eqF
31//! -----END PRIVATE KEY-----
32//! ";
33//!
34//! // Decode PEM
35//! let (type_label, data) = pem_rfc7468::decode_vec(example_pem.as_bytes())?;
36//! assert_eq!(type_label, "PRIVATE KEY");
37//! assert_eq!(
38//!     data,
39//!     &[
40//!         48, 46, 2, 1, 0, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32, 23, 237, 156, 115, 233, 219,
41//!         100, 158, 193, 137, 166, 18, 131, 28, 95, 197, 112, 35, 130, 7, 193, 170, 157, 251,
42//!         210, 197, 62, 63, 245, 229, 234, 133
43//!     ]
44//! );
45//!
46//! // Encode PEM
47//! use pem_rfc7468::LineEnding;
48//! let encoded_pem = pem_rfc7468::encode_string(type_label, LineEnding::default(), &data)?;
49//! assert_eq!(&encoded_pem, example_pem);
50//! # Ok(())
51//! # }
52//! ```
53
54#[cfg(feature = "alloc")]
55#[macro_use]
56extern crate alloc;
57#[cfg(feature = "std")]
58extern crate std;
59
60mod decoder;
61mod encoder;
62mod error;
63mod grammar;
64
65pub use crate::{
66    decoder::{decode, decode_label, Decoder},
67    encoder::{encapsulated_len, encapsulated_len_wrapped, encode, encoded_len, Encoder},
68    error::{Error, Result},
69};
70pub use base64ct::LineEnding;
71
72#[cfg(feature = "alloc")]
73pub use crate::{decoder::decode_vec, encoder::encode_string};
74
75/// The pre-encapsulation boundary appears before the encapsulated text.
76///
77/// From RFC 7468 Section 2:
78/// > There are exactly five hyphen-minus (also known as dash) characters ("-")
79/// > on both ends of the encapsulation boundaries, no more, no less.
80const PRE_ENCAPSULATION_BOUNDARY: &[u8] = b"-----BEGIN ";
81
82/// The post-encapsulation boundary appears immediately after the encapsulated text.
83const POST_ENCAPSULATION_BOUNDARY: &[u8] = b"-----END ";
84
85/// Delimiter of encapsulation boundaries.
86const ENCAPSULATION_BOUNDARY_DELIMITER: &[u8] = b"-----";
87
88/// Width at which the Base64 body of RFC7468-compliant PEM is wrapped.
89///
90/// From [RFC7468 § 2]:
91///
92/// > Generators MUST wrap the base64-encoded lines so that each line
93/// > consists of exactly 64 characters except for the final line, which
94/// > will encode the remainder of the data (within the 64-character line
95/// > boundary), and they MUST NOT emit extraneous whitespace.  Parsers MAY
96/// > handle other line sizes.
97///
98/// [RFC7468 § 2]: https://datatracker.ietf.org/doc/html/rfc7468#section-2
99pub const BASE64_WRAP_WIDTH: usize = 64;
100
101/// Buffered Base64 decoder type.
102pub type Base64Decoder<'i> = base64ct::Decoder<'i, base64ct::Base64>;
103
104/// Buffered Base64 encoder type.
105pub type Base64Encoder<'o> = base64ct::Encoder<'o, base64ct::Base64>;
106
107/// Marker trait for types with an associated PEM type label.
108pub trait PemLabel {
109    /// Expected PEM type label for a given document, e.g. `"PRIVATE KEY"`
110    const PEM_LABEL: &'static str;
111
112    /// Validate that a given label matches the expected label.
113    fn validate_pem_label(actual: &str) -> Result<()> {
114        if Self::PEM_LABEL == actual {
115            Ok(())
116        } else {
117            Err(Error::UnexpectedTypeLabel {
118                expected: Self::PEM_LABEL,
119            })
120        }
121    }
122}
pem_rfc7468/lib.rs

pem_rfc7468/
lib.rs
