Made headers compatible with C++.

[BearSSL] / inc / bearssl_ssl.h

diff --git a/inc/bearssl_ssl.h b/inc/bearssl_ssl.h
index 3ff29f6..21d162b 100644 (file)
--- a/inc/bearssl_ssl.h
+++ b/inc/bearssl_ssl.h
@@ -35,6 +35,10 @@
 #include "bearssl_rand.h"
 #include "bearssl_x509.h"
 
 #include "bearssl_rand.h"
 #include "bearssl_x509.h"
 

+#ifdef __cplusplus
+extern "C" {
+#endif
+

 /** \file bearssl_ssl.h
  *
  * # SSL
 /** \file bearssl_ssl.h
  *
  * # SSL


@@ -1321,6 +1325,18 @@ br_ssl_engine_set_aes_cbc(br_ssl_engine_context *cc,
        cc->iaes_cbcdec = impl_dec;
 }
 
        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.
  *
 /**
  * \brief Set the AES/CTR implementation.
  *


@@ -1334,6 +1350,18 @@ br_ssl_engine_set_aes_ctr(br_ssl_engine_context *cc,
        cc->iaes_ctr = impl;
 }
 
        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.
  *
 /**
  * \brief Set the DES/CBC implementations.
  *


@@ -1350,6 +1378,18 @@ br_ssl_engine_set_des_cbc(br_ssl_engine_context *cc,
        cc->ides_cbcdec = impl_dec;
 }
 
        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).
  *
 /**
  * \brief Set the GHASH implementation (used in GCM mode).
  *


@@ -1388,6 +1428,18 @@ br_ssl_engine_set_poly1305(br_ssl_engine_context *cc,
        cc->ipoly = 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 record encryption and decryption engines for CBC + HMAC.
  *
 /**
  * \brief Set the record encryption and decryption engines for CBC + HMAC.
  *


@@ -1452,6 +1504,29 @@ br_ssl_engine_set_ec(br_ssl_engine_context *cc, const br_ec_impl *iec)
        cc->iec = 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.
  *
 /**
  * \brief Set the RSA signature verification implementation.
  *


@@ -1469,6 +1544,29 @@ br_ssl_engine_set_rsavrfy(br_ssl_engine_context *cc, br_rsa_pkcs1_vrfy irsavrfy)
        cc->irsavrfy = 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).
  *
 /*
  * \brief Set the ECDSA implementation (signature verification).
  *


@@ -1490,6 +1588,31 @@ br_ssl_engine_set_ecdsa(br_ssl_engine_context *cc, br_ecdsa_vrfy iecdsa)
        cc->iecdsa = 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.
  *
 /**
  * \brief Set the I/O buffer for the SSL engine.
  *


@@ -1657,6 +1780,25 @@ br_ssl_engine_set_session_parameters(br_ssl_engine_context *cc,
        memcpy(&cc->session, pp, sizeof *pp);
 }
 
        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.
  *
 /**
  * \brief Get the current engine state.
  *


@@ -2136,12 +2278,13 @@ struct br_ssl_client_certificate_class_ {
         *     structure was set to -1).
         *
         * In that situation, this callback is invoked to compute the
         *     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
         * 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:
         *
         *
         * The callback must uphold the following:
         *


@@ -2158,11 +2301,11 @@ struct br_ssl_client_certificate_class_ {
         *
         * \param pctx   certificate handler context.
         * \param data   server public key point.
         *
         * \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,
         * \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).
 
        /**
         * \brief Perform a signature (client authentication).


@@ -2437,6 +2580,17 @@ br_ssl_client_set_rsapub(br_ssl_client_context *cc, br_rsa_public irsapub)
        cc->irsapub = 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).
  *
 /**
  * \brief Set the minimum ClientHello length (RFC 7685 padding).
  *


@@ -2791,12 +2945,12 @@ struct br_ssl_server_policy_class_ {
         * operation for a key exchange that is not ECDHE. This callback
         * uses the private key.
         *
         * 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`.
         *
         * 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.
         *
         *   - This callback MUST check that the provided length matches
         *     that of the key modulus; it shall report an error otherwise.


@@ -2813,12 +2967,11 @@ struct br_ssl_server_policy_class_ {
         *     in the first 48 bytes of `data` is unimportant (the caller
         *     will use random bytes instead).
         *
         *     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
         * 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.
         *
         *   - If the input array does not have the proper length for
         *     an encoded curve point, then an error (0) shall be reported.


@@ -2837,7 +2990,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,
         * \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).
 
        /**
         * \brief Perform a signature (for a ServerKeyExchange message).


@@ -3146,8 +3299,9 @@ struct br_ssl_server_context_ {
  *      3 = TLS 1.2 with SHA-384
  * -- character 3: encryption
  *      a = AES/CBC
  *      3 = TLS 1.2 with SHA-384
  * -- character 3: encryption
  *      a = AES/CBC

- *      g = AES/GCM

  *      d = 3DES/CBC
  *      d = 3DES/CBC

+ *      g = AES/GCM
+ *      c = ChaCha20+Poly1305

  */
 
 /**
  */
 
 /**


@@ -3915,4 +4069,8 @@ int br_sslio_close(br_sslio_context *cc);
 #define BR_ALERT_UNSUPPORTED_EXTENSION     110
 #define BR_ALERT_NO_APPLICATION_PROTOCOL   120
 
 #define BR_ALERT_UNSUPPORTED_EXTENSION     110
 #define BR_ALERT_NO_APPLICATION_PROTOCOL   120
 

+#ifdef __cplusplus
+}
+#endif
+

 #endif
 #endif