Implement custom extensions.
This change mirrors upstream's custom extension API because we have some
internal users that depend on it.
Change-Id: I408e442de0a55df7b05c872c953ff048cd406513
Reviewed-on: https://boringssl-review.googlesource.com/5471
Reviewed-by: Adam Langley <agl@google.com>
diff --git a/include/openssl/base.h b/include/openssl/base.h
index 84400ae..4618ed2 100644
--- a/include/openssl/base.h
+++ b/include/openssl/base.h
@@ -214,6 +214,7 @@
typedef struct sha512_state_st SHA512_CTX;
typedef struct sha_state_st SHA_CTX;
typedef struct ssl_ctx_st SSL_CTX;
+typedef struct ssl_custom_extension SSL_CUSTOM_EXTENSION;
typedef struct ssl_st SSL;
typedef struct st_ERR_FNS ERR_FNS;
typedef struct v3_ext_ctx X509V3_CTX;
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index 656a901..02445bf 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -768,6 +768,92 @@
size_t *out_len, size_t max_out);
+/* Custom extensions.
+ *
+ * The custom extension functions allow TLS extensions to be added to
+ * ClientHello and ServerHello messages. */
+
+/* SSL_custom_ext_add_cb is a callback function that is called when the
+ * ClientHello (for clients) or ServerHello (for servers) is constructed. In
+ * the case of a server, this callback will only be called for a given
+ * extension if the ClientHello contained that extension – it's not possible to
+ * inject extensions into a ServerHello that the client didn't request.
+ *
+ * When called, |extension_value| will contain the extension number that is
+ * being considered for addition (so that a single callback can handle multiple
+ * extensions). If the callback wishes to include the extension, it must set
+ * |*out| to point to |*out_len| bytes of extension contents and return one. In
+ * this case, the corresponding |SSL_custom_ext_free_cb| callback will later be
+ * called with the value of |*out| once that data has been copied.
+ *
+ * If the callback does not wish to add an extension it must return zero.
+ *
+ * Alternatively, the callback can abort the connection by setting
+ * |*out_alert_value| to a TLS alert number and returning -1. */
+typedef int (*SSL_custom_ext_add_cb)(SSL *ssl, unsigned extension_value,
+ const uint8_t **out, size_t *out_len,
+ int *out_alert_value, void *add_arg);
+
+/* SSL_custom_ext_free_cb is a callback function that is called by OpenSSL iff
+ * an |SSL_custom_ext_add_cb| callback previously returned one. In that case,
+ * this callback is called and passed the |out| pointer that was returned by
+ * the add callback. This is to free any dynamically allocated data created by
+ * the add callback. */
+typedef void (*SSL_custom_ext_free_cb)(SSL *ssl, unsigned extension_value,
+ const uint8_t *out, void *add_arg);
+
+/* SSL_custom_ext_parse_cb is a callback function that is called by OpenSSL to
+ * parse an extension from the peer: that is from the ServerHello for a client
+ * and from the ClientHello for a server.
+ *
+ * When called, |extension_value| will contain the extension number and the
+ * contents of the extension are |contents_len| bytes at |contents|.
+ *
+ * The callback must return one to continue the handshake. Otherwise, if it
+ * returns zero, a fatal alert with value |*out_alert_value| is sent and the
+ * handshake is aborted. */
+typedef int (*SSL_custom_ext_parse_cb)(SSL *ssl, unsigned extension_value,
+ const uint8_t *contents,
+ size_t contents_len,
+ int *out_alert_value, void *parse_arg);
+
+/* SSL_extension_supported returns one iff OpenSSL internally handles
+ * extensions of type |extension_value|. This can be used to avoid registering
+ * custom extension handlers for extensions that a future version of OpenSSL
+ * may handle internally. */
+OPENSSL_EXPORT int SSL_extension_supported(unsigned extension_value);
+
+/* SSL_CTX_add_client_custom_ext registers callback functions for handling
+ * custom TLS extensions for client connections.
+ *
+ * If |add_cb| is NULL then an empty extension will be added in each
+ * ClientHello. Otherwise, see the comment for |SSL_custom_ext_add_cb| about
+ * this callback.
+ *
+ * The |free_cb| may be NULL if |add_cb| doesn't dynamically allocate data that
+ * needs to be freed.
+ *
+ * It returns one on success or zero on error. It's always an error to register
+ * callbacks for the same extension twice, or to register callbacks for an
+ * extension that OpenSSL handles internally. See |SSL_extension_supported| to
+ * discover, at runtime, which extensions OpenSSL handles internally. */
+OPENSSL_EXPORT int SSL_CTX_add_client_custom_ext(
+ SSL_CTX *ctx, unsigned extension_value, SSL_custom_ext_add_cb add_cb,
+ SSL_custom_ext_free_cb free_cb, void *add_arg,
+ SSL_custom_ext_parse_cb parse_cb, void *parse_arg);
+
+/* SSL_CTX_add_server_custom_ext is the same as
+ * |SSL_CTX_add_client_custom_ext|, but for server connections.
+ *
+ * Unlike on the client side, if |add_cb| is NULL no extension will be added.
+ * The |add_cb|, if any, will only be called if the ClientHello contained a
+ * matching extension. */
+OPENSSL_EXPORT int SSL_CTX_add_server_custom_ext(
+ SSL_CTX *ctx, unsigned extension_value, SSL_custom_ext_add_cb add_cb,
+ SSL_custom_ext_free_cb free_cb, void *add_arg,
+ SSL_custom_ext_parse_cb parse_cb, void *parse_arg);
+
+
/* Session tickets. */
/* SSL_CTX_get_tlsext_ticket_keys writes |ctx|'s session ticket key material to
@@ -1221,6 +1307,10 @@
CRYPTO_EX_DATA ex_data;
+ /* custom_*_extensions stores any callback sets for custom extensions. Note
+ * that these pointers will be NULL if the stack would otherwise be empty. */
+ STACK_OF(SSL_CUSTOM_EXTENSION) *client_custom_extensions;
+ STACK_OF(SSL_CUSTOM_EXTENSION) *server_custom_extensions;
/* Default values used when no per-SSL value is defined follow */
@@ -2945,6 +3035,8 @@
#define SSL_R_ERROR_ADDING_EXTENSION 281
#define SSL_R_ERROR_PARSING_EXTENSION 282
#define SSL_R_MISSING_EXTENSION 283
+#define SSL_R_CUSTOM_EXTENSION_CONTENTS_TOO_LARGE 284
+#define SSL_R_CUSTOM_EXTENSION_ERROR 285
#define SSL_R_SSLV3_ALERT_CLOSE_NOTIFY 1000
#define SSL_R_SSLV3_ALERT_UNEXPECTED_MESSAGE 1010
#define SSL_R_SSLV3_ALERT_BAD_RECORD_MAC 1020
diff --git a/include/openssl/ssl3.h b/include/openssl/ssl3.h
index 541b039..faf69ab 100644
--- a/include/openssl/ssl3.h
+++ b/include/openssl/ssl3.h
@@ -453,6 +453,16 @@
uint32_t received;
} extensions;
+ union {
+ /* sent is a bitset where the bits correspond to elements of
+ * |client_custom_extensions| in the |SSL_CTX|. Each bit is set if that
+ * extension was sent in a ClientHello. It's not used by servers. */
+ uint16_t sent;
+ /* received is a bitset, like |sent|, but is used by servers to record
+ * which custom extensions were received from a client. The bits here
+ * correspond to |server_custom_extensions|. */
+ uint16_t received;
+ } custom_extensions;
/* SNI extension */
diff --git a/include/openssl/stack.h b/include/openssl/stack.h
index 5f9b683..36a0397 100644
--- a/include/openssl/stack.h
+++ b/include/openssl/stack.h
@@ -147,6 +147,7 @@
* STACK_OF:POLICY_MAPPING
* STACK_OF:RSA_additional_prime
* STACK_OF:SSL_COMP
+ * STACK_OF:SSL_CUSTOM_EXTENSION
* STACK_OF:STACK_OF_X509_NAME_ENTRY
* STACK_OF:SXNETID
* STACK_OF:X509
diff --git a/include/openssl/stack_macros.h b/include/openssl/stack_macros.h
index a4dc926..08097af 100644
--- a/include/openssl/stack_macros.h
+++ b/include/openssl/stack_macros.h
@@ -2106,6 +2106,99 @@
CHECKED_CAST(void *(*)(void *), SSL_COMP *(*)(SSL_COMP *), copy_func), \
CHECKED_CAST(void (*)(void *), void (*)(SSL_COMP *), free_func)))
+/* SSL_CUSTOM_EXTENSION */
+#define sk_SSL_CUSTOM_EXTENSION_new(comp) \
+ ((STACK_OF(SSL_CUSTOM_EXTENSION) *)sk_new(CHECKED_CAST( \
+ stack_cmp_func, \
+ int (*)(const SSL_CUSTOM_EXTENSION **a, const SSL_CUSTOM_EXTENSION **b), \
+ comp)))
+
+#define sk_SSL_CUSTOM_EXTENSION_new_null() \
+ ((STACK_OF(SSL_CUSTOM_EXTENSION) *)sk_new_null())
+
+#define sk_SSL_CUSTOM_EXTENSION_num(sk) \
+ sk_num(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk))
+
+#define sk_SSL_CUSTOM_EXTENSION_zero(sk) \
+ sk_zero(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk));
+
+#define sk_SSL_CUSTOM_EXTENSION_value(sk, i) \
+ ((SSL_CUSTOM_EXTENSION *)sk_value( \
+ CHECKED_CAST(_STACK *, const STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ (i)))
+
+#define sk_SSL_CUSTOM_EXTENSION_set(sk, i, p) \
+ ((SSL_CUSTOM_EXTENSION *)sk_set( \
+ CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), (i), \
+ CHECKED_CAST(void *, SSL_CUSTOM_EXTENSION *, p)))
+
+#define sk_SSL_CUSTOM_EXTENSION_free(sk) \
+ sk_free(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk))
+
+#define sk_SSL_CUSTOM_EXTENSION_pop_free(sk, free_func) \
+ sk_pop_free(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ CHECKED_CAST(void (*)(void *), void (*)(SSL_CUSTOM_EXTENSION *), \
+ free_func))
+
+#define sk_SSL_CUSTOM_EXTENSION_insert(sk, p, where) \
+ sk_insert(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ CHECKED_CAST(void *, SSL_CUSTOM_EXTENSION *, p), (where))
+
+#define sk_SSL_CUSTOM_EXTENSION_delete(sk, where) \
+ ((SSL_CUSTOM_EXTENSION *)sk_delete( \
+ CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), (where)))
+
+#define sk_SSL_CUSTOM_EXTENSION_delete_ptr(sk, p) \
+ ((SSL_CUSTOM_EXTENSION *)sk_delete_ptr( \
+ CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ CHECKED_CAST(void *, SSL_CUSTOM_EXTENSION *, p)))
+
+#define sk_SSL_CUSTOM_EXTENSION_find(sk, out_index, p) \
+ sk_find(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ (out_index), CHECKED_CAST(void *, SSL_CUSTOM_EXTENSION *, p))
+
+#define sk_SSL_CUSTOM_EXTENSION_shift(sk) \
+ ((SSL_CUSTOM_EXTENSION *)sk_shift( \
+ CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk)))
+
+#define sk_SSL_CUSTOM_EXTENSION_push(sk, p) \
+ sk_push(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ CHECKED_CAST(void *, SSL_CUSTOM_EXTENSION *, p))
+
+#define sk_SSL_CUSTOM_EXTENSION_pop(sk) \
+ ((SSL_CUSTOM_EXTENSION *)sk_pop( \
+ CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk)))
+
+#define sk_SSL_CUSTOM_EXTENSION_dup(sk) \
+ ((STACK_OF(SSL_CUSTOM_EXTENSION) *)sk_dup( \
+ CHECKED_CAST(_STACK *, const STACK_OF(SSL_CUSTOM_EXTENSION) *, sk)))
+
+#define sk_SSL_CUSTOM_EXTENSION_sort(sk) \
+ sk_sort(CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk))
+
+#define sk_SSL_CUSTOM_EXTENSION_is_sorted(sk) \
+ sk_is_sorted( \
+ CHECKED_CAST(_STACK *, const STACK_OF(SSL_CUSTOM_EXTENSION) *, sk))
+
+#define sk_SSL_CUSTOM_EXTENSION_set_cmp_func(sk, comp) \
+ ((int (*)(const SSL_CUSTOM_EXTENSION **a, const SSL_CUSTOM_EXTENSION **b)) \
+ sk_set_cmp_func( \
+ CHECKED_CAST(_STACK *, STACK_OF(SSL_CUSTOM_EXTENSION) *, sk), \
+ CHECKED_CAST(stack_cmp_func, \
+ int (*)(const SSL_CUSTOM_EXTENSION **a, \
+ const SSL_CUSTOM_EXTENSION **b), \
+ comp)))
+
+#define sk_SSL_CUSTOM_EXTENSION_deep_copy(sk, copy_func, free_func) \
+ ((STACK_OF(SSL_CUSTOM_EXTENSION) *)sk_deep_copy( \
+ CHECKED_CAST(const _STACK *, const STACK_OF(SSL_CUSTOM_EXTENSION) *, \
+ sk), \
+ CHECKED_CAST(void *(*)(void *), \
+ SSL_CUSTOM_EXTENSION *(*)(SSL_CUSTOM_EXTENSION *), \
+ copy_func), \
+ CHECKED_CAST(void (*)(void *), void (*)(SSL_CUSTOM_EXTENSION *), \
+ free_func)))
+
/* STACK_OF_X509_NAME_ENTRY */
#define sk_STACK_OF_X509_NAME_ENTRY_new(comp) \
((STACK_OF(STACK_OF_X509_NAME_ENTRY) *)sk_new(CHECKED_CAST( \
