Merge commits '56582094 427bc3cd 0cf2fb91 9c8c4f44 70be3cad f16a709f 464a9115 1d8f3675 afd8b23b 2bca0a5c 2d51a454 4e682626 a0f4644f 145078c4 7b7503da ec98fced 346a053d ' into temp-merge-1269

src/asm/field_10x26_arm.s

@@ -29,6 +29,7 @@ Note:
 	.align	2
 	.global secp256k1_fe_mul_inner
 	.type	secp256k1_fe_mul_inner, %function
+	.hidden secp256k1_fe_mul_inner
 	@ Arguments:
 	@  r0  r      Restrict: can overlap with a, not with b
 	@  r1  a
@@ -516,6 +517,7 @@ secp256k1_fe_mul_inner:
 	.align	2
 	.global secp256k1_fe_sqr_inner
 	.type	secp256k1_fe_sqr_inner, %function
+	.hidden secp256k1_fe_sqr_inner
 	@ Arguments:
 	@  r0  r	 Can overlap with a
 	@  r1  a

src/ecmult_const.h

@@ -18,4 +18,25 @@
  */
 static void secp256k1_ecmult_const(secp256k1_gej *r, const secp256k1_ge *a, const secp256k1_scalar *q, int bits);
 
+/**
+ * Same as secp256k1_ecmult_const, but takes in an x coordinate of the base point
+ * only, specified as fraction n/d (numerator/denominator). Only the x coordinate of the result is
+ * returned.
+ *
+ * If known_on_curve is 0, a verification is performed that n/d is a valid X
+ * coordinate, and 0 is returned if not. Otherwise, 1 is returned.
+ *
+ * d being NULL is interpreted as d=1. If non-NULL, d must not be zero. q must not be zero.
+ *
+ * Constant time in the value of q, but not any other inputs.
+ */
+static int secp256k1_ecmult_const_xonly(
+    secp256k1_fe *r,
+    const secp256k1_fe *n,
+    const secp256k1_fe *d,
+    const secp256k1_scalar *q,
+    int bits,
+    int known_on_curve
+);
+
 #endif /* SECP256K1_ECMULT_CONST_H */

src/ecmult_const_impl.h

@@ -228,4 +228,139 @@ static void secp256k1_ecmult_const(secp256k1_gej *r, const secp256k1_ge *a, cons
     secp256k1_fe_mul(&r->z, &r->z, &Z);
 }
 
+static int secp256k1_ecmult_const_xonly(secp256k1_fe* r, const secp256k1_fe *n, const secp256k1_fe *d, const secp256k1_scalar *q, int bits, int known_on_curve) {
+
+    /* This algorithm is a generalization of Peter Dettman's technique for
+     * avoiding the square root in a random-basepoint x-only multiplication
+     * on a Weierstrass curve:
+     * https://mailarchive.ietf.org/arch/msg/cfrg/7DyYY6gg32wDgHAhgSb6XxMDlJA/
+     *
+     *
+     * === Background: the effective affine technique ===
+     *
+     * Let phi_u be the isomorphism that maps (x, y) on secp256k1 curve y^2 = x^3 + 7 to
+     * x' = u^2*x, y' = u^3*y on curve y'^2 = x'^3 + u^6*7. This new curve has the same order as
+     * the original (it is isomorphic), but moreover, has the same addition/doubling formulas, as
+     * the curve b=7 coefficient does not appear in those formulas (or at least does not appear in
+     * the formulas implemented in this codebase, both affine and Jacobian). See also Example 9.5.2
+     * in https://www.math.auckland.ac.nz/~sgal018/crypto-book/ch9.pdf.
+     *
+     * This means any linear combination of secp256k1 points can be computed by applying phi_u
+     * (with non-zero u) on all input points (including the generator, if used), computing the
+     * linear combination on the isomorphic curve (using the same group laws), and then applying
+     * phi_u^{-1} to get back to secp256k1.
+     *
+     * Switching to Jacobian coordinates, note that phi_u applied to (X, Y, Z) is simply
+     * (X, Y, Z/u). Thus, if we want to compute (X1, Y1, Z) + (X2, Y2, Z), with identical Z
+     * coordinates, we can use phi_Z to transform it to (X1, Y1, 1) + (X2, Y2, 1) on an isomorphic
+     * curve where the affine addition formula can be used instead.
+     * If (X3, Y3, Z3) = (X1, Y1) + (X2, Y2) on that curve, then our answer on secp256k1 is
+     * (X3, Y3, Z3*Z).
+     *
+     * This is the effective affine technique: if we have a linear combination of group elements
+     * to compute, and all those group elements have the same Z coordinate, we can simply pretend
+     * that all those Z coordinates are 1, perform the computation that way, and then multiply the
+     * original Z coordinate back in.
+     *
+     * The technique works on any a=0 short Weierstrass curve. It is possible to generalize it to
+     * other curves too, but there the isomorphic curves will have different 'a' coefficients,
+     * which typically does affect the group laws.
+     *
+     *
+     * === Avoiding the square root for x-only point multiplication ===
+     *
+     * In this function, we want to compute the X coordinate of q*(n/d, y), for
+     * y = sqrt((n/d)^3 + 7). Its negation would also be a valid Y coordinate, but by convention
+     * we pick whatever sqrt returns (which we assume to be a deterministic function).
+     *
+     * Let g = y^2*d^3 = n^3 + 7*d^3. This also means y = sqrt(g/d^3).
+     * Further let v = sqrt(d*g), which must exist as d*g = y^2*d^4 = (y*d^2)^2.
+     *
+     * The input point (n/d, y) also has Jacobian coordinates:
+     *
+     *     (n/d, y, 1)
+     *   = (n/d * v^2, y * v^3, v)
+     *   = (n/d * d*g, y * sqrt(d^3*g^3), v)
+     *   = (n/d * d*g, sqrt(y^2 * d^3*g^3), v)
+     *   = (n*g, sqrt(g/d^3 * d^3*g^3), v)
+     *   = (n*g, sqrt(g^4), v)
+     *   = (n*g, g^2, v)
+     *
+     * It is easy to verify that both (n*g, g^2, v) and its negation (n*g, -g^2, v) have affine X
+     * coordinate n/d, and this holds even when the square root function doesn't have a
+     * determinstic sign. We choose the (n*g, g^2, v) version.
+     *
+     * Now switch to the effective affine curve using phi_v, where the input point has coordinates
+     * (n*g, g^2). Compute (X, Y, Z) = q * (n*g, g^2) there.
+     *
+     * Back on secp256k1, that means q * (n*g, g^2, v) = (X, Y, v*Z). This last point has affine X
+     * coordinate X / (v^2*Z^2) = X / (d*g*Z^2). Determining the affine Y coordinate would involve
+     * a square root, but as long as we only care about the resulting X coordinate, no square root
+     * is needed anywhere in this computation.
+     */
+
+    secp256k1_fe g, i;
+    secp256k1_ge p;
+    secp256k1_gej rj;
+
+    /* Compute g = (n^3 + B*d^3). */
+    secp256k1_fe_sqr(&g, n);
+    secp256k1_fe_mul(&g, &g, n);
+    if (d) {
+        secp256k1_fe b;
+#ifdef VERIFY
+        VERIFY_CHECK(!secp256k1_fe_normalizes_to_zero(d));
+#endif
+        secp256k1_fe_sqr(&b, d);
+        VERIFY_CHECK(SECP256K1_B <= 8); /* magnitude of b will be <= 8 after the next call */
+        secp256k1_fe_mul_int(&b, SECP256K1_B);
+        secp256k1_fe_mul(&b, &b, d);
+        secp256k1_fe_add(&g, &b);
+        if (!known_on_curve) {
+            /* We need to determine whether (n/d)^3 + 7 is square.
+             *
+             *     is_square((n/d)^3 + 7)
+             * <=> is_square(((n/d)^3 + 7) * d^4)
+             * <=> is_square((n^3 + 7*d^3) * d)
+             * <=> is_square(g * d)
+             */
+            secp256k1_fe c;
+            secp256k1_fe_mul(&c, &g, d);
+            if (!secp256k1_fe_is_square_var(&c)) return 0;
+        }
+    } else {
+        secp256k1_fe_add_int(&g, SECP256K1_B);
+        if (!known_on_curve) {
+            /* g at this point equals x^3 + 7. Test if it is square. */
+            if (!secp256k1_fe_is_square_var(&g)) return 0;
+        }
+    }
+
+    /* Compute base point P = (n*g, g^2), the effective affine version of (n*g, g^2, v), which has
+     * corresponding affine X coordinate n/d. */
+    secp256k1_fe_mul(&p.x, &g, n);
+    secp256k1_fe_sqr(&p.y, &g);
+    p.infinity = 0;
+
+    /* Perform x-only EC multiplication of P with q. */
+#ifdef VERIFY
+    VERIFY_CHECK(!secp256k1_scalar_is_zero(q));
+#endif
+    secp256k1_ecmult_const(&rj, &p, q, bits);
+#ifdef VERIFY
+    VERIFY_CHECK(!secp256k1_gej_is_infinity(&rj));
+#endif
+
+    /* The resulting (X, Y, Z) point on the effective-affine isomorphic curve corresponds to
+     * (X, Y, Z*v) on the secp256k1 curve. The affine version of that has X coordinate
+     * (X / (Z^2*d*g)). */
+    secp256k1_fe_sqr(&i, &rj.z);
+    secp256k1_fe_mul(&i, &i, &g);
+    if (d) secp256k1_fe_mul(&i, &i, d);
+    secp256k1_fe_inv(&i, &i);
+    secp256k1_fe_mul(r, &rj.x, &i);
+
+    return 1;
+}
+
 #endif /* SECP256K1_ECMULT_CONST_IMPL_H */

src/ecmult_impl.h

@@ -97,7 +97,7 @@ static void secp256k1_ecmult_odd_multiples_table(int n, secp256k1_ge *pre_a, sec
     secp256k1_gej_set_ge(&ai, &pre_a[0]);
     ai.z = a->z;
 
-    /* pre_a[0] is the point (a.x*C^2, a.y*C^3, a.z*C) which is equvalent to a.
+    /* pre_a[0] is the point (a.x*C^2, a.y*C^3, a.z*C) which is equivalent to a.
      * Set zr[0] to C, which is the ratio between the omitted z(pre_a[0]) value and a.z.
      */
     zr[0] = d.z;
@@ -114,13 +114,16 @@ static void secp256k1_ecmult_odd_multiples_table(int n, secp256k1_ge *pre_a, sec
     secp256k1_fe_mul(z, &ai.z, &d.z);
 }
 
-#define SECP256K1_ECMULT_TABLE_VERIFY(n,w) \
-    VERIFY_CHECK(((n) & 1) == 1); \
-    VERIFY_CHECK((n) >= -((1 << ((w)-1)) - 1)); \
+SECP256K1_INLINE static void secp256k1_ecmult_table_verify(int n, int w) {
+    (void)n;
+    (void)w;
+    VERIFY_CHECK(((n) & 1) == 1);
+    VERIFY_CHECK((n) >= -((1 << ((w)-1)) - 1));
     VERIFY_CHECK((n) <=  ((1 << ((w)-1)) - 1));
+}
 
 SECP256K1_INLINE static void secp256k1_ecmult_table_get_ge(secp256k1_ge *r, const secp256k1_ge *pre, int n, int w) {
-    SECP256K1_ECMULT_TABLE_VERIFY(n,w)
+    secp256k1_ecmult_table_verify(n,w);
     if (n > 0) {
         *r = pre[(n-1)/2];
     } else {
@@ -130,7 +133,7 @@ SECP256K1_INLINE static void secp256k1_ecmult_table_get_ge(secp256k1_ge *r, cons
 }
 
 SECP256K1_INLINE static void secp256k1_ecmult_table_get_ge_lambda(secp256k1_ge *r, const secp256k1_ge *pre, const secp256k1_fe *x, int n, int w) {
-    SECP256K1_ECMULT_TABLE_VERIFY(n,w)
+    secp256k1_ecmult_table_verify(n,w);
     if (n > 0) {
         secp256k1_ge_set_xy(r, &x[(n-1)/2], &pre[(n-1)/2].y);
     } else {
@@ -140,7 +143,7 @@ SECP256K1_INLINE static void secp256k1_ecmult_table_get_ge_lambda(secp256k1_ge *
 }
 
 SECP256K1_INLINE static void secp256k1_ecmult_table_get_ge_storage(secp256k1_ge *r, const secp256k1_ge_storage *pre, int n, int w) {
-    SECP256K1_ECMULT_TABLE_VERIFY(n,w)
+    secp256k1_ecmult_table_verify(n,w);
     if (n > 0) {
         secp256k1_ge_from_storage(r, &pre[(n-1)/2]);
     } else {

src/field_10x26_impl.h

@@ -1365,7 +1365,9 @@ static void secp256k1_fe_inv(secp256k1_fe *r, const secp256k1_fe *x) {
     secp256k1_modinv32(&s, &secp256k1_const_modinfo_fe);
     secp256k1_fe_from_signed30(r, &s);
 
+#ifdef VERIFY
     VERIFY_CHECK(secp256k1_fe_normalizes_to_zero(r) == secp256k1_fe_normalizes_to_zero(&tmp));
+#endif
 }
 
 static void secp256k1_fe_inv_var(secp256k1_fe *r, const secp256k1_fe *x) {
@@ -1378,7 +1380,9 @@ static void secp256k1_fe_inv_var(secp256k1_fe *r, const secp256k1_fe *x) {
     secp256k1_modinv32_var(&s, &secp256k1_const_modinfo_fe);
     secp256k1_fe_from_signed30(r, &s);
 
+#ifdef VERIFY
     VERIFY_CHECK(secp256k1_fe_normalizes_to_zero(r) == secp256k1_fe_normalizes_to_zero(&tmp));
+#endif
 }
 
 static int secp256k1_fe_is_square_var(const secp256k1_fe *x) {

src/int128_struct_impl.h

@@ -193,7 +193,7 @@ static SECP256K1_INLINE int secp256k1_i128_check_pow2(const secp256k1_int128 *r,
     VERIFY_CHECK(n < 127);
     VERIFY_CHECK(sign == 1 || sign == -1);
     return n >= 64 ? r->hi == (uint64_t)sign << (n - 64) && r->lo == 0
-                   : r->hi == (uint64_t)((sign - 1) >> 1) && r->lo == (uint64_t)sign << n;
+                   : r->hi == (uint64_t)(sign >> 1) && r->lo == (uint64_t)sign << n;
 }
 
 #endif

src/modinv32_impl.h

@@ -235,7 +235,7 @@ static int32_t secp256k1_modinv32_divsteps_30(int32_t zeta, uint32_t f0, uint32_
     return zeta;
 }
 
-/* inv256[i] = -(2*i+1)^-1 (mod 256) */
+/* secp256k1_modinv32_inv256[i] = -(2*i+1)^-1 (mod 256) */
 static const uint8_t secp256k1_modinv32_inv256[128] = {
     0xFF, 0x55, 0x33, 0x49, 0xC7, 0x5D, 0x3B, 0x11, 0x0F, 0xE5, 0xC3, 0x59,
     0xD7, 0xED, 0xCB, 0x21, 0x1F, 0x75, 0x53, 0x69, 0xE7, 0x7D, 0x5B, 0x31,

src/tests.c

@@ -4728,6 +4728,68 @@ static void ecmult_const_mult_zero_one(void) {
     ge_equals_ge(&res2, &point);
 }
 
+static void ecmult_const_mult_xonly(void) {
+    int i;
+
+    /* Test correspondence between secp256k1_ecmult_const and secp256k1_ecmult_const_xonly. */
+    for (i = 0; i < 2*COUNT; ++i) {
+        secp256k1_ge base;
+        secp256k1_gej basej, resj;
+        secp256k1_fe n, d, resx, v;
+        secp256k1_scalar q;
+        int res;
+        /* Random base point. */
+        random_group_element_test(&base);
+        /* Random scalar to multiply it with. */
+        random_scalar_order_test(&q);
+        /* If i is odd, n=d*base.x for random non-zero d */
+        if (i & 1) {
+            do {
+                random_field_element_test(&d);
+            } while (secp256k1_fe_normalizes_to_zero_var(&d));
+            secp256k1_fe_mul(&n, &base.x, &d);
+        } else {
+            n = base.x;
+        }
+        /* Perform x-only multiplication. */
+        res = secp256k1_ecmult_const_xonly(&resx, &n, (i & 1) ? &d : NULL, &q, 256, i & 2);
+        CHECK(res);
+        /* Perform normal multiplication. */
+        secp256k1_gej_set_ge(&basej, &base);
+        secp256k1_ecmult(&resj, &basej, &q, NULL);
+        /* Check that resj's X coordinate corresponds with resx. */
+        secp256k1_fe_sqr(&v, &resj.z);
+        secp256k1_fe_mul(&v, &v, &resx);
+        CHECK(check_fe_equal(&v, &resj.x));
+    }
+
+    /* Test that secp256k1_ecmult_const_xonly correctly rejects X coordinates not on curve. */
+    for (i = 0; i < 2*COUNT; ++i) {
+        secp256k1_fe x, n, d, c, r;
+        int res;
+        secp256k1_scalar q;
+        random_scalar_order_test(&q);
+        /* Generate random X coordinate not on the curve. */
+        do {
+            random_field_element_test(&x);
+            secp256k1_fe_sqr(&c, &x);
+            secp256k1_fe_mul(&c, &c, &x);
+            secp256k1_fe_add(&c, &secp256k1_fe_const_b);
+        } while (secp256k1_fe_is_square_var(&c));
+        /* If i is odd, n=d*x for random non-zero d. */
+        if (i & 1) {
+            do {
+                random_field_element_test(&d);
+            } while (secp256k1_fe_normalizes_to_zero_var(&d));
+            secp256k1_fe_mul(&n, &x, &d);
+        } else {
+            n = x;
+        }
+        res = secp256k1_ecmult_const_xonly(&r, &n, (i & 1) ? &d : NULL, &q, 256, 0);
+        CHECK(res == 0);
+    }
+}
+
 static void ecmult_const_chain_multiply(void) {
     /* Check known result (randomly generated test problem from sage) */
     const secp256k1_scalar scalar = SECP256K1_SCALAR_CONST(
@@ -4759,6 +4821,7 @@ static void run_ecmult_const_tests(void) {
     ecmult_const_random_mult();
     ecmult_const_commutativity();
     ecmult_const_chain_multiply();
+    ecmult_const_mult_xonly();
 }
 
 typedef struct {
@@ -7582,6 +7645,44 @@ static void run_ecdsa_edge_cases(void) {
     test_ecdsa_edge_cases();
 }
 
+/** Wycheproof tests
+
+The tests check for known attacks (range checks in (r,s), arithmetic errors, malleability).
+*/
+static void test_ecdsa_wycheproof(void) {
+    #include "wycheproof/ecdsa_secp256k1_sha256_bitcoin_test.h"
+
+    int t;
+    for (t = 0; t < SECP256K1_ECDSA_WYCHEPROOF_NUMBER_TESTVECTORS; t++) {
+        secp256k1_ecdsa_signature signature;
+        secp256k1_sha256 hasher;
+        secp256k1_pubkey pubkey;
+        const unsigned char *msg, *sig, *pk;
+        unsigned char out[32] = {0};
+        int actual_verify = 0;
+
+        memset(&pubkey, 0, sizeof(pubkey));
+        pk = &wycheproof_ecdsa_public_keys[testvectors[t].pk_offset];
+        CHECK(secp256k1_ec_pubkey_parse(CTX, &pubkey, pk, 65) == 1);
+
+        secp256k1_sha256_initialize(&hasher);
+        msg = &wycheproof_ecdsa_messages[testvectors[t].msg_offset];
+        secp256k1_sha256_write(&hasher, msg, testvectors[t].msg_len);
+        secp256k1_sha256_finalize(&hasher, out);
+
+        sig = &wycheproof_ecdsa_signatures[testvectors[t].sig_offset];
+        if (secp256k1_ecdsa_signature_parse_der(CTX, &signature, sig, testvectors[t].sig_len) == 1) {
+            actual_verify = secp256k1_ecdsa_verify(CTX, (const secp256k1_ecdsa_signature *)&signature, out, &pubkey);
+        }
+        CHECK(testvectors[t].expected_verify == actual_verify);
+    }
+}
+
+/* Tests cases from Wycheproof test suite. */
+static void run_ecdsa_wycheproof(void) {
+    test_ecdsa_wycheproof();
+}
+
 #ifdef ENABLE_MODULE_BPPP
 # include "modules/bppp/tests_impl.h"
 #endif
@@ -7956,6 +8057,7 @@ int main(int argc, char **argv) {
     run_ecdsa_sign_verify();
     run_ecdsa_end_to_end();
     run_ecdsa_edge_cases();
+    run_ecdsa_wycheproof();
 
 #ifdef ENABLE_MODULE_RECOVERY
     /* ECDSA pubkey recovery tests */

src/tests_exhaustive.c

@@ -59,6 +59,19 @@ static void random_fe(secp256k1_fe *x) {
         }
     } while(1);
 }
+
+static void random_fe_non_zero(secp256k1_fe *nz) {
+    int tries = 10;
+    while (--tries >= 0) {
+        random_fe(nz);
+        secp256k1_fe_normalize(nz);
+        if (!secp256k1_fe_is_zero(nz)) {
+            break;
+        }
+    }
+    /* Infinitesimal probability of spurious failure here */
+    CHECK(tries >= 0);
+}
 /** END stolen from tests.c */
 
 static uint32_t num_cores = 1;
@@ -174,10 +187,37 @@ static void test_exhaustive_ecmult(const secp256k1_ge *group, const secp256k1_ge
                 secp256k1_ecmult(&tmp, &groupj[r_log], &na, &ng);
                 ge_equals_gej(&group[(i * r_log + j) % EXHAUSTIVE_TEST_ORDER], &tmp);
 
-                if (i > 0) {
-                    secp256k1_ecmult_const(&tmp, &group[i], &ng, 256);
-                    ge_equals_gej(&group[(i * j) % EXHAUSTIVE_TEST_ORDER], &tmp);
-                }
+            }
+        }
+    }
+
+    for (j = 0; j < EXHAUSTIVE_TEST_ORDER; j++) {
+        for (i = 1; i < EXHAUSTIVE_TEST_ORDER; i++) {
+            int ret;
+            secp256k1_gej tmp;
+            secp256k1_fe xn, xd, tmpf;
+            secp256k1_scalar ng;
+
+            if (skip_section(&iter)) continue;
+
+            secp256k1_scalar_set_int(&ng, j);
+
+            /* Test secp256k1_ecmult_const. */
+            secp256k1_ecmult_const(&tmp, &group[i], &ng, 256);
+            ge_equals_gej(&group[(i * j) % EXHAUSTIVE_TEST_ORDER], &tmp);
+
+            if (j != 0) {
+                /* Test secp256k1_ecmult_const_xonly with all curve X coordinates, and xd=NULL. */
+                ret = secp256k1_ecmult_const_xonly(&tmpf, &group[i].x, NULL, &ng, 256, 0);
+                CHECK(ret);
+                CHECK(secp256k1_fe_equal_var(&tmpf, &group[(i * j) % EXHAUSTIVE_TEST_ORDER].x));
+
+                /* Test secp256k1_ecmult_const_xonly with all curve X coordinates, with random xd. */
+                random_fe_non_zero(&xd);
+                secp256k1_fe_mul(&xn, &xd, &group[i].x);
+                ret = secp256k1_ecmult_const_xonly(&tmpf, &xn, &xd, &ng, 256, 0);
+                CHECK(ret);
+                CHECK(secp256k1_fe_equal_var(&tmpf, &group[(i * j) % EXHAUSTIVE_TEST_ORDER].x));
             }
         }
     }

src/wycheproof/WYCHEPROOF_COPYING

@@ -0,0 +1,212 @@
+* The file `ecdsa_secp256k1_sha256_bitcoin_test.json` in this directory
+  comes from Google's project Wycheproof with git commit
+  `b063b4aedae951c69df014cd25fa6d69ae9e8cb9`, see
+  https://github.com/google/wycheproof/blob/b063b4aedae951c69df014cd25fa6d69ae9e8cb9/testvectors_v1/ecdsa_secp256k1_sha256_bitcoin_test.json
+
+* The file `ecdsa_secp256k1_sha256_bitcoin_test.h` is generated from
+  `ecdsa_secp256k1_sha256_bitcoin_test.json` using the script
+  `tests_wycheproof_generate.py`.
+
+-------------------------------------------------------------------------------
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.