Skip to content

CPemChainFormat

Jay edited this page Oct 3, 2026 · 2 revisions

CPemChainFormat

#include <certpp/x509/chain/pem.hpp> --- certpp::x509 --- implements IChainFormat

The PEM container format (RFC 7468): a CCertCollection written as, and read back from, concatenated textual blocks -- -----BEGIN CERTIFICATE-----, base64, -----END CERTIFICATE-----, one after another, optionally interleaved with private-key blocks.

This class is the whole of this library's PEM handling: block scanning, encapsulation boundaries, labels, base64 framing and "this file also carries a private key" are container concerns, so they live here rather than in CCert, whose own native form is DER. CCert::importPem()/exportPem() are thin delegations to this class, kept because a single certificate in a file is the common case, not because they do the work.

PEM has no password and no encryption, and that is not a detail this class can soften. needsPassword() returns false, and the password argument of load()/save() is ignored outright: it is not checked, not compared, not used to derive anything, and nothing in a file this class writes is protected by it. Passing one buys exactly nothing. A private key written out by save() lands on disk as base64 of its plaintext DER -- anyone who can read the file has the key. When a key has to rest on disk or cross a network, that is what ECHAINFMT_PFX is for.

Because of that, writing keys is opt-in: save() writes certificates only unless the format was constructed with withPrivateKeys true, and IChainFormat::builtIn() hands back the certificates-only form. A caller who wants a key in the clear can say so in one argument; a caller who did not ask cannot get one by surprise.

Methods

explicit CPemChainFormat(bool withPrivateKeys = false)

Constructs the PEM format.

  • withPrivateKeys --- True to have save() write each entry's private key, in the clear, alongside its certificate. False -- the default, and what IChainFormat::builtIn() returns -- writes certificates only.

~CPemChainFormat() override = default

Destroys the format object. It holds no key material of its own.

EChainFormats format() const override

Returns which format this implementation handles.

Returns: Always ECHAINFMT_PEM.

bool needsPassword() const override

Reports whether this format requires a password.

Always false, and that is a warning rather than a convenience: PEM has no confidentiality whatsoever. A password handed to load() or save() is ignored, and a private key save() writes is readable by anyone who can read the file.

Returns: Always false.

bool includesPrivateKeys() const

Reports whether save() writes private keys.

Returns: True if this format object was constructed to write private keys in the clear.

static ERetCode nextBlock( const CString& text, size_t& cursor, CString& outLabel, COctet& outDer)

Reads the next RFC 7468 encapsulated block out of text, whatever its label.

This class owns this library's PEM framing, and a certificate collection is not its only consumer: a PKCS#10 request is a CERTIFICATE REQUEST block in exactly the same envelope, and CCertRequest::importPem() reads it through here rather than carrying a second scanner that could come to disagree with this one about what a PEM file is.

The body is base64-decoded but not parsed -- what the DER means is the caller's business, which is the whole reason this is label-agnostic.

  • text --- The PEM text to scan.
  • cursor --- Where to scan from; advanced past the block that was read.
  • outLabel --- Receives the block's label, without the dashes.
  • outDer --- Receives the decoded body.

Returns: ERET_OK on a block read; ERET_NOTFOUND once no -----BEGIN remains (the ordinary end of a scan, not an error); ERET_BADREQ for a boundary with no usable block behind it; ERET_NOTSUP for an RFC 1421 password-encrypted body, which this format cannot decrypt.

static bool appendBlock(CString& text, const char* label, const COctet& der)

Appends one RFC 7468 encapsulated block, base64 body wrapped at 64 characters.

  • text --- The text to append to.
  • label --- The label to use, without the dashes (e.g. "CERTIFICATE").
  • der --- The DER to encode as the block's body.

Returns: True on success, false if the base64 encoding or an append failed.

ERetCode load( const SReadOnlyByteSpan& data, const SReadOnlyByteSpan& password, CCertCollection& out ) const override

Reads concatenated PEM blocks into a collection, appending one entry per CERTIFICATE block, in the order the file lists them.

Everything outside the -----BEGIN/-----END boundaries is explanatory text, which RFC 7468 permits and this reader skips -- except that the text immediately preceding a CERTIFICATE block is scanned for openssl's own Bag Attributes header (friendlyName:/localKeyID:, what openssl pkcs12 -nokeys emits), so the PKCS#9 attributes an SCertEntry carries survive a PFX -> PEM -> PFX trip. Note that IChainFormat::detect() sniffs only the container's first bytes, so a file that opens with such text is not recognised there even though it loads perfectly well here.

A block whose label is not CERTIFICATE is treated as a candidate private key and tried against every certificate in the file, in file order, until one accepts it; acceptance is CCert::privateKey(IPrivateKeyPtr&)'s own public-key comparison, so a key is paired with the certificate it actually belongs to rather than with whichever one it happens to sit next to. A key block that pairs with nothing is dropped, which is the only way to read a file that carries somebody else's key alongside a certificate.

A certificate whose algorithm this library does not implement is loaded, not rejected: CCert::importDer() parses it fully and leaves keyAlgo()/signAlgo() as raw OID text, and dropping such an entry would lose a certificate the file genuinely contains and that the collection's name-based lookups still work on. What cannot be done with it is anything needing its key -- publicKey() is null, so no private key ever pairs with it and verifyLinks() reports it as unsupported.

Nothing is added to out until every block has been read, so a file that goes wrong half way through leaves the collection exactly as it was.

  • data --- The container's bytes.
  • password --- Ignored entirely -- PEM has no password. See this class's doc comment.
  • out --- Receives the entries, appended.

Returns: ERET_OK; ERET_BADREQ for empty input, a file with no CERTIFICATE block, a structurally broken block (a missing -----END, a body that is not base64) or a CERTIFICATE block that is not a well-formed X.509 certificate; ERET_NOTSUP for a password-encrypted key block (an ENCRYPTED PRIVATE KEY label, or RFC 1421's Proc-Type: 4,ENCRYPTED header), which this format cannot decrypt because it has no password to decrypt it with.

ERetCode save( const CCertCollection& in, const SReadOnlyByteSpan& password, CBuffer& out ) const override

Writes a collection out as concatenated PEM blocks: one CERTIFICATE block per entry, in collection order, each preceded by a Bag Attributes header when the entry carries a PKCS#9 friendlyName or localKeyId.

A private key is written only when this format object was constructed with withPrivateKeys true, and then in the clear -- see this class's doc comment. A key whose algorithm has no standard PEM encoding this library can build is left out rather than written as something non-standard, which is what CCert::exportPem() has always done.

  • in --- The collection; must not be empty.
  • password --- Ignored entirely -- PEM has no password, so there is nothing for one to protect.
  • out --- Receives the PEM text's bytes, replacing any content it held.

Returns: ERET_OK; ERET_BADREQ if the collection is empty or an entry's friendlyName contains a line break (which this one-line header cannot represent, and silently dropping it would lose data the caller set); ERET_INVAL if an entry's certificate is empty; ERET_KEY_ERROR if key writing is on and an entry's private key is not its certificate's own; ERET_NOMEM on allocation failure.

Example

Loads a PEM bundle as a collection, then writes the ordered chain back out. The format object is obtained from builtIn(), which returns the certificates-only form: writing private keys is a separate constructor argument because PEM has no encryption, so a key it writes is in the clear and should never be one a caller got by accident.

// given: const SReadOnlyByteSpan& pemFile
IChainFormatPtr pem = IChainFormat::builtIn(ECHAINFMT_PEM);
if (!pem) {
    return;
}

// The password argument is ignored outright in both directions -- needsPassword() is false,
// and that is a warning, not a convenience.
CCertCollection collection;
ERetCode rc = pem->load(pemFile, SReadOnlyByteSpan(), collection);
if (rc != ERET_OK) {
    return;         // ERET_BADREQ: malformed container. ERET_NOTSUP: an encrypted key block.
}

TArray<size_t> chain;
if (collection.buildChain(0, chain) != ECHAINRES_OK) {
    return;         // ordered, still not validated -- see CCertCollection
}

CBuffer out;
pem->save(collection, SReadOnlyByteSpan(), out);

Reference generated from certpp/x509/chain/pem.hpp at commit 0834b29 (v1.0.1). The header is authoritative --- if this page disagrees with it, the header is right and this page needs regenerating.

Clone this wiki locally