41  * # X.509 Certificate Chain Processing
43  * An X.509 processing engine receives an X.509 chain, chunk by chunk,
47  * is thus injected in the engine in SSL order (end-entity first).
49  * The engine's job is to return the public key to use for SSL/TLS.
51  * engine.
53  * **The "known key" engine** returns a public key which is already known
54  * from out-of-band information (e.g. the client _remembers_ the key from
56  * engine since it simply ignores the chain, thereby avoiding the need
59  * **The "minimal" engine** implements minimal X.509 decoding and chain
62  *   - The provided chain should validate "as is". There is no attempt
65  *   - X.509 v1, v2 and v3 certificates are supported.
67  *   - Trust anchors are a DN and a public key. Each anchor is either a
68  *     "CA" anchor, or a non-CA.
70  *   - If the end-entity certificate matches a non-CA anchor (subject DN
71  *     is equal to the non-CA name, and public key is also identical to
75  *   - Unless direct trust is applied, the chain must be verifiable up to
80  *   - The engine verifies subject/issuer DN matching, and enforces
81  *     processing of Basic Constraints and Key Usage extensions. The
85  *     ignored. The Subject Alt Name is decoded for the end-entity
87  *     are ignored if non-critical, or imply chain rejection if critical.
89  *   - The Subject Alt Name extension is parsed for names of type `dNSName`
90  *     when decoding the end-entity certificate, and only if there is a
93  *     case-insensitive and honours a single starting wildcard (i.e. if
98  *   - DN matching is byte-to-byte equality (a future version might
99  *     include some limited processing for case-insensitive matching and
102  *   - Successful validation produces a public key type but also a set
111  *   - The "minimal" engine does not check revocation status. The relevant
115  *   - The "minimal" engine does not currently support Name Constraints
116  *     (some basic functionality to handle sub-domains may be added in a
119  *   - The decoder is not "validating" in the sense that it won't reject
176 /** \brief X.509 status: decoding error: value is off-limits. */
243  * The DN is DER-encoded.
268  * A "non-CA" anchor is accepted only for direct trust (server's
293  * validation engine that it should find a public key of that type,
304  * validation engine that it should find a public key of that type,
311  *               is not NULL and non-empty, then it is a name that
326  *               0 on success, or a non-zero error code.
337  * long as a new chain is not started. This may be a sub-structure
338  * within the context for the engine. This function MAY return a valid
340  * depending on the validation engine.
344  * \brief Class type for an X.509 engine.
346  * A certificate chain validation uses a caller-allocated context, which
350  *   - `start_chain()` is called at the start of the validation.
351  *   - Certificates are processed one by one, in SSL order (end-entity
355  *       - `start_cert()` at the beginning of the certificate.
356  *       - `append()` is called zero, one or more times, to provide
358  *       - `end_cert()` at the end of the certificate.
360  *   - `end_chain()` is called when the last certificate in the chain
362  *   - `get_pkey()` is called after chain processing, if the chain
383 	 * elements of the end-entity certificate's SAN extension (if there
435 	 * non-zero error code. The `BR_ERR_X509_*` constants are
439 	 * \return  0 on success, or a non-zero error code.
444 	 * \brief Get the resulting end-entity public key.
464 	 * \return  the end-entity public key, or `NULL`.
471  * \brief The "known key" X.509 engine structure.
476  * The "known key" engine returns an externally configured public key,
489  * \brief Class instance for the "known key" X.509 engine.
494  * \brief Initialize a "known key" X.509 engine with a known RSA public key.
510  * \brief Initialize a "known key" X.509 engine with a known EC public key.
527  * The minimal X.509 engine has some state buffers which must be large
529  * -- the public key extracted from the current certificate;
530  * -- the signature on the current certificate or on the previous
532  * -- the public key extracted from the EE certificate.
534  * We store public key elements in their raw unsigned big-endian
535  * encoding. We want to support up to RSA-4096 with a short (up to 64
537  * length at least 520 bytes. Similarly, a RSA-4096 signature has length
546  * cost of public key operations. The X.509 "minimal" engine will tolerate
551  * NIST P-521 (the largest curve we care to support), a public key is
564  * as zero-terminated strings into the buffer.
567  * ensures that the resulting string is zero-terminated. If the string
577 	 * first byte shall contain the length of the DER-encoded OID
579 	 * for id-at-commonName, will be `03 55 04 03`). This is
587 	 *   - 1: `rfc822Name`
589 	 *   - 2: `dNSName`
591 	 *   - 6: `uniformResourceIdentifier`
593 	 *   - 0: `otherName`
620 	 * found and decoded, or -1 on error. Error conditions include
631  * The function receives as parameter an arbitrary user-provided context,
635  *   - Days are counted in a proleptic Gregorian calendar since
639  *   - Seconds are counted since midnight, from 0 to 86400 (a count of
647  * This function must return -1 if the current date is strictly before
651  * the certificate. If the function returns a value distinct from -1, 0
658  * returns a non-zero value.
668  * \return  -1, 0 or +1.
675  * \brief The "minimal" X.509 engine structure.
680  * The "minimal" engine performs a rudimentary but serviceable X.509 path
714 	   It is incremented at the end of the processing of a certificate,
750 	 * Multi-hasher for the TBS.
789  * \brief Class instance for the "minimal" X.509 engine.
794  * \brief Initialise a "minimal" X.509 engine.
798  * hash function may be used, but a collision-resistant hash function is
814  * \brief Set a supported hash function in an X.509 "minimal" engine.
820  * hash function identifiers (1 to 6, for MD5, SHA-1, SHA-224, SHA-256,
821  * SHA-384 and SHA-512).
834 	br_multihash_setimpl(&ctx->mhash, id, impl);  in br_x509_minimal_set_hash()
839  * "minimal" engine.
853 	ctx->irsa = irsa;  in br_x509_minimal_set_rsa()
858  * "minimal" engine.
877 	ctx->iecdsa = iecdsa;  in br_x509_minimal_set_ecdsa()
878 	ctx->iec = iec;  in br_x509_minimal_set_ecdsa()
882  * \brief Initialise a "minimal" X.509 engine with default algorithms.
896  * \brief Set the validation time for the X.509 "minimal" engine.
898  * The validation time is set as two 32-bit integers, for days and
901  *   - Days are counted in a proleptic Gregorian calendar since
905  *   - Seconds are counted since midnight, from 0 to 86400 (a count of
927 	ctx->days = days;  in br_x509_minimal_set_time()
928 	ctx->seconds = seconds;  in br_x509_minimal_set_time()
929 	ctx->itime = 0;  in br_x509_minimal_set_time()
934  * "minimal" engine.
949 	ctx->itime_ctx = itime_ctx;  in br_x509_minimal_set_time_callback()
950 	ctx->itime = itime;  in br_x509_minimal_set_time_callback()
955  * engine).
961  * (both end-entity, and intermediate CA) but not to "CA" trust anchors.
969 	ctx->min_rsa_size = (int16_t)(byte_length - 128);  in br_x509_minimal_set_minrsa()
988 	ctx->name_elts = elts;  in br_x509_minimal_set_name_elements()
989 	ctx->num_name_elts = num_elts;  in br_x509_minimal_set_name_elements()
997  * to use (self-signed) certificates as trust anchors.
1031 	/* DN processing: the subject DN is extracted and pushed to the
1052  * \brief Initialise an X.509 decoder context for processing a new
1071  * If `len` is non-zero, then that many bytes are pushed, from address
1096 	if (ctx->decoded && ctx->err == 0) {  in br_x509_decoder_get_pkey()
1097 		return &ctx->pkey;  in br_x509_decoder_get_pkey()
1111  * \return  0 on successful decoding, or a non-zero error code.
1116 	if (ctx->err != 0) {  in br_x509_decoder_last_error()
1117 		return ctx->err;  in br_x509_decoder_last_error()
1119 	if (!ctx->decoded) {  in br_x509_decoder_last_error()
1138 	return ctx->isCA;  in br_x509_decoder_isCA()
1154 	return ctx->signer_key_type;  in br_x509_decoder_get_signer_key_type()
1169 	return ctx->signer_hash_id;  in br_x509_decoder_get_signer_hash_id()
1173  * \brief Type for an X.509 certificate (DER-encoded).
1176 	/** \brief The DER-encoded certificate data. */
1178 	/** \brief The DER-encoded certificate length (in bytes). */
1186  * their raw, DER-encoded format, or wrapped in an unencrypted PKCS#8
1187  * archive (again DER-encoded).
1220 	   to accommodate all elements for a RSA-4096 private key (roughly
1221 	   five 2048-bit integers, possibly a bit more). */
1236  * If `len` is non-zero, then that many data bytes, starting at address
1249  * Decoding status is 0 on success, or a non-zero error code. If the
1254  * \return  0 on successful decoding, or a non-zero error code.
1259 	if (ctx->err != 0) {  in br_skey_decoder_last_error()
1260 		return ctx->err;  in br_skey_decoder_last_error()
1262 	if (ctx->key_type == 0) {  in br_skey_decoder_last_error()
1280 	if (ctx->err == 0) {  in br_skey_decoder_key_type()
1281 		return ctx->key_type;  in br_skey_decoder_key_type()
1301 	if (ctx->err == 0 && ctx->key_type == BR_KEYTYPE_RSA) {  in br_skey_decoder_get_rsa()
1302 		return &ctx->key.rsa;  in br_skey_decoder_get_rsa()
1322 	if (ctx->err == 0 && ctx->key_type == BR_KEYTYPE_EC) {  in br_skey_decoder_get_ec()
1323 		return &ctx->key.ec;  in br_skey_decoder_get_ec()
1338  *  - `sk`: the private key (`p`, `q`, `dp`, `dq` and `iq`)
1340  *  - `pk`: the public key (`n` and `e`)
1342  *  - `d` (size: `dlen` bytes): the private exponent
1372  *  - `sk`: the private key (`p`, `q`, `dp`, `dq` and `iq`)
1374  *  - `pk`: the public key (`n` and `e`)
1376  *  - `d` (size: `dlen` bytes): the private exponent