Crate pem_rfc7468

Pure Rust implementation of PEM Encoding (RFC 7468) for PKIX, PKCS, and CMS Structures, a strict subset of the original Privacy-Enhanced Mail encoding intended specifically for use with cryptographic keys, certificates, and other messages.

Provides a no_std-friendly, constant-time implementation suitable for use with cryptographic private keys.

About

Many cryptography-related document formats, such as certificates (PKIX), private and public keys/keypairs (PKCS), and other cryptographic messages (CMS) provide an ASCII encoding which can be traced back to Privacy-Enhanced Mail (PEM) as defined in RFC 1421, which look like the following:

-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIBftnHPp22SewYmmEoMcX8VwI4IHwaqd+9LFPj/15eqF
-----END PRIVATE KEY-----

However, all of these formats actually implement a text-based encoding that is similar to, but not identical with, the legacy PEM encoding as described in RFC 1421.

For this reason, RFC 7468 was created to describe a stricter form of “PEM encoding” for use in these applications which codifies the previously de facto rules that most implementations operate by, and makes recommendations to promote interoperability.

This crate attempts to implement a strict interpretation of the RFC 7468 rules, implementing all of the MUSTs and SHOULDs while avoiding the MAYs, and targeting the “ABNF (Strict)” subset of the grammar as described in RFC 7468 Section 3 Figure 3 (p6).

Implementation

The implementation of this crate takes great care to operate in constant-time whenever possible by avoiding branching on any values which may contain secret data.

It uses the base64ct crate for Base64 decoding/encoding, which provides a portable constant-time implementation of the Base64 format.

The implementation also avoids heap allocations by default, allowing it to work in “heapless” no_std environments.

Minimum Supported Rust Version

This crate requires Rust 1.51 at a minimum.

Usage

/// Example PEM document
/// NOTE: do not actually put private key literals into your source code!!!
let example_pem = "\
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIBftnHPp22SewYmmEoMcX8VwI4IHwaqd+9LFPj/15eqF
-----END PRIVATE KEY-----
";

// Decode PEM
let (type_label, data) = pem_rfc7468::decode_vec(example_pem.as_bytes())?;
assert_eq!(type_label, "PRIVATE KEY");
assert_eq!(
    data,
    &[
        48, 46, 2, 1, 0, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32, 23, 237, 156, 115, 233, 219,
        100, 158, 193, 137, 166, 18, 131, 28, 95, 197, 112, 35, 130, 7, 193, 170, 157, 251,
        210, 197, 62, 63, 245, 229, 234, 133
    ]
);

// Encode PEM
let encoded_pem = pem_rfc7468::encode_string(type_label, &data)?;
assert_eq!(&encoded_pem, example_pem);

Enums

Error

Error type

Functions

decode

Decode a PEM document according to RFC 7468’s “Strict” grammar.

decode_vecalloc

Decode a PEM document according to RFC 7468’s “Strict” grammar, returning the result as a Vec upon success.

encode

Encode a PEM document according to RFC 7468’s “Strict” grammar.

encode_stringalloc

Encode a PEM document according to RFC 7468’s “Strict” grammar, returning the result as a String.

encoded_len

Get the length of a PEM encoded document with the given bytes and label.

Type Definitions

Result

Result type