view release on metacpan or  search on metacpan

include/bearssl_x509.h  view on Meta::CPAN

	 * For X.500 name elements (to be extracted from the subject DN),
	 * this is the encoded OID for the requested name element; the
	 * first byte shall contain the length of the DER-encoded OID
	 * value, followed by the OID value (for instance, OID 2.5.4.3,
	 * for id-at-commonName, will be `03 55 04 03`). This is
	 * equivalent to full DER encoding with the length but without
	 * the tag.
	 *
	 * For SAN name elements, the first byte (`oid[0]`) has value 0,
	 * followed by another byte that matches the expected GeneralName
	 * tag. Allowed second byte values are then:
	 *
	 *   - 1: `rfc822Name`
	 *
	 *   - 2: `dNSName`
	 *
	 *   - 6: `uniformResourceIdentifier`
	 *
	 *   - 0: `otherName`
	 *
	 * If first and second byte are 0, then this is a SAN element of
	 * type `otherName`; the `oid[]` array should then contain, right
	 * after the two bytes of value 0, an encoded OID (with the same
	 * conventions as for X.500 name elements). If a match is found
	 * for that OID, then the corresponding name element will be
	 * extracted, as long as it is a supported string type.
	 */
	const unsigned char *oid;

	/**
	 * \brief Destination buffer.
	 */
	char *buf;

	/**
	 * \brief Length (in bytes) of the destination buffer.
	 *
	 * The buffer MUST NOT be smaller than 1 byte.
	 */
	size_t len;

	/**
	 * \brief Decoding status.
	 *
	 * Status is 0 if the name element was not found, 1 if it was
	 * found and decoded, or -1 on error. Error conditions include
	 * an unrecognised encoding, an invalid encoding, or a string
	 * too large for the destination buffer.
	 */
	int status;

} br_name_element;

/**
 * \brief Callback for validity date checks.
 *
 * The function receives as parameter an arbitrary user-provided context,
 * and the notBefore and notAfter dates specified in an X.509 certificate,
 * both expressed as a number of days and a number of seconds:
 *
 *   - Days are counted in a proleptic Gregorian calendar since
 *     January 1st, 0 AD. Year "0 AD" is the one that preceded "1 AD";
 *     it is also traditionally known as "1 BC".
 *
 *   - Seconds are counted since midnight, from 0 to 86400 (a count of
 *     86400 is possible only if a leap second happened).
 *
 * Each date and time is understood in the UTC time zone. The "Unix
 * Epoch" (January 1st, 1970, 00:00 UTC) corresponds to days=719528 and
 * seconds=0; the "Windows Epoch" (January 1st, 1601, 00:00 UTC) is
 * days=584754, seconds=0.
 *
 * This function must return -1 if the current date is strictly before
 * the "notBefore" time, or +1 if the current date is strictly after the
 * "notAfter" time. If neither condition holds, then the function returns
 * 0, which means that the current date falls within the validity range of
 * the certificate. If the function returns a value distinct from -1, 0
 * and +1, then this is interpreted as an unavailability of the current
 * time, which normally ends the validation process with a
 * `BR_ERR_X509_TIME_UNKNOWN` error.
 *
 * During path validation, this callback will be invoked for each
 * considered X.509 certificate. Validation fails if any of the calls
 * returns a non-zero value.
 *
 * The context value is an abritrary pointer set by the caller when
 * configuring this callback.
 *
 * \param tctx                 context pointer.
 * \param not_before_days      notBefore date (days since Jan 1st, 0 AD).
 * \param not_before_seconds   notBefore time (seconds, at most 86400).
 * \param not_after_days       notAfter date (days since Jan 1st, 0 AD).
 * \param not_after_seconds    notAfter time (seconds, at most 86400).
 * \return  -1, 0 or +1.
 */
typedef int (*br_x509_time_check)(void *tctx,
	uint32_t not_before_days, uint32_t not_before_seconds,
	uint32_t not_after_days, uint32_t not_after_seconds);

/**
 * \brief The "minimal" X.509 engine structure.
 *
 * The structure contents are opaque (they shall not be accessed directly),
 * except for the first field (the vtable).
 *
 * The "minimal" engine performs a rudimentary but serviceable X.509 path
 * validation.
 */
typedef struct {
	const br_x509_class *vtable;

#ifndef BR_DOXYGEN_IGNORE
	/* Structure for returning the EE public key. */
	br_x509_pkey pkey;

	/* CPU for the T0 virtual machine. */
	struct {
		uint32_t *dp;
		uint32_t *rp;
		const unsigned char *ip;
	} cpu;

include/bearssl_x509.h  view on Meta::CPAN

 * Once initialised (with `br_x509_minimal_init()`), the context must
 * be configured with the signature verification implementations that
 * it is supposed to support. If `irsa` is `0`, then the RSA support
 * is disabled.
 *
 * \param ctx    validation context.
 * \param irsa   RSA signature verification implementation (or `0`).
 */
static inline void
br_x509_minimal_set_rsa(br_x509_minimal_context *ctx,
	br_rsa_pkcs1_vrfy irsa)
{
	ctx->irsa = irsa;
}

/**
 * \brief Set a ECDSA signature verification implementation in the X.509
 * "minimal" engine.
 *
 * Once initialised (with `br_x509_minimal_init()`), the context must
 * be configured with the signature verification implementations that
 * it is supposed to support.
 *
 * If `iecdsa` is `0`, then this call disables ECDSA support; in that
 * case, `iec` may be `NULL`. Otherwise, `iecdsa` MUST point to a function
 * that verifies ECDSA signatures with format "asn1", and it will use
 * `iec` as underlying elliptic curve support.
 *
 * \param ctx      validation context.
 * \param iec      elliptic curve implementation (or `NULL`).
 * \param iecdsa   ECDSA implementation (or `0`).
 */
static inline void
br_x509_minimal_set_ecdsa(br_x509_minimal_context *ctx,
	const br_ec_impl *iec, br_ecdsa_vrfy iecdsa)
{
	ctx->iecdsa = iecdsa;
	ctx->iec = iec;
}

/**
 * \brief Initialise a "minimal" X.509 engine with default algorithms.
 *
 * This function performs the same job as `br_x509_minimal_init()`, but
 * also sets implementations for RSA, ECDSA, and the standard hash
 * functions.
 *
 * \param ctx                 context to initialise.
 * \param trust_anchors       trust anchors.
 * \param trust_anchors_num   number of trust anchors.
 */
void br_x509_minimal_init_full(br_x509_minimal_context *ctx,
	const br_x509_trust_anchor *trust_anchors, size_t trust_anchors_num);

/**
 * \brief Set the validation time for the X.509 "minimal" engine.
 *
 * The validation time is set as two 32-bit integers, for days and
 * seconds since a fixed epoch:
 *
 *   - Days are counted in a proleptic Gregorian calendar since
 *     January 1st, 0 AD. Year "0 AD" is the one that preceded "1 AD";
 *     it is also traditionally known as "1 BC".
 *
 *   - Seconds are counted since midnight, from 0 to 86400 (a count of
 *     86400 is possible only if a leap second happened).
 *
 * The validation date and time is understood in the UTC time zone. The
 * "Unix Epoch" (January 1st, 1970, 00:00 UTC) corresponds to days=719528
 * and seconds=0; the "Windows Epoch" (January 1st, 1601, 00:00 UTC) is
 * days=584754, seconds=0.
 *
 * If the validation date and time are not explicitly set, but BearSSL
 * was compiled with support for the system clock on the underlying
 * platform, then the current time will automatically be used. Otherwise,
 * not setting the validation date and time implies a validation
 * failure (except in case of direct trust of the EE key).
 *
 * \param ctx       validation context.
 * \param days      days since January 1st, 0 AD (Gregorian calendar).
 * \param seconds   seconds since midnight (0 to 86400).
 */
static inline void
br_x509_minimal_set_time(br_x509_minimal_context *ctx,
	uint32_t days, uint32_t seconds)
{
	ctx->days = days;
	ctx->seconds = seconds;
	ctx->itime = 0;
}

/**
 * \brief Set the validity range callback function for the X.509
 * "minimal" engine.
 *
 * The provided function will be invoked to check whether the validation
 * date is within the validity range for a given X.509 certificate; a
 * call will be issued for each considered certificate. The provided
 * context pointer (itime_ctx) will be passed as first parameter to the
 * callback.
 *
 * \param tctx   context for callback invocation.
 * \param cb     callback function.
 */
static inline void
br_x509_minimal_set_time_callback(br_x509_minimal_context *ctx,
	void *itime_ctx, br_x509_time_check itime)
{
	ctx->itime_ctx = itime_ctx;
	ctx->itime = itime;
}

/**
 * \brief Set the minimal acceptable length for RSA keys (X.509 "minimal"
 * engine).
 *
 * The RSA key length is expressed in bytes. The default minimum key
 * length is 128 bytes, corresponding to 1017 bits. RSA keys shorter
 * than the configured length will be rejected, implying validation
 * failure. This setting applies to keys extracted from certificates
 * (both end-entity, and intermediate CA) but not to "CA" trust anchors.
 *
 * \param ctx           validation context.
 * \param byte_length   minimum RSA key length, **in bytes** (not bits).
 */
static inline void
br_x509_minimal_set_minrsa(br_x509_minimal_context *ctx, int byte_length)
{
	ctx->min_rsa_size = (int16_t)(byte_length - 128);
}

/**
 * \brief Set the name elements to gather.
 *
 * The provided array is linked in the context. The elements are
 * gathered from the EE certificate. If the same element type is
 * requested several times, then the relevant structures will be filled
 * in the order the matching values are encountered in the certificate.
 *
 * \param ctx        validation context.