#include "bearssl_rand.h"
#include "bearssl_x509.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+
/** \file bearssl_ssl.h
*
* # SSL
signature algorithm, hash function). */
#define BR_ERR_INVALID_ALGORITHM 26
-/** \brief SSL status: invalid signature on ServerKeyExchange message. */
+/** \brief SSL status: invalid signature (on ServerKeyExchange from
+ server, or in CertificateVerify from client). */
#define BR_ERR_BAD_SIGNATURE 27
+/** \brief SSL status: peer's public key does not have the proper type
+ or is not allowed for requested operation. */
+#define BR_ERR_WRONG_KEY_USAGE 28
+
+/** \brief SSL status: client did not send a certificate upon request,
+ or the client certificate could not be validated. */
+#define BR_ERR_NO_CLIENT_AUTH 29
+
/** \brief SSL status: I/O error or premature close on underlying
transport stream. This error code is set only by the simplified
I/O API ("br_sslio_*"). */
* This class type extends the decryption engine class with an
* initialisation method that receives the parameters needed
* for GCM processing: block cipher implementation, block cipher key,
- * GHASH implementtion, and 4-byte IV.
+ * GHASH implementation, and 4-byte IV.
*/
typedef struct br_sslrec_in_gcm_class_ br_sslrec_in_gcm_class;
struct br_sslrec_in_gcm_class_ {
};
/**
- * \brief Record decryption engine class, for GCM mode.
+ * \brief Record encryption engine class, for GCM mode.
*
- * This class type extends the decryption engine class with an
+ * This class type extends the encryption engine class with an
* initialisation method that receives the parameters needed
* for GCM processing: block cipher implementation, block cipher key,
- * GHASH implementtion, and 4-byte IV.
+ * GHASH implementation, and 4-byte IV.
*/
typedef struct br_sslrec_out_gcm_class_ br_sslrec_out_gcm_class;
struct br_sslrec_out_gcm_class_ {
/* ===================================================================== */
+/**
+ * \brief Record decryption engine class, for ChaCha20+Poly1305.
+ *
+ * This class type extends the decryption engine class with an
+ * initialisation method that receives the parameters needed
+ * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
+ * Poly1305 implementation, key, and 12-byte IV.
+ */
+typedef struct br_sslrec_in_chapol_class_ br_sslrec_in_chapol_class;
+struct br_sslrec_in_chapol_class_ {
+ /**
+ * \brief Superclass, as first vtable field.
+ */
+ br_sslrec_in_class inner;
+
+ /**
+ * \brief Engine initialisation method.
+ *
+ * This method sets the vtable field in the context.
+ *
+ * \param ctx context to initialise.
+ * \param ichacha ChaCha20 implementation.
+ * \param ipoly Poly1305 implementation.
+ * \param key secret key (32 bytes).
+ * \param iv static IV (12 bytes).
+ */
+ void (*init)(const br_sslrec_in_chapol_class **ctx,
+ br_chacha20_run ichacha,
+ br_poly1305_run ipoly,
+ const void *key, const void *iv);
+};
+
+/**
+ * \brief Record encryption engine class, for ChaCha20+Poly1305.
+ *
+ * This class type extends the encryption engine class with an
+ * initialisation method that receives the parameters needed
+ * for ChaCha20+Poly1305 processing: ChaCha20 implementation,
+ * Poly1305 implementation, key, and 12-byte IV.
+ */
+typedef struct br_sslrec_out_chapol_class_ br_sslrec_out_chapol_class;
+struct br_sslrec_out_chapol_class_ {
+ /**
+ * \brief Superclass, as first vtable field.
+ */
+ br_sslrec_out_class inner;
+
+ /**
+ * \brief Engine initialisation method.
+ *
+ * This method sets the vtable field in the context.
+ *
+ * \param ctx context to initialise.
+ * \param ichacha ChaCha20 implementation.
+ * \param ipoly Poly1305 implementation.
+ * \param key secret key (32 bytes).
+ * \param iv static IV (12 bytes).
+ */
+ void (*init)(const br_sslrec_out_chapol_class **ctx,
+ br_chacha20_run ichacha,
+ br_poly1305_run ipoly,
+ const void *key, const void *iv);
+};
+
+/**
+ * \brief Context structure for processing records with ChaCha20+Poly1305.
+ *
+ * The same context structure is used for encrypting and decrypting.
+ *
+ * The first field points to the vtable. The other fields are opaque
+ * and shall not be accessed directly.
+ */
+typedef struct {
+ /** \brief Pointer to vtable. */
+ union {
+ const void *gen;
+ const br_sslrec_in_chapol_class *in;
+ const br_sslrec_out_chapol_class *out;
+ } vtable;
+#ifndef BR_DOXYGEN_IGNORE
+ uint64_t seq;
+ unsigned char key[32];
+ unsigned char iv[12];
+ br_chacha20_run ichacha;
+ br_poly1305_run ipoly;
+#endif
+} br_sslrec_chapol_context;
+
+/**
+ * \brief Static, constant vtable for record decryption with ChaCha20+Poly1305.
+ */
+extern const br_sslrec_in_chapol_class br_sslrec_in_chapol_vtable;
+
+/**
+ * \brief Static, constant vtable for record encryption with ChaCha20+Poly1305.
+ */
+extern const br_sslrec_out_chapol_class br_sslrec_out_chapol_vtable;
+
+/* ===================================================================== */
+
+/**
+ * \brief Record decryption engine class, for CCM mode.
+ *
+ * This class type extends the decryption engine class with an
+ * initialisation method that receives the parameters needed
+ * for CCM processing: block cipher implementation, block cipher key,
+ * and 4-byte IV.
+ */
+typedef struct br_sslrec_in_ccm_class_ br_sslrec_in_ccm_class;
+struct br_sslrec_in_ccm_class_ {
+ /**
+ * \brief Superclass, as first vtable field.
+ */
+ br_sslrec_in_class inner;
+
+ /**
+ * \brief Engine initialisation method.
+ *
+ * This method sets the vtable field in the context.
+ *
+ * \param ctx context to initialise.
+ * \param bc_impl block cipher implementation (CTR+CBC).
+ * \param key block cipher key.
+ * \param key_len block cipher key length (in bytes).
+ * \param iv static IV (4 bytes).
+ * \param tag_len tag length (in bytes)
+ */
+ void (*init)(const br_sslrec_in_ccm_class **ctx,
+ const br_block_ctrcbc_class *bc_impl,
+ const void *key, size_t key_len,
+ const void *iv, size_t tag_len);
+};
+
+/**
+ * \brief Record encryption engine class, for CCM mode.
+ *
+ * This class type extends the encryption engine class with an
+ * initialisation method that receives the parameters needed
+ * for CCM processing: block cipher implementation, block cipher key,
+ * and 4-byte IV.
+ */
+typedef struct br_sslrec_out_ccm_class_ br_sslrec_out_ccm_class;
+struct br_sslrec_out_ccm_class_ {
+ /**
+ * \brief Superclass, as first vtable field.
+ */
+ br_sslrec_out_class inner;
+
+ /**
+ * \brief Engine initialisation method.
+ *
+ * This method sets the vtable field in the context.
+ *
+ * \param ctx context to initialise.
+ * \param bc_impl block cipher implementation (CTR+CBC).
+ * \param key block cipher key.
+ * \param key_len block cipher key length (in bytes).
+ * \param iv static IV (4 bytes).
+ * \param tag_len tag length (in bytes)
+ */
+ void (*init)(const br_sslrec_out_ccm_class **ctx,
+ const br_block_ctrcbc_class *bc_impl,
+ const void *key, size_t key_len,
+ const void *iv, size_t tag_len);
+};
+
+/**
+ * \brief Context structure for processing records with CCM.
+ *
+ * The same context structure is used for encrypting and decrypting.
+ *
+ * The first field points to the vtable. The other fields are opaque
+ * and shall not be accessed directly.
+ */
+typedef struct {
+ /** \brief Pointer to vtable. */
+ union {
+ const void *gen;
+ const br_sslrec_in_ccm_class *in;
+ const br_sslrec_out_ccm_class *out;
+ } vtable;
+#ifndef BR_DOXYGEN_IGNORE
+ uint64_t seq;
+ union {
+ const br_block_ctrcbc_class *vtable;
+ br_aes_gen_ctrcbc_keys aes;
+ } bc;
+ unsigned char iv[4];
+ size_t tag_len;
+#endif
+} br_sslrec_ccm_context;
+
+/**
+ * \brief Static, constant vtable for record decryption with CCM.
+ */
+extern const br_sslrec_in_ccm_class br_sslrec_in_ccm_vtable;
+
+/**
+ * \brief Static, constant vtable for record encryption with CCM.
+ */
+extern const br_sslrec_out_ccm_class br_sslrec_out_ccm_vtable;
+
+/* ===================================================================== */
+
/**
* \brief Type for session parameters, to be saved for session resumption.
*/
#ifndef BR_DOXYGEN_IGNORE
/*
- * Maximum numnber of cipher suites supported by a client or server.
+ * Maximum number of cipher suites supported by a client or server.
*/
-#define BR_MAX_CIPHER_SUITES 40
+#define BR_MAX_CIPHER_SUITES 48
#endif
/**
const br_sslrec_in_class *vtable;
br_sslrec_in_cbc_context cbc;
br_sslrec_gcm_context gcm;
+ br_sslrec_chapol_context chapol;
+ br_sslrec_ccm_context ccm;
} in;
union {
const br_sslrec_out_class *vtable;
br_sslrec_out_clear_context clear;
br_sslrec_out_cbc_context cbc;
br_sslrec_gcm_context gcm;
+ br_sslrec_chapol_context chapol;
+ br_sslrec_ccm_context ccm;
} out;
/*
- * The "application data" flag. It is set when application data
- * can be exchanged, cleared otherwise.
+ * The "application data" flag. Value:
+ * 0 handshake is in process, no application data acceptable
+ * 1 application data can be sent and received
+ * 2 closing, no application data can be sent, but some
+ * can still be received (and discarded)
*/
unsigned char application_data;
/*
* Context RNG.
+ *
+ * rng_init_done is initially 0. It is set to 1 when the
+ * basic structure of the RNG is set, and 2 when some
+ * entropy has been pushed in. The value 2 marks the RNG
+ * as "properly seeded".
+ *
+ * rng_os_rand_done is initially 0. It is set to 1 when
+ * some seeding from the OS or hardware has been attempted.
*/
br_hmac_drbg_context rng;
int rng_init_done;
/*
* Secure renegotiation (RFC 5746): 'reneg' can be:
* 0 first handshake (server support is not known)
- * 1 server does not support secure renegotiation
- * 2 server supports secure renegotiation
+ * 1 peer does not support secure renegotiation
+ * 2 peer supports secure renegotiation
*
* The saved_finished buffer contains the client and the
* server "Finished" values from the last handshake, in
uint32_t flags;
/*
- * Context variables for the handshake processor.
- * The 'pad' must be large enough to accommodate an
- * RSA-encrypted pre-master secret, or a RSA signature on
- * key exchange parameters; since we want to support up to
- * RSA-4096, this means at least 512 bytes.
- * (Other pad usages require its length to be at least 256.)
+ * Context variables for the handshake processor. The 'pad' must
+ * be large enough to accommodate an RSA-encrypted pre-master
+ * secret, or an RSA signature; since we want to support up to
+ * RSA-4096, this means at least 512 bytes. (Other pad usages
+ * require its length to be at least 256.)
*/
struct {
uint32_t *dp;
*/
const br_x509_class **x509ctx;
+ /*
+ * Certificate chain to send. This is used by both client and
+ * server, when they send their respective Certificate messages.
+ * If chain_len is 0, then chain may be NULL.
+ */
+ const br_x509_certificate *chain;
+ size_t chain_len;
+ const unsigned char *cert_cur;
+ size_t cert_len;
+
+ /*
+ * List of supported protocol names (ALPN extension). If unset,
+ * (number of names is 0), then:
+ * - the client sends no ALPN extension;
+ * - the server ignores any incoming ALPN extension.
+ *
+ * Otherwise:
+ * - the client sends an ALPN extension with all the names;
+ * - the server selects the first protocol in its list that
+ * the client also supports, or fails (fatal alert 120)
+ * if the client sends an ALPN extension and there is no
+ * match.
+ *
+ * The 'selected_protocol' field contains 1+n if the matching
+ * name has index n in the list (the value is 0 if no match was
+ * performed, e.g. the peer did not send an ALPN extension).
+ */
+ const char **protocol_names;
+ uint16_t protocol_names_num;
+ uint16_t selected_protocol;
+
/*
* Pointers to implementations; left to NULL for unsupported
* functions. For the raw hash functions, implementations are
const br_block_cbcenc_class *iaes_cbcenc;
const br_block_cbcdec_class *iaes_cbcdec;
const br_block_ctr_class *iaes_ctr;
+ const br_block_ctrcbc_class *iaes_ctrcbc;
const br_block_cbcenc_class *ides_cbcenc;
const br_block_cbcdec_class *ides_cbcdec;
br_ghash ighash;
+ br_chacha20_run ichacha;
+ br_poly1305_run ipoly;
const br_sslrec_in_cbc_class *icbc_in;
const br_sslrec_out_cbc_class *icbc_out;
const br_sslrec_in_gcm_class *igcm_in;
const br_sslrec_out_gcm_class *igcm_out;
+ const br_sslrec_in_chapol_class *ichapol_in;
+ const br_sslrec_out_chapol_class *ichapol_out;
+ const br_sslrec_in_ccm_class *iccm_in;
+ const br_sslrec_out_ccm_class *iccm_out;
const br_ec_impl *iec;
+ br_rsa_pkcs1_vrfy irsavrfy;
+ br_ecdsa_vrfy iecdsa;
#endif
} br_ssl_engine_context;
*/
#define BR_OPT_ENFORCE_SERVER_PREFERENCES ((uint32_t)1 << 0)
-/*
+/**
* \brief Behavioural flag: disable renegotiation.
*
* If this flag is set, then renegotiations are rejected unconditionally:
*/
#define BR_OPT_NO_RENEGOTIATION ((uint32_t)1 << 1)
+/**
+ * \brief Behavioural flag: tolerate lack of client authentication.
+ *
+ * If this flag is set in a server and the server requests a client
+ * certificate, but the authentication fails (the client does not send
+ * a certificate, or the client's certificate chain cannot be validated),
+ * then the connection keeps on. Without this flag, a failed client
+ * authentication terminates the connection.
+ *
+ * Notes:
+ *
+ * - If the client's certificate can be validated and its public key is
+ * supported, then a wrong signature value terminates the connection
+ * regardless of that flag.
+ *
+ * - If using full-static ECDH, then a failure to validate the client's
+ * certificate prevents the handshake from succeeding.
+ */
+#define BR_OPT_TOLERATE_NO_CLIENT_AUTH ((uint32_t)1 << 2)
+
+/**
+ * \brief Behavioural flag: fail on application protocol mismatch.
+ *
+ * The ALPN extension ([RFC 7301](https://tools.ietf.org/html/rfc7301))
+ * allows the client to send a list of application protocol names, and
+ * the server to select one. A mismatch is one of the following occurrences:
+ *
+ * - On the client: the client sends a list of names, the server
+ * responds with a protocol name which is _not_ part of the list of
+ * names sent by the client.
+ *
+ * - On the server: the client sends a list of names, and the server
+ * is also configured with a list of names, but there is no common
+ * protocol name between the two lists.
+ *
+ * Normal behaviour in case of mismatch is to report no matching name
+ * (`br_ssl_engine_get_selected_protocol()` returns `NULL`) and carry on.
+ * If the flag is set, then a mismatch implies a protocol failure (if
+ * the mismatch is detected by the server, it will send a fatal alert).
+ *
+ * Note: even with this flag, `br_ssl_engine_get_selected_protocol()`
+ * may still return `NULL` if the client or the server does not send an
+ * ALPN extension at all.
+ */
+#define BR_OPT_FAIL_ON_ALPN_MISMATCH ((uint32_t)1 << 3)
+
/**
* \brief Set the minimum and maximum supported protocol versions.
*
cc->x509ctx = x509ctx;
}
+/**
+ * \brief Set the supported protocol names.
+ *
+ * Protocol names are part of the ALPN extension ([RFC
+ * 7301](https://tools.ietf.org/html/rfc7301)). Each protocol name is a
+ * character string, containing no more than 255 characters (256 with the
+ * terminating zero). When names are set, then:
+ *
+ * - The client will send an ALPN extension, containing the names. If
+ * the server responds with an ALPN extension, the client will verify
+ * that the response contains one of its name, and report that name
+ * through `br_ssl_engine_get_selected_protocol()`.
+ *
+ * - The server will parse incoming ALPN extension (from clients), and
+ * try to find a common protocol; if none is found, the connection
+ * is aborted with a fatal alert. On match, a response ALPN extension
+ * is sent, and name is reported through
+ * `br_ssl_engine_get_selected_protocol()`.
+ *
+ * The provided array is linked in, and must remain valid while the
+ * connection is live.
+ *
+ * Names MUST NOT be empty. Names MUST NOT be longer than 255 characters
+ * (excluding the terminating 0).
+ *
+ * \param ctx SSL engine context.
+ * \param names list of protocol names (zero-terminated).
+ * \param num number of protocol names (MUST be 1 or more).
+ */
+static inline void
+br_ssl_engine_set_protocol_names(br_ssl_engine_context *ctx,
+ const char **names, size_t num)
+{
+ ctx->protocol_names = names;
+ ctx->protocol_names_num = num;
+}
+
+/**
+ * \brief Get the selected protocol.
+ *
+ * If this context was initialised with a non-empty list of protocol
+ * names, and both client and server sent ALPN extensions during the
+ * handshake, and a common name was found, then that name is returned.
+ * Otherwise, `NULL` is returned.
+ *
+ * The returned pointer is one of the pointers provided to the context
+ * with `br_ssl_engine_set_protocol_names()`.
+ *
+ * \return the selected protocol, or `NULL`.
+ */
+static inline const char *
+br_ssl_engine_get_selected_protocol(br_ssl_engine_context *ctx)
+{
+ unsigned k;
+
+ k = ctx->selected_protocol;
+ return (k == 0 || k == 0xFFFF) ? NULL : ctx->protocol_names[k - 1];
+}
+
/**
* \brief Set a hash function implementation (by ID).
*
/**
* \brief Set the PRF implementation (for TLS 1.0 and 1.1).
*
- * This function sets (or removes, if `impl` is `NULL`) the implemenation
+ * This function sets (or removes, if `impl` is `NULL`) the implementation
* for the PRF used in TLS 1.0 and 1.1.
*
* \param cc SSL engine context.
/**
* \brief Set the PRF implementation with SHA-256 (for TLS 1.2).
*
- * This function sets (or removes, if `impl` is `NULL`) the implemenation
+ * This function sets (or removes, if `impl` is `NULL`) the implementation
* for the SHA-256 variant of the PRF used in TLS 1.2.
*
* \param cc SSL engine context.
/**
* \brief Set the PRF implementation with SHA-384 (for TLS 1.2).
*
- * This function sets (or removes, if `impl` is `NULL`) the implemenation
+ * This function sets (or removes, if `impl` is `NULL`) the implementation
* for the SHA-384 variant of the PRF used in TLS 1.2.
*
* \param cc SSL engine context.
cc->iaes_cbcdec = impl_dec;
}
+/**
+ * \brief Set the "default" AES/CBC implementations.
+ *
+ * This function configures in the engine the AES implementations that
+ * should provide best runtime performance on the local system, while
+ * still being safe (in particular, constant-time). It also sets the
+ * handlers for CBC records.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_aes_cbc(br_ssl_engine_context *cc);
+
/**
* \brief Set the AES/CTR implementation.
*
cc->iaes_ctr = impl;
}
+/**
+ * \brief Set the "default" implementations for AES/GCM (AES/CTR + GHASH).
+ *
+ * This function configures in the engine the AES/CTR and GHASH
+ * implementation that should provide best runtime performance on the local
+ * system, while still being safe (in particular, constant-time). It also
+ * sets the handlers for GCM records.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_aes_gcm(br_ssl_engine_context *cc);
+
/**
* \brief Set the DES/CBC implementations.
*
cc->ides_cbcdec = impl_dec;
}
+/**
+ * \brief Set the "default" DES/CBC implementations.
+ *
+ * This function configures in the engine the DES implementations that
+ * should provide best runtime performance on the local system, while
+ * still being safe (in particular, constant-time). It also sets the
+ * handlers for CBC records.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_des_cbc(br_ssl_engine_context *cc);
+
/**
* \brief Set the GHASH implementation (used in GCM mode).
*
cc->ighash = impl;
}
+/**
+ * \brief Set the ChaCha20 implementation.
+ *
+ * \param cc SSL engine context.
+ * \param ichacha ChaCha20 implementation (or `NULL`).
+ */
+static inline void
+br_ssl_engine_set_chacha20(br_ssl_engine_context *cc,
+ br_chacha20_run ichacha)
+{
+ cc->ichacha = ichacha;
+}
+
+/**
+ * \brief Set the Poly1305 implementation.
+ *
+ * \param cc SSL engine context.
+ * \param ipoly Poly1305 implementation (or `NULL`).
+ */
+static inline void
+br_ssl_engine_set_poly1305(br_ssl_engine_context *cc,
+ br_poly1305_run ipoly)
+{
+ cc->ipoly = ipoly;
+}
+
+/**
+ * \brief Set the "default" ChaCha20 and Poly1305 implementations.
+ *
+ * This function configures in the engine the ChaCha20 and Poly1305
+ * implementations that should provide best runtime performance on the
+ * local system, while still being safe (in particular, constant-time).
+ * It also sets the handlers for ChaCha20+Poly1305 records.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_chapol(br_ssl_engine_context *cc);
+
+/**
+ * \brief Set the AES/CTR+CBC implementation.
+ *
+ * \param cc SSL engine context.
+ * \param impl AES/CTR+CBC encryption/decryption implementation (or `NULL`).
+ */
+static inline void
+br_ssl_engine_set_aes_ctrcbc(br_ssl_engine_context *cc,
+ const br_block_ctrcbc_class *impl)
+{
+ cc->iaes_ctrcbc = impl;
+}
+
+/**
+ * \brief Set the "default" implementations for AES/CCM.
+ *
+ * This function configures in the engine the AES/CTR+CBC
+ * implementation that should provide best runtime performance on the local
+ * system, while still being safe (in particular, constant-time). It also
+ * sets the handlers for CCM records.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_aes_ccm(br_ssl_engine_context *cc);
+
/**
* \brief Set the record encryption and decryption engines for CBC + HMAC.
*
cc->igcm_out = impl_out;
}
+/**
+ * \brief Set the record encryption and decryption engines for CCM.
+ *
+ * \param cc SSL engine context.
+ * \param impl_in record CCM decryption implementation (or `NULL`).
+ * \param impl_out record CCM encryption implementation (or `NULL`).
+ */
+static inline void
+br_ssl_engine_set_ccm(br_ssl_engine_context *cc,
+ const br_sslrec_in_ccm_class *impl_in,
+ const br_sslrec_out_ccm_class *impl_out)
+{
+ cc->iccm_in = impl_in;
+ cc->iccm_out = impl_out;
+}
+
+/**
+ * \brief Set the record encryption and decryption engines for
+ * ChaCha20+Poly1305.
+ *
+ * \param cc SSL engine context.
+ * \param impl_in record ChaCha20 decryption implementation (or `NULL`).
+ * \param impl_out record ChaCha20 encryption implementation (or `NULL`).
+ */
+static inline void
+br_ssl_engine_set_chapol(br_ssl_engine_context *cc,
+ const br_sslrec_in_chapol_class *impl_in,
+ const br_sslrec_out_chapol_class *impl_out)
+{
+ cc->ichapol_in = impl_in;
+ cc->ichapol_out = impl_out;
+}
+
/**
* \brief Set the EC implementation.
*
cc->iec = iec;
}
+/**
+ * \brief Set the "default" EC implementation.
+ *
+ * This function sets the elliptic curve implementation for ECDH and
+ * ECDHE cipher suites, and for ECDSA support. It selects the fastest
+ * implementation on the current system.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_ec(br_ssl_engine_context *cc);
+
+/**
+ * \brief Get the EC implementation configured in the provided engine.
+ *
+ * \param cc SSL engine context.
+ * \return the EC implementation.
+ */
+static inline const br_ec_impl *
+br_ssl_engine_get_ec(br_ssl_engine_context *cc)
+{
+ return cc->iec;
+}
+
+/**
+ * \brief Set the RSA signature verification implementation.
+ *
+ * On the client, this is used to verify the server's signature on its
+ * ServerKeyExchange message (for ECDHE_RSA cipher suites). On the server,
+ * this is used to verify the client's CertificateVerify message (if a
+ * client certificate is requested, and that certificate contains a RSA key).
+ *
+ * \param cc SSL engine context.
+ * \param irsavrfy RSA signature verification implementation.
+ */
+static inline void
+br_ssl_engine_set_rsavrfy(br_ssl_engine_context *cc, br_rsa_pkcs1_vrfy irsavrfy)
+{
+ cc->irsavrfy = irsavrfy;
+}
+
+/**
+ * \brief Set the "default" RSA implementation (signature verification).
+ *
+ * This function sets the RSA implementation (signature verification)
+ * to the fastest implementation available on the current platform.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_rsavrfy(br_ssl_engine_context *cc);
+
+/**
+ * \brief Get the RSA implementation (signature verification) configured
+ * in the provided engine.
+ *
+ * \param cc SSL engine context.
+ * \return the RSA signature verification implementation.
+ */
+static inline br_rsa_pkcs1_vrfy
+br_ssl_engine_get_rsavrfy(br_ssl_engine_context *cc)
+{
+ return cc->irsavrfy;
+}
+
+/*
+ * \brief Set the ECDSA implementation (signature verification).
+ *
+ * On the client, this is used to verify the server's signature on its
+ * ServerKeyExchange message (for ECDHE_ECDSA cipher suites). On the server,
+ * this is used to verify the client's CertificateVerify message (if a
+ * client certificate is requested, that certificate contains an EC key,
+ * and full-static ECDH is not used).
+ *
+ * The ECDSA implementation will use the EC core implementation configured
+ * in the engine context.
+ *
+ * \param cc client context.
+ * \param iecdsa ECDSA verification implementation.
+ */
+static inline void
+br_ssl_engine_set_ecdsa(br_ssl_engine_context *cc, br_ecdsa_vrfy iecdsa)
+{
+ cc->iecdsa = iecdsa;
+}
+
+/**
+ * \brief Set the "default" ECDSA implementation (signature verification).
+ *
+ * This function sets the ECDSA implementation (signature verification)
+ * to the fastest implementation available on the current platform. This
+ * call also sets the elliptic curve implementation itself, there again
+ * to the fastest EC implementation available.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_set_default_ecdsa(br_ssl_engine_context *cc);
+
+/**
+ * \brief Get the ECDSA implementation (signature verification) configured
+ * in the provided engine.
+ *
+ * \param cc SSL engine context.
+ * \return the ECDSA signature verification implementation.
+ */
+static inline br_ecdsa_vrfy
+br_ssl_engine_get_ecdsa(br_ssl_engine_context *cc)
+{
+ return cc->iecdsa;
+}
+
/**
* \brief Set the I/O buffer for the SSL engine.
*
memcpy(&cc->session, pp, sizeof *pp);
}
+/**
+ * \brief Get identifier for the curve used for key exchange.
+ *
+ * If the cipher suite uses ECDHE, then this function returns the
+ * identifier for the curve used for transient parameters. This is
+ * defined during the course of the handshake, when the ServerKeyExchange
+ * is sent (on the server) or received (on the client). If the
+ * cipher suite does not use ECDHE (e.g. static ECDH, or RSA key
+ * exchange), then this value is indeterminate.
+ *
+ * @param cc SSL engine context.
+ * @return the ECDHE curve identifier.
+ */
+static inline int
+br_ssl_engine_get_ecdhe_curve(br_ssl_engine_context *cc)
+{
+ return cc->ecdhe_curve;
+}
+
/**
* \brief Get the current engine state.
*
* Informs the engine that 'len' bytes have been read from the buffer
* (extract operation) or written to the buffer (inject operation).
* The 'len' value MUST NOT be zero. The 'len' value MUST NOT exceed
- * that which was obtained from a preceeding br_ssl_engine_xxx_buf()
+ * that which was obtained from a preceding br_ssl_engine_xxx_buf()
* call.
*/
void br_ssl_engine_flush(br_ssl_engine_context *cc, int force);
/**
- * \brief Initiate a closure.
+ * \brief Initiate a closure.
+ *
+ * If, at that point, the context is open and in ready state, then a
+ * `close_notify` alert is assembled and marked for sending; this
+ * triggers the closure protocol. Otherwise, no such alert is assembled.
+ *
+ * \param cc SSL engine context.
+ */
+void br_ssl_engine_close(br_ssl_engine_context *cc);
+
+/**
+ * \brief Initiate a renegotiation.
+ *
+ * If the engine is failed or closed, or if the peer is known not to
+ * support secure renegotiation (RFC 5746), or if renegotiations have
+ * been disabled with the `BR_OPT_NO_RENEGOTIATION` flag, or if there
+ * is buffered incoming application data, then this function returns 0
+ * and nothing else happens.
+ *
+ * Otherwise, this function returns 1, and a renegotiation attempt is
+ * triggered (if a handshake is already ongoing at that point, then
+ * no new handshake is triggered).
+ *
+ * \param cc SSL engine context.
+ * \return 1 on success, 0 on error.
+ */
+int br_ssl_engine_renegotiate(br_ssl_engine_context *cc);
+
+/**
+ * \brief Export key material from a connected SSL engine (RFC 5705).
+ *
+ * This calls compute a secret key of arbitrary length from the master
+ * secret of a connected SSL engine. If the provided context is not
+ * currently in "application data" state (initial handshake is not
+ * finished, another handshake is ongoing, or the connection failed or
+ * was closed), then this function returns 0. Otherwise, a secret key of
+ * length `len` bytes is computed and written in the buffer pointed to
+ * by `dst`, and 1 is returned.
+ *
+ * The computed key follows the specification described in RFC 5705.
+ * That RFC includes two key computations, with and without a "context
+ * value". If `context` is `NULL`, then the variant without context is
+ * used; otherwise, the `context_len` bytes located at the address
+ * pointed to by `context` are used in the computation. Note that it
+ * is possible to have a "with context" key with a context length of
+ * zero bytes, by setting `context` to a non-`NULL` value but
+ * `context_len` to 0.
+ *
+ * When context bytes are used, the context length MUST NOT exceed
+ * 65535 bytes.
+ *
+ * \param cc SSL engine context.
+ * \param dst destination buffer for exported key.
+ * \param len exported key length (in bytes).
+ * \param label disambiguation label.
+ * \param context context value (or `NULL`).
+ * \param context_len context length (in bytes).
+ * \return 1 on success, 0 on error.
+ */
+int br_ssl_key_export(br_ssl_engine_context *cc,
+ void *dst, size_t len, const char *label,
+ const void *context, size_t context_len);
+
+/*
+ * Pre-declaration for the SSL client context.
+ */
+typedef struct br_ssl_client_context_ br_ssl_client_context;
+
+/**
+ * \brief Type for the client certificate, if requested by the server.
+ */
+typedef struct {
+ /**
+ * \brief Authentication type.
+ *
+ * This is either `BR_AUTH_RSA` (RSA signature), `BR_AUTH_ECDSA`
+ * (ECDSA signature), or `BR_AUTH_ECDH` (static ECDH key exchange).
+ */
+ int auth_type;
+
+ /**
+ * \brief Hash function for computing the CertificateVerify.
+ *
+ * This is the symbolic identifier for the hash function that
+ * will be used to produce the hash of handshake messages, to
+ * be signed into the CertificateVerify. For full static ECDH
+ * (client and server certificates are both EC in the same
+ * curve, and static ECDH is used), this value is set to -1.
+ *
+ * Take care that with TLS 1.0 and 1.1, that value MUST match
+ * the protocol requirements: value must be 0 (MD5+SHA-1) for
+ * a RSA signature, or 2 (SHA-1) for an ECDSA signature. Only
+ * TLS 1.2 allows for other hash functions.
+ */
+ int hash_id;
+
+ /**
+ * \brief Certificate chain to send to the server.
+ *
+ * This is an array of `br_x509_certificate` objects, each
+ * normally containing a DER-encoded certificate. The client
+ * code does not try to decode these elements. If there is no
+ * chain to send to the server, then this pointer shall be
+ * set to `NULL`.
+ */
+ const br_x509_certificate *chain;
+
+ /**
+ * \brief Certificate chain length (number of certificates).
+ *
+ * If there is no chain to send to the server, then this value
+ * shall be set to 0.
+ */
+ size_t chain_len;
+
+} br_ssl_client_certificate;
+
+/*
+ * Note: the constants below for signatures match the TLS constants.
+ */
+
+/** \brief Client authentication type: static ECDH. */
+#define BR_AUTH_ECDH 0
+/** \brief Client authentication type: RSA signature. */
+#define BR_AUTH_RSA 1
+/** \brief Client authentication type: ECDSA signature. */
+#define BR_AUTH_ECDSA 3
+
+/**
+ * \brief Class type for a certificate handler (client side).
+ *
+ * A certificate handler selects a client certificate chain to send to
+ * the server, upon explicit request from that server. It receives
+ * the list of trust anchor DN from the server, and supported types
+ * of certificates and signatures, and returns the chain to use. It
+ * is also invoked to perform the corresponding private key operation
+ * (a signature, or an ECDH computation).
+ *
+ * The SSL client engine will first push the trust anchor DN with
+ * `start_name_list()`, `start_name()`, `append_name()`, `end_name()`
+ * and `end_name_list()`. Then it will call `choose()`, to select the
+ * actual chain (and signature/hash algorithms). Finally, it will call
+ * either `do_sign()` or `do_keyx()`, depending on the algorithm choices.
+ */
+typedef struct br_ssl_client_certificate_class_ br_ssl_client_certificate_class;
+struct br_ssl_client_certificate_class_ {
+ /**
+ * \brief Context size (in bytes).
+ */
+ size_t context_size;
+
+ /**
+ * \brief Begin reception of a list of trust anchor names. This
+ * is called while parsing the incoming CertificateRequest.
+ *
+ * \param pctx certificate handler context.
+ */
+ void (*start_name_list)(const br_ssl_client_certificate_class **pctx);
+
+ /**
+ * \brief Begin reception of a new trust anchor name.
+ *
+ * The total encoded name length is provided; it is less than
+ * 65535 bytes.
+ *
+ * \param pctx certificate handler context.
+ * \param len encoded name length (in bytes).
+ */
+ void (*start_name)(const br_ssl_client_certificate_class **pctx,
+ size_t len);
+
+ /**
+ * \brief Receive some more bytes for the current trust anchor name.
+ *
+ * The provided reference (`data`) points to a transient buffer
+ * they may be reused as soon as this function returns. The chunk
+ * length (`len`) is never zero.
+ *
+ * \param pctx certificate handler context.
+ * \param data anchor name chunk.
+ * \param len anchor name chunk length (in bytes).
+ */
+ void (*append_name)(const br_ssl_client_certificate_class **pctx,
+ const unsigned char *data, size_t len);
+
+ /**
+ * \brief End current trust anchor name.
+ *
+ * This function is called when all the encoded anchor name data
+ * has been provided.
+ *
+ * \param pctx certificate handler context.
+ */
+ void (*end_name)(const br_ssl_client_certificate_class **pctx);
+
+ /**
+ * \brief End list of trust anchor names.
+ *
+ * This function is called when all the anchor names in the
+ * CertificateRequest message have been obtained.
+ *
+ * \param pctx certificate handler context.
+ */
+ void (*end_name_list)(const br_ssl_client_certificate_class **pctx);
+
+ /**
+ * \brief Select client certificate and algorithms.
+ *
+ * This callback function shall fill the provided `choices`
+ * structure with the selected algorithms and certificate chain.
+ * The `hash_id`, `chain` and `chain_len` fields must be set. If
+ * the client cannot or does not wish to send a certificate,
+ * then it shall set `chain` to `NULL` and `chain_len` to 0.
+ *
+ * The `auth_types` parameter describes the authentication types,
+ * signature algorithms and hash functions that are supported by
+ * both the client context and the server, and compatible with
+ * the current protocol version. This is a bit field with the
+ * following contents:
+ *
+ * - If RSA signatures with hash function x are supported, then
+ * bit x is set.
+ *
+ * - If ECDSA signatures with hash function x are supported,
+ * then bit 8+x is set.
+ *
+ * - If static ECDH is supported, with a RSA-signed certificate,
+ * then bit 16 is set.
+ *
+ * - If static ECDH is supported, with an ECDSA-signed certificate,
+ * then bit 17 is set.
+ *
+ * Notes:
+ *
+ * - When using TLS 1.0 or 1.1, the hash function for RSA
+ * signatures is always the special MD5+SHA-1 (id 0), and the
+ * hash function for ECDSA signatures is always SHA-1 (id 2).
+ *
+ * - When using TLS 1.2, the list of hash functions is trimmed
+ * down to include only hash functions that the client context
+ * can support. The actual server list can be obtained with
+ * `br_ssl_client_get_server_hashes()`; that list may be used
+ * to select the certificate chain to send to the server.
+ *
+ * \param pctx certificate handler context.
+ * \param cc SSL client context.
+ * \param auth_types supported authentication types and algorithms.
+ * \param choices destination structure for the policy choices.
+ */
+ void (*choose)(const br_ssl_client_certificate_class **pctx,
+ const br_ssl_client_context *cc, uint32_t auth_types,
+ br_ssl_client_certificate *choices);
+
+ /**
+ * \brief Perform key exchange (client part).
+ *
+ * This callback is invoked in case of a full static ECDH key
+ * exchange:
+ *
+ * - the cipher suite uses `ECDH_RSA` or `ECDH_ECDSA`;
+ *
+ * - the server requests a client certificate;
+ *
+ * - the client has, and sends, a client certificate that
+ * uses an EC key in the same curve as the server's key,
+ * and chooses static ECDH (the `hash_id` field in the choice
+ * structure was set to -1).
+ *
+ * In that situation, this callback is invoked to compute the
+ * client-side ECDH: the provided `data` (of length `*len` bytes)
+ * is the server's public key point (as decoded from its
+ * certificate), and the client shall multiply that point with
+ * its own private key, and write back the X coordinate of the
+ * resulting point in the same buffer, starting at offset 0.
+ * The `*len` value shall be modified to designate the actual
+ * length of the X coordinate.
+ *
+ * The callback must uphold the following:
+ *
+ * - If the input array does not have the proper length for
+ * an encoded curve point, then an error (0) shall be reported.
+ *
+ * - If the input array has the proper length, then processing
+ * MUST be constant-time, even if the data is not a valid
+ * encoded point.
+ *
+ * - This callback MUST check that the input point is valid.
+ *
+ * Returned value is 1 on success, 0 on error.
+ *
+ * \param pctx certificate handler context.
+ * \param data server public key point.
+ * \param len public key point length / X coordinate length.
+ * \return 1 on success, 0 on error.
+ */
+ uint32_t (*do_keyx)(const br_ssl_client_certificate_class **pctx,
+ unsigned char *data, size_t *len);
+
+ /**
+ * \brief Perform a signature (client authentication).
+ *
+ * This callback is invoked when a client certificate was sent,
+ * and static ECDH is not used. It shall compute a signature,
+ * using the client's private key, over the provided hash value
+ * (which is the hash of all previous handshake messages).
+ *
+ * On input, the hash value to sign is in `data`, of size
+ * `hv_len`; the involved hash function is identified by
+ * `hash_id`. The signature shall be computed and written
+ * back into `data`; the total size of that buffer is `len`
+ * bytes.
+ *
+ * This callback shall verify that the signature length does not
+ * exceed `len` bytes, and abstain from writing the signature if
+ * it does not fit.
+ *
+ * For RSA signatures, the `hash_id` may be 0, in which case
+ * this is the special header-less signature specified in TLS 1.0
+ * and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1
+ * v1.5 signatures shall be computed.
+ *
+ * For ECDSA signatures, the signature value shall use the ASN.1
+ * based encoding.
+ *
+ * Returned value is the signature length (in bytes), or 0 on error.
+ *
+ * \param pctx certificate handler context.
+ * \param hash_id hash function identifier.
+ * \param hv_len hash value length (in bytes).
+ * \param data input/output buffer (hash value, then signature).
+ * \param len total buffer length (in bytes).
+ * \return signature length (in bytes) on success, or 0 on error.
+ */
+ size_t (*do_sign)(const br_ssl_client_certificate_class **pctx,
+ int hash_id, size_t hv_len, unsigned char *data, size_t len);
+};
+
+/**
+ * \brief A single-chain RSA client certificate handler.
*
- * If, at that point, the context is open and in ready state, then a
- * `close_notify` alert is assembled and marked for sending; this
- * triggers the closure protocol. Otherwise, no such alert is assembled.
+ * This handler uses a single certificate chain, with a RSA
+ * signature. The list of trust anchor DN is ignored.
*
- * \param cc SSL engine context.
+ * Apart from the first field (vtable pointer), its contents are
+ * opaque and shall not be accessed directly.
*/
-void br_ssl_engine_close(br_ssl_engine_context *cc);
+typedef struct {
+ /** \brief Pointer to vtable. */
+ const br_ssl_client_certificate_class *vtable;
+#ifndef BR_DOXYGEN_IGNORE
+ const br_x509_certificate *chain;
+ size_t chain_len;
+ const br_rsa_private_key *sk;
+ br_rsa_pkcs1_sign irsasign;
+#endif
+} br_ssl_client_certificate_rsa_context;
/**
- * \brief Initiate a renegotiation.
+ * \brief A single-chain EC client certificate handler.
*
- * If the engine is failed or closed, or if the peer is known not to
- * support secure renegotiation (RFC 5746), or if renegotiations have
- * been disabled with the `BR_OPT_NO_RENEGOTIATION` flag, then this
- * function returns 0 and nothing else happens.
+ * This handler uses a single certificate chain, with a RSA
+ * signature. The list of trust anchor DN is ignored.
*
- * Otherwise, this function returns 1, and a renegotiation attempt is
- * triggered (if a handshake is already ongoing at that point, then
- * no new handshake is triggered).
+ * This handler may support both static ECDH, and ECDSA signatures
+ * (either usage may be selectively disabled).
*
- * \param cc SSL engine context.
- * \return 1 on success, 0 on error.
+ * Apart from the first field (vtable pointer), its contents are
+ * opaque and shall not be accessed directly.
*/
-int br_ssl_engine_renegotiate(br_ssl_engine_context *cc);
+typedef struct {
+ /** \brief Pointer to vtable. */
+ const br_ssl_client_certificate_class *vtable;
+#ifndef BR_DOXYGEN_IGNORE
+ const br_x509_certificate *chain;
+ size_t chain_len;
+ const br_ec_private_key *sk;
+ unsigned allowed_usages;
+ unsigned issuer_key_type;
+ const br_multihash_context *mhash;
+ const br_ec_impl *iec;
+ br_ecdsa_sign iecdsa;
+#endif
+} br_ssl_client_certificate_ec_context;
/**
* \brief Context structure for a SSL client.
* a pointer to that field. The other structure fields are opaque and
* must not be accessed directly.
*/
-typedef struct {
+struct br_ssl_client_context_ {
/**
* \brief The encapsulated engine context.
*/
*/
uint16_t min_clienthello_len;
+ /*
+ * Bit field for algoithms (hash + signature) supported by the
+ * server when requesting a client certificate.
+ */
+ uint32_t hashes;
+
+ /*
+ * Server's public key curve.
+ */
+ int server_curve;
+
+ /*
+ * Context for certificate handler.
+ */
+ const br_ssl_client_certificate_class **client_auth_vtable;
+
+ /*
+ * Client authentication type.
+ */
+ unsigned char auth_type;
+
+ /*
+ * Hash function to use for the client signature. This is 0xFF
+ * if static ECDH is used.
+ */
+ unsigned char hash_id;
+
+ /*
+ * For the core certificate handlers, thus avoiding (in most
+ * cases) the need for an externally provided policy context.
+ */
+ union {
+ const br_ssl_client_certificate_class *vtable;
+ br_ssl_client_certificate_rsa_context single_rsa;
+ br_ssl_client_certificate_ec_context single_ec;
+ } client_auth;
+
/*
* Implementations.
*/
br_rsa_public irsapub;
- br_rsa_pkcs1_vrfy irsavrfy;
- br_ecdsa_vrfy iecdsa;
#endif
-} br_ssl_client_context;
+};
+
+/**
+ * \brief Get the hash functions and signature algorithms supported by
+ * the server.
+ *
+ * This value is a bit field:
+ *
+ * - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
+ * then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
+ * or 2 to 6 for the SHA family).
+ *
+ * - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
+ * is set.
+ *
+ * - Newer algorithms are symbolic 16-bit identifiers that do not
+ * represent signature algorithm and hash function separately. If
+ * the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
+ * range, then bit `16+x` is set.
+ *
+ * "New algorithms" are currently defined only in draft documents, so
+ * this support is subject to possible change. Right now (early 2017),
+ * this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA
+ * on Curve448) to bit 24. If the identifiers on the wire change in
+ * future document, then the decoding mechanism in BearSSL will be
+ * amended to keep mapping ed25519 and ed448 on bits 23 and 24,
+ * respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not
+ * guaranteed yet.
+ *
+ * \param cc client context.
+ * \return the server-supported hash functions and signature algorithms.
+ */
+static inline uint32_t
+br_ssl_client_get_server_hashes(const br_ssl_client_context *cc)
+{
+ return cc->hashes;
+}
+
+/**
+ * \brief Get the server key curve.
+ *
+ * This function returns the ID for the curve used by the server's public
+ * key. This is set when the server's certificate chain is processed;
+ * this value is 0 if the server's key is not an EC key.
+ *
+ * \return the server's public key curve ID, or 0.
+ */
+static inline int
+br_ssl_client_get_server_curve(const br_ssl_client_context *cc)
+{
+ return cc->server_curve;
+}
/*
* Each br_ssl_client_init_xxx() function sets the list of supported
void br_ssl_client_zero(br_ssl_client_context *cc);
/**
- * \brief Set the RSA public-key operations implementation.
+ * \brief Set an externally provided client certificate handler context.
*
- * This will be used to encrypt the pre-master secret with the server's
- * RSA public key (RSA-encryption cipher suites only).
+ * The handler's methods are invoked when the server requests a client
+ * certificate.
*
- * \param cc client context.
- * \param irsapub RSA public-key encryption implementation.
+ * \param cc client context.
+ * \param pctx certificate handler context (pointer to its vtable field).
*/
static inline void
-br_ssl_client_set_rsapub(br_ssl_client_context *cc, br_rsa_public irsapub)
+br_ssl_client_set_client_certificate(br_ssl_client_context *cc,
+ const br_ssl_client_certificate_class **pctx)
{
- cc->irsapub = irsapub;
+ cc->client_auth_vtable = pctx;
}
/**
- * \brief Set the RSA signature verification implementation.
+ * \brief Set the RSA public-key operations implementation.
*
- * This will be used to verify the server's signature on its
- * ServerKeyExchange message (ECDHE_RSA cipher suites only).
+ * This will be used to encrypt the pre-master secret with the server's
+ * RSA public key (RSA-encryption cipher suites only).
*
- * \param cc client context.
- * \param irsavrfy RSA signature verification implementation.
+ * \param cc client context.
+ * \param irsapub RSA public-key encryption implementation.
*/
static inline void
-br_ssl_client_set_rsavrfy(br_ssl_client_context *cc, br_rsa_pkcs1_vrfy irsavrfy)
+br_ssl_client_set_rsapub(br_ssl_client_context *cc, br_rsa_public irsapub)
{
- cc->irsavrfy = irsavrfy;
+ cc->irsapub = irsapub;
}
-/*
- * \brief Set the ECDSA implementation (signature verification).
+/**
+ * \brief Set the "default" RSA implementation for public-key operations.
*
- * The ECDSA implementation will use the EC core implementation configured
- * in the engine context.
+ * This sets the RSA implementation in the client context (for encrypting
+ * the pre-master secret, in `TLS_RSA_*` cipher suites) to the fastest
+ * available on the current platform.
*
- * \param cc client context.
- * \param iecdsa ECDSA verification implementation.
+ * \param cc client context.
*/
-static inline void
-br_ssl_client_set_ecdsa(br_ssl_client_context *cc, br_ecdsa_vrfy iecdsa)
-{
- cc->iecdsa = iecdsa;
-}
+void br_ssl_client_set_default_rsapub(br_ssl_client_context *cc);
/**
* \brief Set the minimum ClientHello length (RFC 7685 padding).
cc->eng.session.session_id_len = 0;
}
+/**
+ * \brief Set client certificate chain and key (single RSA case).
+ *
+ * This function sets a client certificate chain, that the client will
+ * send to the server whenever a client certificate is requested. This
+ * certificate uses an RSA public key; the corresponding private key is
+ * invoked for authentication. Trust anchor names sent by the server are
+ * ignored.
+ *
+ * The provided chain and private key are linked in the client context;
+ * they must remain valid as long as they may be used, i.e. normally
+ * for the duration of the connection, since they might be invoked
+ * again upon renegotiations.
+ *
+ * \param cc SSL client context.
+ * \param chain client certificate chain (SSL order: EE comes first).
+ * \param chain_len client chain length (number of certificates).
+ * \param sk client private key.
+ * \param irsasign RSA signature implementation (PKCS#1 v1.5).
+ */
+void br_ssl_client_set_single_rsa(br_ssl_client_context *cc,
+ const br_x509_certificate *chain, size_t chain_len,
+ const br_rsa_private_key *sk, br_rsa_pkcs1_sign irsasign);
+
+/*
+ * \brief Set the client certificate chain and key (single EC case).
+ *
+ * This function sets a client certificate chain, that the client will
+ * send to the server whenever a client certificate is requested. This
+ * certificate uses an EC public key; the corresponding private key is
+ * invoked for authentication. Trust anchor names sent by the server are
+ * ignored.
+ *
+ * The provided chain and private key are linked in the client context;
+ * they must remain valid as long as they may be used, i.e. normally
+ * for the duration of the connection, since they might be invoked
+ * again upon renegotiations.
+ *
+ * The `allowed_usages` is a combination of usages, namely
+ * `BR_KEYTYPE_KEYX` and/or `BR_KEYTYPE_SIGN`. The `BR_KEYTYPE_KEYX`
+ * value allows full static ECDH, while the `BR_KEYTYPE_SIGN` value
+ * allows ECDSA signatures. If ECDSA signatures are used, then an ECDSA
+ * signature implementation must be provided; otherwise, the `iecdsa`
+ * parameter may be 0.
+ *
+ * The `cert_issuer_key_type` value is either `BR_KEYTYPE_RSA` or
+ * `BR_KEYTYPE_EC`; it is the type of the public key used the the CA
+ * that issued (signed) the client certificate. That value is used with
+ * full static ECDH: support of the certificate by the server depends
+ * on how the certificate was signed. (Note: when using TLS 1.2, this
+ * parameter is ignored; but its value matters for TLS 1.0 and 1.1.)
+ *
+ * \param cc server context.
+ * \param chain server certificate chain to send.
+ * \param chain_len chain length (number of certificates).
+ * \param sk server private key (EC).
+ * \param allowed_usages allowed private key usages.
+ * \param cert_issuer_key_type issuing CA's key type.
+ * \param iec EC core implementation.
+ * \param iecdsa ECDSA signature implementation ("asn1" format).
+ */
+void br_ssl_client_set_single_ec(br_ssl_client_context *cc,
+ const br_x509_certificate *chain, size_t chain_len,
+ const br_ec_private_key *sk, unsigned allowed_usages,
+ unsigned cert_issuer_key_type,
+ const br_ec_impl *iec, br_ecdsa_sign iecdsa);
+
/**
* \brief Type for a "translated cipher suite", as an array of two
* 16-bit integers.
uint16_t cipher_suite;
/**
- * \brief Hash function for signing the ServerKeyExchange.
+ * \brief Hash function or algorithm for signing the ServerKeyExchange.
*
- * This is the symbolic identifier for the hash function that
- * will be used to sign the ServerKeyExchange message, for ECDHE
- * cipher suites. This is ignored for RSA and ECDH cipher suites.
+ * This parameter is ignored for `TLS_RSA_*` and `TLS_ECDH_*`
+ * cipher suites; it is used only for `TLS_ECDHE_*` suites, in
+ * which the server _signs_ the ephemeral EC Diffie-Hellman
+ * parameters sent to the client.
*
- * Take care that with TLS 1.0 and 1.1, that value MUST match
- * the protocol requirements: value must be 0 (MD5+SHA-1) for
- * a RSA signature, or 2 (SHA-1) for an ECDSA signature. Only
- * TLS 1.2 allows for other hash functions.
+ * This identifier must be one of the following values:
+ *
+ * - `0xFF00 + id`, where `id` is a hash function identifier
+ * (0 for MD5+SHA-1, or 2 to 6 for one of the SHA functions);
+ *
+ * - a full 16-bit identifier, lower than `0xFF00`.
+ *
+ * If the first option is used, then the SSL engine will
+ * compute the hash of the data that is to be signed, with the
+ * designated hash function. The `do_sign()` method will be
+ * invoked with that hash value provided in the the `data`
+ * buffer.
+ *
+ * If the second option is used, then the SSL engine will NOT
+ * compute a hash on the data; instead, it will provide the
+ * to-be-signed data itself in `data`, i.e. the concatenation of
+ * the client random, server random, and encoded ECDH
+ * parameters. Furthermore, with TLS-1.2 and later, the 16-bit
+ * identifier will be used "as is" in the protocol, in the
+ * SignatureAndHashAlgorithm; for instance, `0x0401` stands for
+ * RSA PKCS#1 v1.5 signature (the `01`) with SHA-256 as hash
+ * function (the `04`).
+ *
+ * Take care that with TLS 1.0 and 1.1, the hash function is
+ * constrainted by the protocol: RSA signature must use
+ * MD5+SHA-1 (so use `0xFF00`), while ECDSA must use SHA-1
+ * (`0xFF02`). Since TLS 1.0 and 1.1 don't include a
+ * SignatureAndHashAlgorithm field in their ServerKeyExchange
+ * messages, any value below `0xFF00` will be usable to send the
+ * raw ServerKeyExchange data to the `do_sign()` callback, but
+ * that callback must still follow the protocol requirements
+ * when generating the signature.
*/
- int hash_id;
+ unsigned algo_id;
/**
* \brief Certificate chain to send to the client.
* \brief Certificate chain length (number of certificates).
*/
size_t chain_len;
+
} br_ssl_server_choices;
/**
* operation for a key exchange that is not ECDHE. This callback
* uses the private key.
*
- * **For RSA key exchange**, the provided `data` (of length `len`
+ * **For RSA key exchange**, the provided `data` (of length `*len`
* bytes) shall be decrypted with the server's private key, and
* the 48-byte premaster secret copied back to the first 48 bytes
* of `data`.
*
- * - The caller makes sure that `len` is at least 59 bytes.
+ * - The caller makes sure that `*len` is at least 59 bytes.
*
* - This callback MUST check that the provided length matches
* that of the key modulus; it shall report an error otherwise.
* in the first 48 bytes of `data` is unimportant (the caller
* will use random bytes instead).
*
- * **For ECDH key exchange**, the provided `data` (of length `len`
+ * **For ECDH key exchange**, the provided `data` (of length `*len`
* bytes) is the elliptic curve point from the client. The
* callback shall multiply it with its private key, and store
- * the resulting X coordinate in `data`, starting at offset 1
- * (thus, simply encoding the point in compressed or uncompressed
- * format in `data` is fine).
+ * the resulting X coordinate in `data`, starting at offset 0,
+ * and set `*len` to the length of the X coordinate.
*
* - If the input array does not have the proper length for
* an encoded curve point, then an error (0) shall be reported.
* \return 1 on success, 0 on error.
*/
uint32_t (*do_keyx)(const br_ssl_server_policy_class **pctx,
- unsigned char *data, size_t len);
+ unsigned char *data, size_t *len);
/**
* \brief Perform a signature (for a ServerKeyExchange message).
*
- * This callback function is invoked for ECDHE cipher suites.
- * On input, the hash value to sign is in `data`, of size
- * `hv_len`; the involved hash function is identified by
- * `hash_id`. The signature shall be computed and written
- * back into `data`; the total size of that buffer is `len`
- * bytes.
+ * This callback function is invoked for ECDHE cipher suites. On
+ * input, the hash value or message to sign is in `data`, of
+ * size `hv_len`; the involved hash function or algorithm is
+ * identified by `algo_id`. The signature shall be computed and
+ * written back into `data`; the total size of that buffer is
+ * `len` bytes.
*
* This callback shall verify that the signature length does not
* exceed `len` bytes, and abstain from writing the signature if
* it does not fit.
*
- * For RSA signatures, the `hash_id` may be 0, in which case
- * this is the special header-less signature specified in TLS 1.0
- * and 1.1, with a 36-byte hash value. Otherwise, normal PKCS#1
- * v1.5 signatures shall be computed.
+ * The `algo_id` value matches that which was written in the
+ * `choices` structures by the `choose()` callback. This will be
+ * one of the following:
+ *
+ * - `0xFF00 + id` for a hash function identifier `id`. In
+ * that case, the `data` buffer contains a hash value
+ * already computed over the data that is to be signed,
+ * of length `hv_len`. The `id` may be 0 to designate the
+ * special MD5+SHA-1 concatenation (old-style RSA signing).
+ *
+ * - Another value, lower than `0xFF00`. The `data` buffer
+ * then contains the raw, non-hashed data to be signed
+ * (concatenation of the client and server randoms and
+ * ECDH parameters). The callback is responsible to apply
+ * any relevant hashing as part of the signing process.
*
* Returned value is the signature length (in bytes), or 0 on error.
*
* \param pctx policy context.
- * \param hash_id hash function identifier.
- * \param hv_len hash value length (in bytes).
- * \param data input/output buffer (hash value, then signature).
+ * \param algo_id hash function / algorithm identifier.
+ * \param data input/output buffer (message/hash, then signature).
+ * \param hv_len hash value or message length (in bytes).
* \param len total buffer length (in bytes).
* \return signature length (in bytes) on success, or 0 on error.
*/
size_t (*do_sign)(const br_ssl_server_policy_class **pctx,
- int hash_id, size_t hv_len, unsigned char *data, size_t len);
+ unsigned algo_id,
+ unsigned char *data, size_t hv_len, size_t len);
};
/**
void br_ssl_session_cache_lru_init(br_ssl_session_cache_lru *cc,
unsigned char *store, size_t store_len);
+/**
+ * \brief Forget an entry in an LRU session cache.
+ *
+ * The session cache context must have been initialised. The entry
+ * with the provided session ID (of exactly 32 bytes) is looked for
+ * in the cache; if located, it is disabled.
+ *
+ * \param cc session cache context.
+ * \param id session ID to forget.
+ */
+void br_ssl_session_cache_lru_forget(
+ br_ssl_session_cache_lru *cc, const unsigned char *id);
+
/**
* \brief Context structure for a SSL server.
*
/*
* Hash functions supported by the client, with ECDSA and RSA
* (bit mask). For hash function with id 'x', set bit index is
- * x for RSA, x+8 for ECDSA.
+ * x for RSA, x+8 for ECDSA. For newer algorithms, with ID
+ * 0x08**, bit 16+k is set for algorithm 0x0800+k.
*/
- uint16_t hashes;
+ uint32_t hashes;
/*
* Curves supported by the client (bit mask, for named curves).
* Context for chain handler.
*/
const br_ssl_server_policy_class **policy_vtable;
- const br_x509_certificate *chain;
- size_t chain_len;
- const unsigned char *cert_cur;
- size_t cert_len;
- unsigned char sign_hash_id;
+ uint16_t sign_hash_id;
/*
* For the core handlers, thus avoiding (in most cases) the
unsigned char ecdhe_key[70];
size_t ecdhe_key_len;
+ /*
+ * Trust anchor names for client authentication. "ta_names" and
+ * "tas" cannot be both non-NULL.
+ */
+ const br_x500_name *ta_names;
+ const br_x509_trust_anchor *tas;
+ size_t num_tas;
+ size_t cur_dn_index;
+ const unsigned char *cur_dn;
+ size_t cur_dn_len;
+
+ /*
+ * Buffer for the hash value computed over all handshake messages
+ * prior to CertificateVerify, and identifier for the hash function.
+ */
+ unsigned char hash_CV[64];
+ size_t hash_CV_len;
+ int hash_CV_id;
+
/*
* Server-specific implementations.
* (none for now)
* 3 = TLS 1.2 with SHA-384
* -- character 3: encryption
* a = AES/CBC
- * g = AES/GCM
* d = 3DES/CBC
+ * g = AES/GCM
+ * c = ChaCha20+Poly1305
*/
/**
const br_x509_certificate *chain, size_t chain_len,
const br_ec_private_key *sk);
+/**
+ * \brief SSL server profile: mine2c.
+ *
+ * This profile uses only TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256.
+ * Server key is RSA, and ECDHE key exchange is used. This suite
+ * provides forward security.
+ *
+ * \param cc server context to initialise.
+ * \param chain server certificate chain.
+ * \param chain_len certificate chain length (number of certificate).
+ * \param sk RSA private key.
+ */
+void br_ssl_server_init_mine2c(br_ssl_server_context *cc,
+ const br_x509_certificate *chain, size_t chain_len,
+ const br_rsa_private_key *sk);
+
+/**
+ * \brief SSL server profile: minf2c.
+ *
+ * This profile uses only TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256.
+ * Server key is EC, and ECDHE key exchange is used. This suite provides
+ * forward security.
+ *
+ * \param cc server context to initialise.
+ * \param chain server certificate chain.
+ * \param chain_len certificate chain length (number of certificate).
+ * \param sk EC private key.
+ */
+void br_ssl_server_init_minf2c(br_ssl_server_context *cc,
+ const br_x509_certificate *chain, size_t chain_len,
+ const br_ec_private_key *sk);
+
/**
* \brief Get the supported client suites.
*
}
/**
- * \brief Get the hash functions supported by the client.
+ * \brief Get the hash functions and signature algorithms supported by
+ * the client.
+ *
+ * This value is a bit field:
+ *
+ * - If RSA (PKCS#1 v1.5) is supported with hash function of ID `x`,
+ * then bit `x` is set (hash function ID is 0 for the special MD5+SHA-1,
+ * or 2 to 6 for the SHA family).
+ *
+ * - If ECDSA is supported with hash function of ID `x`, then bit `8+x`
+ * is set.
*
- * This is a field of bits: for hash function of ID x, bit x is set if
- * the hash function is supported in RSA signatures, 8+x if it is supported
- * with ECDSA.
+ * - Newer algorithms are symbolic 16-bit identifiers that do not
+ * represent signature algorithm and hash function separately. If
+ * the TLS-level identifier is `0x0800+x` for a `x` in the 0..15
+ * range, then bit `16+x` is set.
+ *
+ * "New algorithms" are currently defined only in draft documents, so
+ * this support is subject to possible change. Right now (early 2017),
+ * this maps ed25519 (EdDSA on Curve25519) to bit 23, and ed448 (EdDSA
+ * on Curve448) to bit 24. If the identifiers on the wire change in
+ * future document, then the decoding mechanism in BearSSL will be
+ * amended to keep mapping ed25519 and ed448 on bits 23 and 24,
+ * respectively. Mapping of other new algorithms (e.g. RSA/PSS) is not
+ * guaranteed yet.
*
* \param cc server context.
- * \return the client-supported hash functions (for signatures).
+ * \return the client-supported hash functions and signature algorithms.
*/
-static inline uint16_t
+static inline uint32_t
br_ssl_server_get_client_hashes(const br_ssl_server_context *cc)
{
return cc->hashes;
const br_rsa_private_key *sk, unsigned allowed_usages,
br_rsa_private irsacore, br_rsa_pkcs1_sign irsasign);
-/*
+/**
* \brief Set the server certificate chain and key (single EC case).
*
* This function uses a policy context included in the server context.
unsigned cert_issuer_key_type,
const br_ec_impl *iec, br_ecdsa_sign iecdsa);
+/**
+ * \brief Activate client certificate authentication.
+ *
+ * The trust anchor encoded X.500 names (DN) to send to the client are
+ * provided. A client certificate will be requested and validated through
+ * the X.509 validator configured in the SSL engine. If `num` is 0, then
+ * client certificate authentication is disabled.
+ *
+ * If the client does not send a certificate, or on validation failure,
+ * the handshake aborts. Unauthenticated clients can be tolerated by
+ * setting the `BR_OPT_TOLERATE_NO_CLIENT_AUTH` flag.
+ *
+ * The provided array is linked in, not copied, so that pointer must
+ * remain valid as long as anchor names may be used.
+ *
+ * \param cc server context.
+ * \param ta_names encoded trust anchor names.
+ * \param num number of encoded trust anchor names.
+ */
+static inline void
+br_ssl_server_set_trust_anchor_names(br_ssl_server_context *cc,
+ const br_x500_name *ta_names, size_t num)
+{
+ cc->ta_names = ta_names;
+ cc->tas = NULL;
+ cc->num_tas = num;
+}
+
+/**
+ * \brief Activate client certificate authentication.
+ *
+ * This is a variant for `br_ssl_server_set_trust_anchor_names()`: the
+ * trust anchor names are provided not as an array of stand-alone names
+ * (`br_x500_name` structures), but as an array of trust anchors
+ * (`br_x509_trust_anchor` structures). The server engine itself will
+ * only use the `dn` field of each trust anchor. This is meant to allow
+ * defining a single array of trust anchors, to be used here and in the
+ * X.509 validation engine itself.
+ *
+ * The provided array is linked in, not copied, so that pointer must
+ * remain valid as long as anchor names may be used.
+ *
+ * \param cc server context.
+ * \param tas trust anchors (only names are used).
+ * \param num number of trust anchors.
+ */
+static inline void
+br_ssl_server_set_trust_anchor_names_alt(br_ssl_server_context *cc,
+ const br_x509_trust_anchor *tas, size_t num)
+{
+ cc->ta_names = NULL;
+ cc->tas = tas;
+ cc->num_tas = num;
+}
+
/**
* \brief Configure the cache for session parameters.
*
#define BR_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 0xC031
#define BR_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 0xC032
+/* From RFC 6655 and 7251 */
+#define BR_TLS_RSA_WITH_AES_128_CCM 0xC09C
+#define BR_TLS_RSA_WITH_AES_256_CCM 0xC09D
+#define BR_TLS_RSA_WITH_AES_128_CCM_8 0xC0A0
+#define BR_TLS_RSA_WITH_AES_256_CCM_8 0xC0A1
+#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM 0xC0AC
+#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM 0xC0AD
+#define BR_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0xC0AE
+#define BR_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8 0xC0AF
+
/* From RFC 7905 */
#define BR_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
#define BR_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
#define BR_ALERT_USER_CANCELED 90
#define BR_ALERT_NO_RENEGOTIATION 100
#define BR_ALERT_UNSUPPORTED_EXTENSION 110
+#define BR_ALERT_NO_APPLICATION_PROTOCOL 120
+
+#ifdef __cplusplus
+}
+#endif
#endif
projects / BearSSL / blobdiff