Repository navigation
IChainFormat
#include <certpp/x509/chain.hpp> --- certpp::x509
Reads and writes a CCertCollection as a container file.
One implementation per format under x509/chain/, the same arrangement x509/exts/ has
for extension types: the interface is here, the concrete formats are there, and
builtIn() is the only thing that needs to know which exist.
The two formats are not interchangeable, and the difference is not cosmetic:
-
PEM is concatenated base64 blocks with no password and no encryption. A private key
written to PEM by this interface is written in the clear. That is what PEM is, and
it is occasionally what a caller wants (a key they are about to hand to a tool that
expects it), but
needsPassword()returning false is not a convenience -- it is a warning. - PFX (PKCS#12, RFC 7292) encrypts its key bags and MACs the whole container under a password. It is the format to use when a private key is going to rest on disk or cross a network.
Both round-trip the certificates and the PKCS#9 attributes. Only PFX round-trips a private key without exposing it.
Destructor for the container-format interface.
Creates the built-in implementation of a format.
-
which--- The format.
Returns: The implementation, or null for ECHAINFMT_UNKNOWN or an unimplemented one.
Guesses a container's format from its first bytes.
PEM begins with the ASCII -----BEGIN; a PFX is DER and so begins with a SEQUENCE
tag. That is enough to tell them apart and is not a validity check -- a buffer
that merely starts like one is reported as that one, and the subsequent load() is
what decides whether it really is.
-
data--- The start of the container; a few bytes are enough.
Returns: The guessed format, or ECHAINFMT_UNKNOWN.
Returns which format this implementation handles.
Returns: The format.
Reports whether this format requires a password.
False means the format has no confidentiality at all, not that a password is optional -- see this interface's own doc comment.
Returns: True if load()/save() need a non-empty password.
virtual ERetCode load( const SReadOnlyByteSpan& data, const SReadOnlyByteSpan& password, CCertCollection& out ) const = 0
Reads a container into a collection.
Entries are appended, so loading two containers into one collection merges them. On failure the collection is left as it was rather than half-populated.
-
data--- The container's bytes. -
password--- The password; ignored by a format whereneedsPassword()is false. -
out--- Receives the entries, appended.
Returns: ERET_OK, ERET_BADREQ for a malformed container, ERET_KEY_ERROR for a wrong password or a failed integrity check, or ERET_NOTSUP for a container using an algorithm this library does not implement.
virtual ERetCode save( const CCertCollection& in, const SReadOnlyByteSpan& password, CBuffer& out ) const = 0
Writes a collection out as a container.
-
in--- The collection; must not be empty. -
password--- The password; ignored by a format whereneedsPassword()is false. -
out--- Receives the container's bytes, replacing any content it held.
Returns: ERET_OK, ERET_BADREQ if the collection is empty or the password is required and empty, or ERET_NOTSUP if an entry holds a key this format cannot carry.
Starts from builtIn() and writes a collection out. A PEM container has no password and no encryption at all, so a private key held in the collection is written in the clear -- check needsPassword() and choose ECHAINFMT_PFX when the key is going to rest on disk.
// given: const CCertCollection& col, const COctet& password
IChainFormatPtr format = IChainFormat::builtIn(ECHAINFMT_PEM);
if (!format) {
return;
}
if (!format->needsPassword()) {
// Nothing in this container will be encrypted, whatever password is passed.
} else if (password.empty()) {
return; // save() would refuse with ERET_BADREQ
}
CBuffer out;
if (format->save(col, password.toSpan(), out) != ERET_OK) {
return; // ERET_NOTSUP when an entry holds a key this format cannot carry
}
// out holds the container's bytes; format->format() reports which format they areReference generated from certpp/x509/chain.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.