Repository navigation
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.
Constructs the PEM format.
-
withPrivateKeys--- True to havesave()write each entry's private key, in the clear, alongside its certificate. False -- the default, and whatIChainFormat::builtIn()returns -- writes certificates only.
Destroys the format object. It holds no key material of its own.
Returns which format this implementation handles.
Returns: Always ECHAINFMT_PEM.
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.
Reports whether save() writes private keys.
Returns: True if this format object was constructed to write private keys in the clear.
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.
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.
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.