Repository navigation
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.
-
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 chainbuildChain()will assemble before giving up withECHAINRES_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.
Constructs an empty collection.
Destroys the collection, clearing any private key material it holds.
Returns the number of entries.
Returns: The entry count.
Reports whether the collection holds nothing.
Returns: True if there are no entries.
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.
Removes every entry, clearing any private key material first.
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.
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.
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.
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.
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.
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.
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.
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.
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 bytesCCert::serialNumber()reports.
Returns: The entry index, or NOT_FOUND.
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.
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.
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.
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.
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.
Collects every entry that is self-issued, i.e. every candidate root.
-
out--- Receives the indices; cleared first.
Returns: The number found.
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.
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.
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, asbuildChain()produces.
Returns: ERET_OK if every link verifies; otherwise the first failure's code, or ERET_BADREQ if an index is out of range.
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.
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 tooReference 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.