X-Git-Url: https://www.bearssl.org/gitweb//home/git/?p=BearSSL;a=blobdiff_plain;f=inc%2Fbearssl_ssl.h;h=d15cf55192c04d8ab1b98a5dfff2adabc7ea3a16;hp=3ff29f69f4374636a9f4059a6d0474c086a09736;hb=127fb4a31d24e58fa8e04a154c6e87a2cb28245b;hpb=ef318ef83a3a58b0a9e036676b84d11261ed7bb4 diff --git a/inc/bearssl_ssl.h b/inc/bearssl_ssl.h index 3ff29f6..d15cf55 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; @@ -864,8 +871,8 @@ typedef struct { /* * 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 @@ -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. * @@ -1918,8 +2063,9 @@ void br_ssl_engine_close(br_ssl_engine_context *cc); * * 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. + * 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 @@ -1930,6 +2076,41 @@ void br_ssl_engine_close(br_ssl_engine_context *cc); */ 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. */ @@ -2136,12 +2317,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 +2340,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 +2619,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 +2984,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 +3006,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 +3029,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 +3338,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 +4108,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