More API documentation (Doxygen format) for EC code.

[BearSSL] / inc / bearssl_ssl.h

diff --git a/inc/bearssl_ssl.h b/inc/bearssl_ssl.h
index 24d773c..0876ff9 100644 (file)
--- a/inc/bearssl_ssl.h
+++ b/inc/bearssl_ssl.h
@@ -544,13 +544,6 @@ typedef struct {
         */
        unsigned char client_random[32];
        unsigned char server_random[32];
         */
        unsigned char client_random[32];
        unsigned char server_random[32];

-       /* obsolete
-       unsigned char session_id[32];
-       unsigned char session_id_len;
-       uint16_t version;
-       uint16_t cipher_suite;
-       unsigned char master_secret[48];
-       */

        br_ssl_session_parameters session;
 
        /*
        br_ssl_session_parameters session;
 
        /*


@@ -574,6 +567,11 @@ typedef struct {
        unsigned char reneg;
        unsigned char saved_finished[24];
 
        unsigned char reneg;
        unsigned char saved_finished[24];
 

+       /*
+        * Behavioural flags.
+        */
+       uint32_t flags;
+

        /*
         * Context variables for the handshake processor.
         * The 'pad' must be large enough to accommodate an
        /*
         * Context variables for the handshake processor.
         * The 'pad' must be large enough to accommodate an


@@ -653,6 +651,45 @@ typedef struct {
 
 } br_ssl_engine_context;
 
 
 } br_ssl_engine_context;
 

+/*
+ * Get currently defined engine behavioural flags.
+ */
+static inline uint32_t
+br_ssl_engine_get_flags(br_ssl_engine_context *cc)
+{
+       return cc->flags;
+}
+
+/*
+ * Set all engine flags. Flags which are not in the 'flags' argument
+ * are cleared.
+ */
+static inline void
+br_ssl_engine_set_all_flags(br_ssl_engine_context *cc, uint32_t flags)
+{
+       cc->flags = flags;
+}
+
+/*
+ * Add some engine flags. The provided flags are set in the engine context,
+ * but other flags are untouched.
+ */
+static inline void
+br_ssl_engine_add_flags(br_ssl_engine_context *cc, uint32_t flags)
+{
+       cc->flags |= flags;
+}
+
+/*
+ * Remove some engine flags. The provided flags are cleared from the
+ * engine context, but other flags are untouched.
+ */
+static inline void
+br_ssl_engine_remove_flags(br_ssl_engine_context *cc, uint32_t flags)
+{
+       cc->flags &= ~flags;
+}
+

 /*
  * Set the minimum and maximum supported protocol versions.
  */
 /*
  * Set the minimum and maximum supported protocol versions.
  */


@@ -882,6 +919,31 @@ br_ssl_engine_get_server_name(br_ssl_engine_context *cc)
        return cc->server_name;
 }
 
        return cc->server_name;
 }
 

+/*
+ * Get a copy of the session parameters. The session parameters are
+ * filled during the handshake, so this function shall not be called
+ * before completion of the handshake.
+ */
+static inline void
+br_ssl_engine_get_session_parameters(const br_ssl_engine_context *cc,
+       br_ssl_session_parameters *pp)
+{
+       memcpy(pp, &cc->session, sizeof *pp);
+}
+
+/*
+ * Set the session parameters to the provided value. This function
+ * is meant to be used in the client, before doing a new handshake;
+ * a session resumption will be attempted with these parameters. In
+ * the server, this function has no effect.
+ */
+static inline void
+br_ssl_engine_set_session_parameters(br_ssl_engine_context *cc,
+       const br_ssl_session_parameters *pp)
+{
+       memcpy(&cc->session, pp, sizeof *pp);
+}
+

 /*
  * An SSL engine (client or server) has, at any time, a state which is
  * the combination of zero, one or more of these flags:
 /*
  * An SSL engine (client or server) has, at any time, a state which is
  * the combination of zero, one or more of these flags:


@@ -1020,6 +1082,14 @@ typedef struct {
         */
        br_ssl_engine_context eng;
 
         */
        br_ssl_engine_context eng;
 

+       /*
+        * Minimum ClientHello length; padding with an extension (RFC
+        * 7685) is added if necessary to match at least that length.
+        * Such padding is nominally unnecessary, but it has been used
+        * to work around some server implementation bugs.
+        */
+       uint16_t min_clienthello_len;
+

        /*
         * Implementations.
         */
        /*
         * Implementations.
         */


@@ -1081,6 +1151,15 @@ br_ssl_client_set_ecdsa(br_ssl_client_context *cc, br_ecdsa_vrfy iecdsa)
        cc->iecdsa = iecdsa;
 }
 
        cc->iecdsa = iecdsa;
 }
 

+/*
+ * Set the minimum ClientHello length (RFC 7685 padding).
+ */
+static inline void
+br_ssl_client_set_min_clienthello_len(br_ssl_client_context *cc, uint16_t len)
+{
+       cc->min_clienthello_len = len;
+}
+

 /*
  * Prepare or reset a client context for connecting with a server of
  * name 'server_name'. The 'server_name' parameter is used to fill the
 /*
  * Prepare or reset a client context for connecting with a server of
  * name 'server_name'. The 'server_name' parameter is used to fill the


@@ -1353,11 +1432,6 @@ struct br_ssl_server_context_ {
         */
        br_ssl_engine_context eng;
 
         */
        br_ssl_engine_context eng;
 

-       /*
-        * Flags.
-        */
-       uint32_t flags;
-

        /*
         * Maximum version from the client.
         */
        /*
         * Maximum version from the client.
         */


@@ -1420,51 +1494,19 @@ struct br_ssl_server_context_ {
         */
 };
 
         */
 };
 

-/*
- * Get currently defined server behavioural flags.
- */
-static inline uint32_t
-br_ssl_server_get_flags(br_ssl_server_context *cc)
-{
-       return cc->flags;
-}
-
-/*
- * Set all server flags. Flags which are not in the 'flags' argument
- * are cleared.
- */
-static inline void
-br_ssl_server_set_all_flags(br_ssl_server_context *cc, uint32_t flags)
-{
-       cc->flags = flags;
-}
-
-/*
- * Add some server flags. The provided flags are set in the server context,
- * but other flags are untouched.
- */
-static inline void
-br_ssl_server_add_flags(br_ssl_server_context *cc, uint32_t flags)
-{
-       cc->flags |= flags;
-}
-
-/*
- * Remove some server flags. The provided flags are cleared from the
- * server context, but other flags are untouched.
- */
-static inline void
-br_ssl_server_remove_flags(br_ssl_server_context *cc, uint32_t flags)
-{
-       cc->flags &= ~flags;
-}
-

 /*
  * If this flag is set, then the server will enforce its own cipher suite
  * preference order; otherwise, it follows the client preferences.
  */
 #define BR_OPT_ENFORCE_SERVER_PREFERENCES      ((uint32_t)1 << 0)
 
 /*
  * If this flag is set, then the server will enforce its own cipher suite
  * preference order; otherwise, it follows the client preferences.
  */
 #define BR_OPT_ENFORCE_SERVER_PREFERENCES      ((uint32_t)1 << 0)
 

+/*
+ * If this flag is set, then renegotiations are rejected unconditionally:
+ * they won't be honoured if asked for programmatically, and requests from
+ * the peer are rejected.
+ */
+#define BR_OPT_NO_RENEGOTIATION                ((uint32_t)1 << 1)
+

 /*
  * Each br_ssl_server_init_xxx() function sets the list of supported
  * cipher suites and used implementations, as specified by the profile
 /*
  * Each br_ssl_server_init_xxx() function sets the list of supported
  * cipher suites and used implementations, as specified by the profile