Skip to content

CCertCollection

Jay edited this page Oct 3, 2026 · 2 revisions

CCertCollection

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

A set of certificates, optionally with their private keys, plus the lookups needed to order them into a chain.

This is the layer a PKCS#12/PFX container sits on. A PFX is, in substance, exactly this: a bag of certificates, zero or more private keys, the PKCS#9 attributes that pair them, and an ordering. Building that container needs all of this and no more, so it lives here rather than inside the container format, where it would be stuck behind password-based encryption and unavailable to anything else.

This does not validate a certification path, and the distinction is not a quibble. buildChain() orders certificates by who issued whom. A path validator additionally checks signatures, validity periods, basicConstraints (cA and pathLenConstraint), keyUsage, extendedKeyUsage, name constraints, policy constraints and revocation, and decides whether the root is one the caller trusts. None of that happens here. An ordered chain out of this class says "these certificates claim to form a chain", which is what a container format needs to store and what a validator needs as input -- it is not a statement that the chain is good. verifyLinks() goes one step further and checks the signatures, and is still not path validation; its own doc comment lists what it leaves out.

Lookups return an index into the collection, with NOT_FOUND for a miss, rather than a pointer or an iterator. An index stays meaningful across a copy of the collection and is what buildChain() reports a chain as, so the two compose; it is invalidated by removeAt() and clear(), like any index into a sequence.

Constants

  • static constexpr size_t NOT_FOUND = size_t(-1) --- Returned by every lookup that finds nothing.
  • static constexpr size_t MAX_DEPTH = 16 --- The longest chain buildChain() will assemble before giving up with ECHAINRES_TOO_DEEP. A bound is needed because a collection is caller-supplied data: without one, a sufficiently long chain -- or a cycle that the already-seen check somehow missed -- turns a lookup into an unbounded loop. Real hierarchies are a handful of links deep.

Methods

CCertCollection()

Constructs an empty collection.

~CCertCollection()

Destroys the collection, clearing any private key material it holds.

size_t count() const

Returns the number of entries.

Returns: The entry count.

bool empty() const

Reports whether the collection holds nothing.

Returns: True if there are no entries.

ERetCode at(size_t index, SCertEntry& out) const

Returns an entry by index.

  • index --- The entry index, below count().
  • out --- Receives the entry.

Returns: ERET_OK, or ERET_BADREQ if index is out of range.

void clear()

Removes every entry, clearing any private key material first.

ERetCode add(const CCert& cert, size_t& outIndex)

Adds a certificate with no private key.

  • cert --- The certificate; must not be empty.
  • outIndex --- Receives the index of the new entry.

Returns: ERET_OK, or ERET_BADREQ if cert is empty.

ERetCode add( const CCert& cert, const crypto::IPrivateKeyPtr& privateKey, size_t& outIndex )

Adds a certificate together with its private key.

The two are not checked against each other here -- see checkKeyPairing(), which is separate because the check costs a signature operation and a caller importing a container of many entries may not want to pay it for every one.

  • cert --- The certificate; must not be empty.
  • privateKey --- The matching private key; may be null, which is the same as add().
  • outIndex --- Receives the index of the new entry.

Returns: ERET_OK, or ERET_BADREQ if cert is empty.

ERetCode add(const SCertEntry& entry, size_t& outIndex)

Adds a fully-specified entry, PKCS#9 attributes included.

  • entry --- The entry to add; its cert must not be empty.
  • outIndex --- Receives the index of the new entry.

Returns: ERET_OK, or ERET_BADREQ if the entry's certificate is empty.

ERetCode removeAt(size_t index)

Removes one entry, clearing its private key material first.

Every index at or above index shifts down by one, as with any sequence.

  • index --- The entry to remove.

Returns: ERET_OK, or ERET_BADREQ if index is out of range.

ERetCode attachPrivateKey(size_t index, const crypto::IPrivateKeyPtr& privateKey)

Attaches a private key to an entry that does not have one.

  • index --- The entry.
  • privateKey --- The key to attach; must not be null.

Returns: ERET_OK, ERET_BADREQ if index is out of range or privateKey is null.

ERetCode setFriendlyName(size_t index, const CString& name)

Sets an entry's PKCS#9 friendlyName.

  • index --- The entry.
  • name --- The name; may be empty, which removes it.

Returns: ERET_OK, or ERET_BADREQ if index is out of range.

ERetCode setLocalKeyId(size_t index, const SReadOnlyByteSpan& id)

Sets an entry's PKCS#9 localKeyId.

  • index --- The entry.
  • id --- The identifier; may be empty, which removes it.

Returns: ERET_OK, or ERET_BADREQ if index is out of range.

size_t findBySubject(const CDistinguishedName& subject) const

Finds the first entry whose subject matches.

More than one certificate can share a subject -- a CA re-keying itself issues a new certificate with the same subject and a different key -- so this returns the first match and findAllBySubject() returns every one. Prefer findBySubjectKeyId() where the key identifier is known, since it distinguishes exactly the case this cannot.

  • subject --- The subject to match.

Returns: The entry index, or NOT_FOUND.

size_t findAllBySubject(const CDistinguishedName& subject, TArray<size_t>& out) const

Finds every entry whose subject matches.

  • subject --- The subject to match.
  • out --- Receives the matching indices; cleared first.

Returns: The number of matches.

size_t findByIssuerAndSerial( const CDistinguishedName& issuer, const SReadOnlyByteSpan& serial ) const

Finds the entry with a given issuer and serial number, which is the identifier X.509 itself treats as unique: a CA must not reuse a serial.

  • issuer --- The issuing CA's subject name, as it appears in the certificate's issuer field.
  • serial --- The serial number, as the bytes CCert::serialNumber() reports.

Returns: The entry index, or NOT_FOUND.

size_t findBySubjectKeyId(const SReadOnlyByteSpan& keyId) const

Finds the entry whose SubjectKeyIdentifier extension matches.

Entries with no such extension never match, rather than matching an empty identifier.

  • keyId --- The key identifier.

Returns: The entry index, or NOT_FOUND.

size_t findByFriendlyName(const CString& name) const

Finds the entry with a given PKCS#9 friendlyName.

  • name --- The name to match; an empty name never matches.

Returns: The entry index, or NOT_FOUND.

size_t findByLocalKeyId(const SReadOnlyByteSpan& id) const

Finds the entry with a given PKCS#9 localKeyId, which is how a PFX pairs a certificate with a key.

  • id --- The identifier to match; an empty identifier never matches.

Returns: The entry index, or NOT_FOUND.

static bool isSelfIssued(const CCert& cert)

Reports whether a certificate names itself as its own issuer.

This is a check on the names only -- it does not verify that the certificate's signature was made by its own key, which is what would make it genuinely self-signed. A certificate can be self-issued without being self-signed. buildChain() stops at a self-issued certificate because that is where the naming links run out; whether it is really self-signed is for verifyLinks() or a validator to establish.

  • cert --- The certificate.

Returns: True if the subject and issuer names are equal.

size_t findIssuerOf(const CCert& cert) const

Finds the entry that appears to have issued a certificate.

Matches the certificate's issuer name against candidate subjects, and where the certificate carries an AuthorityKeyIdentifier with a key identifier, prefers the candidate whose SubjectKeyIdentifier matches it. That preference is what makes the result well-defined when a CA has re-keyed and two of its certificates share a subject.

A self-issued certificate is not reported as its own issuer, so this returning NOT_FOUND for one is the normal end of a chain rather than a failure.

  • cert --- The certificate whose issuer to find.

Returns: The entry index, or NOT_FOUND.

size_t collectSelfIssued(TArray<size_t>& out) const

Collects every entry that is self-issued, i.e. every candidate root.

  • out --- Receives the indices; cleared first.

Returns: The number found.

EChainResults buildChain(size_t leafIndex, TArray<size_t>& out) const

Orders the collection into a chain starting from one of its entries.

Walks findIssuerOf() from the given entry upwards. out receives the indices in order, leaf first, including the starting entry; on anything other than ECHAINRES_OK it holds the partial chain assembled before the problem, which is more useful to a caller than an empty array.

This performs no verification whatsoever -- see this class's own doc comment.

  • leafIndex --- The entry to start from.
  • out --- Receives the chain as indices, leaf first; cleared first.

Returns: How the walk ended.

EChainResults buildChainFor(const CCert& leaf, TArray<size_t>& out) const

Orders the collection into a chain starting from a certificate that need not be in it.

Useful for the common case where the leaf arrived separately from the CA certificates that support it. The leaf itself is not included in out, since it has no index in this collection.

  • leaf --- The certificate to start from.
  • out --- Receives the chain above the leaf as indices, nearest issuer first; cleared first.

Returns: How the walk ended; never ECHAINRES_NOT_FOUND, since the leaf is supplied directly.

ERetCode verifyLinks(const TArray<size_t>& chain) const

Checks the signature on each link of an already-assembled chain.

Calls CCert::verifyBy() for every adjacent pair, and for a chain ending in a self-issued certificate also checks that one against itself.

This is still not path validation. It establishes only that each certificate was signed by the key in the one above it. It does not check validity periods, basicConstraints, keyUsage, extendedKeyUsage, name or policy constraints, or revocation, and it has no notion of which roots the caller trusts -- a chain of perfectly-signed certificates rooted in an attacker's own CA passes this.

  • chain --- The chain as indices, leaf first, as buildChain() produces.

Returns: ERET_OK if every link verifies; otherwise the first failure's code, or ERET_BADREQ if an index is out of range.

ERetCode checkKeyPairing(size_t index) const

Checks that an entry's private key really belongs to its certificate.

Signs a fixed value with the private key and verifies it against the certificate's public key, which is the only way to establish the pairing for a signature algorithm -- comparing serialized keys works for some algorithms and not others, and comparing nothing at all is how a container ends up holding a key that silently fails on first use. Separate from add() because it costs a signature operation.

  • index --- The entry; must hold a private key.

Returns: ERET_OK if the key matches, ERET_KEY_ERROR if it does not, ERET_KEY_EMPTY if the entry holds no private key, ERET_BADREQ if index is out of range, or ERET_NOTSUP if the key's algorithm cannot sign.

Example

Collects certificates and orders them into a chain. buildChain() orders by who issued whom and verifies nothing at all; verifyLinks() adds each link's signature and is still not path validation -- dates, basicConstraints, revocation and trust-anchor choice stay with the caller.

// given: const CCert& leaf, const CCert& intermediate, const CCert& root
CCertCollection col;
size_t leafIndex = 0, index = 0;
if (col.add(leaf, leafIndex) != ERET_OK
    || col.add(intermediate, index) != ERET_OK
    || col.add(root, index) != ERET_OK)
{
    return;
}

TArray<size_t> chain;
if (col.buildChain(leafIndex, chain) != ECHAINRES_OK) {
    return; // chain still holds the partial walk assembled before the problem
}

if (col.verifyLinks(chain) != ERET_OK) {
    return;
}
// every link's signature holds -- a chain rooted in an attacker's own CA gets this far too

Reference 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.

Clone this wiki locally