X-Git-Url: https://www.bearssl.org/gitweb//home/git/?p=BearSSL;a=blobdiff_plain;f=inc%2Fbearssl_ssl.h;h=2ac9e258a79b1ed2053dccaa189d770f095ac033;hp=3ff29f69f4374636a9f4059a6d0474c086a09736;hb=968da0f646a43c69a2517a240c9963ff513981b3;hpb=ef318ef83a3a58b0a9e036676b84d11261ed7bb4 diff --git a/inc/bearssl_ssl.h b/inc/bearssl_ssl.h index 3ff29f6..2ac9e25 100644 --- a/inc/bearssl_ssl.h +++ b/inc/bearssl_ssl.h @@ -35,6 +35,10 @@ #include "bearssl_rand.h" #include "bearssl_x509.h" +#ifdef __cplusplus +extern "C" { +#endif + /** \file bearssl_ssl.h * * # SSL @@ -819,8 +823,11 @@ typedef struct { } 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; @@ -1321,6 +1328,18 @@ br_ssl_engine_set_aes_cbc(br_ssl_engine_context *cc, 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. * @@ -1334,6 +1353,18 @@ br_ssl_engine_set_aes_ctr(br_ssl_engine_context *cc, 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. * @@ -1350,6 +1381,18 @@ br_ssl_engine_set_des_cbc(br_ssl_engine_context *cc, 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). * @@ -1388,6 +1431,18 @@ br_ssl_engine_set_poly1305(br_ssl_engine_context *cc, 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 record encryption and decryption engines for CBC + HMAC. * @@ -1452,6 +1507,29 @@ br_ssl_engine_set_ec(br_ssl_engine_context *cc, const br_ec_impl *iec) 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. * @@ -1469,6 +1547,29 @@ 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). * @@ -1490,6 +1591,31 @@ 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. * @@ -1657,6 +1783,25 @@ br_ssl_engine_set_session_parameters(br_ssl_engine_context *cc, 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. * @@ -2136,12 +2281,13 @@ struct br_ssl_client_certificate_class_ { * 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) + * 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 1 - * (therefore, writing back the complete encoded point works). + * 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: * @@ -2158,11 +2304,11 @@ struct br_ssl_client_certificate_class_ { * * \param pctx certificate handler context. * \param data server public key point. - * \param len server public key point length (in bytes). + * \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); + unsigned char *data, size_t *len); /** * \brief Perform a signature (client authentication). @@ -2437,6 +2583,17 @@ br_ssl_client_set_rsapub(br_ssl_client_context *cc, br_rsa_public irsapub) cc->irsapub = irsapub; } +/** + * \brief Set the "default" RSA implementation for public-key operations. + * + * 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. + */ +void br_ssl_client_set_default_rsapub(br_ssl_client_context *cc); + /** * \brief Set the minimum ClientHello length (RFC 7685 padding). * @@ -2791,12 +2948,12 @@ struct br_ssl_server_policy_class_ { * 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. @@ -2813,12 +2970,11 @@ struct br_ssl_server_policy_class_ { * 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. @@ -2837,7 +2993,7 @@ struct br_ssl_server_policy_class_ { * \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). @@ -3146,8 +3302,9 @@ struct br_ssl_server_context_ { * 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 */ /** @@ -3915,4 +4072,8 @@ int br_sslio_close(br_sslio_context *cc); #define BR_ALERT_UNSUPPORTED_EXTENSION 110 #define BR_ALERT_NO_APPLICATION_PROTOCOL 120 +#ifdef __cplusplus +} +#endif + #endif