+ *
+ * **The "known key" engine** returns a public key which is already known
+ * from out-of-band information (e.g. the client _remembers_ the key from
+ * a previous connection, as in the usual SSH model). This is the simplest
+ * engine since it simply ignores the chain, thereby avoiding the need
+ * for any decoding logic.
+ *
+ * **The "minimal" engine** implements minimal X.509 decoding and chain
+ * validation:
+ *
+ * - The provided chain should validate "as is". There is no attempt
+ * at reordering, skipping or downloading extra certificates.
+ *
+ * - X.509 v1, v2 and v3 certificates are supported.
+ *
+ * - Trust anchors are a DN and a public key. Each anchor is either a
+ * "CA" anchor, or a non-CA.
+ *
+ * - If the end-entity certificate matches a non-CA anchor (subject DN
+ * is equal to the non-CA name, and public key is also identical to
+ * the anchor key), then this is a _direct trust_ case and the
+ * remaining certificates are ignored.
+ *
+ * - Unless direct trust is applied, the chain must be verifiable up to
+ * a certificate whose issuer DN matches the DN from a "CA" trust anchor,
+ * and whose signature is verifiable against that anchor's public key.
+ * Subsequent certificates in the chain are ignored.
+ *
+ * - The engine verifies subject/issuer DN matching, and enforces
+ * processing of Basic Constraints and Key Usage extensions. The
+ * Authority Key Identifier, Subject Key Identifier, Issuer Alt Name,
+ * Subject Directory Attribute, CRL Distribution Points, Freshest CRL,
+ * Authority Info Access and Subject Info Access extensions are
+ * ignored. The Subject Alt Name is decoded for the end-entity
+ * certificate under some conditions (see below). Other extensions
+ * are ignored if non-critical, or imply chain rejection if critical.
+ *
+ * - The Subject Alt Name extension is parsed for names of type `dNSName`
+ * when decoding the end-entity certificate, and only if there is a
+ * server name to match. If there is no SAN extension, then the
+ * Common Name from the subjectDN is used. That name matching is
+ * case-insensitive and honours a single starting wildcard (i.e. if
+ * the name in the certificate starts with "`*.`" then this matches
+ * any word as first element). Note: this name matching is performed
+ * also in the "direct trust" model.
+ *
+ * - DN matching is byte-to-byte equality (a future version might
+ * include some limited processing for case-insensitive matching and
+ * whitespace normalisation).
+ *
+ * - Successful validation produces a public key type but also a set
+ * of allowed usages (`BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`).
+ * The caller is responsible for checking that the key type and
+ * usages are compatible with the expected values (e.g. with the
+ * selected cipher suite, when the client validates the server's
+ * certificate).
+ *
+ * **Important caveats:**
+ *
+ * - The "minimal" engine does not check revocation status. The relevant
+ * extensions are ignored, and CRL or OCSP responses are not gathered
+ * or checked.
+ *
+ * - The "minimal" engine does not currently support Name Constraints
+ * (some basic functionality to handle sub-domains may be added in a
+ * later version).
+ *
+ * - The decoder is not "validating" in the sense that it won't reject
+ * some certificates with invalid field values when these fields are
+ * not actually processed.