1 files changed, 155 insertions, 0 deletions

diff --git a/docs/libraries.rst b/docs/libraries.rst
index 564ca46..9629949 100644
--- a/docs/libraries.rst
+++ b/docs/libraries.rst
@@ -449,3 +449,158 @@ Verify:
  - Short-Weierstrass
  - `Shamir's trick <https://github.com/kmackay/micro-ecc/blob/v1.1/uECC.c#L1558>`__ via ``uECC_verify``.
  - Same coords and formulas as KeyGen.
+
+
+Intel IPP cryptography
+======================
+
+| Version: ``2021.9.0``
+| Repository: https://github.com/intel/ipp-crypto/
+| Docs: https://www.intel.com/content/www/us/en/docs/ipp-crypto/developer-reference/2021-8/overview.html
+
+Primitives
+----------
+
+Supports "ECC (NIST curves), ECDSA, ECDH, EC-SM2".
+Also ECNR.
+
+ECDH
+^^^^
+
+KeyGen:
+ - Short-Weierstrass
+ - `(signed, Booth) Fixed Window with full precomputation? (width = 5) <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/pcpgfpec_mulbase.c#L34>`__ via ``ippsGFpECPublicKey -> gfec_MulBasePoint -> gfec_base_point_mul or gfec_point_mul``.
+ - `Jacobian coords <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/pcpgfpecstuff.h#L76>`__
+ - Has special functions for NIST curves, but those implement the same scalarmult.
+ - Weirdly mentions "Enhanced Montgomery Multiplication" DOI:10.1155/2008/583926 in each of the formulas.
+   Does actually use Montgomery arithmetic.
+
+Add (P-256)::
+
+     * A = x1*z2^2    B = x2*z1^2      C = y1*z2^3      D = y2*z1^3
+     * E = B - A      F = D - C
+     * x3 = -E^3 - 2*A*E^2 + F^2
+     * y3 = -C*E^3 + F*(A*E^2 - x3)
+     * z3 = z1*z2*E
+
+Dbl (P-256)::
+
+     * l1 = 3x^2 + a*z^4 = [a = -3]= 3*(x^2 - z^4) = 3*(x - z^2)*(x + z^2)
+     * z2 = 2*y*z
+     * l2 = 4*x*y^2
+     * x2 = l1^2 - 2*l2
+     * l3 = 8*y^4
+     * y2 = l1*(l2 - x2) - l3
+
+Add::
+
+    // S1 = y1*z2^3
+    // S2 = y2*z1^3
+    //
+    // U1 = x1*z2^2
+    // U2 = x2*z1^2
+
+    //  R = S2-S1
+    //  H = U2-U1
+    //
+    //  x3 = -H^3 -2*U1*H^2 +R2
+    //  y3 = -S1*H^3 +R*(U1*H^2 -x3)
+    //  z3 = z1*z2*H
+
+Dbl::
+
+    // A = 4*x*y^2
+    // B = 3*x^2 + a*z^4
+    //
+    // x3 = -2*A + B^2
+    // y3 = -8y^4 +B*(A-x3)
+    // z3 = 2*y*z
+
+Derive:
+ - Short-Weierstrass
+ - `(signed, Booth) Fixed Window (width = 5) <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/pcpgfpec_mul.c#L36>`__ via ``ippsGFpECSharedSecretDH -> gfec_MulPoint -> gfec_point_mul``.
+ - Has special functions for NIST curves, but those implement the same scalarmult.
+ - Same coordinates and formulas as KeyGen.
+
+ECDSA
+^^^^^
+
+KeyGen:
+ - Same as ECDH.
+
+Sign:
+ - Short-Weierstrass
+ - `(signed, Booth) Fixed Window with full precomputation? (width = 5) <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/pcpgfpec_mulbase.c#L34>`__ via ``ippsGFpECSignDSA -> gfec_MulBasePoint -> gfec_base_point_mul or gfec_point_mul``.
+ - Same coordinates and formulas as KeyGen (and ECDH).
+
+Verify:
+ - Short-Weierstrass
+ - `(signed, Booth) Fixed window (width = 5) interleaved multi-scalar <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/pcpgfpec_prod.c#L36>`__ via ``ippsGFpECVerifyDSA -> gfec_BasePointProduct -> either (gfec_base_point_mul + gfec_point_mul + gfec_point_add) or (gfec_point_prod)``.
+ - Same coordinates and formulas as KeyGen (and ECDH).
+
+
+x25519
+^^^^^^
+
+KeyGen:
+ - Montgomery
+ - `Some Full precomputation <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/crypto_mb/src/x25519/ifma_x25519.c#L1596>`__ via ``mbx_x25519_public_key``
+ - xz
+ - Unknown formulas.
+
+Derive:
+ - Montgomery
+ - `? <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/crypto_mb/src/x25519/ifma_x25519.c#L1140>`__ via ``mbx_x25519 -> x25519_scalar_mul_dual``
+ - xz
+ - Unknown formulas.
+
+Ed25519
+^^^^^^^
+
+KeyGen:
+ - Twisted-Edwards
+ - `Fixed window with full precomputation? (width = 4) <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/crypto_mb/src/ed25519/ifma_arith_ed25519.c#L287>`__ via ``mbx_ed25519_public_key -> ifma_ed25519_mul_basepoint``
+ - Mixes coordinate models::
+
+    homogeneous: (X:Y:Z) satisfying x=X/Z, y=Y/Z
+    extended homogeneous: (X:Y:Z:T) satisfying x=X/Z, y=Y/Z, XY=ZT
+    completed: (X:Y:Z:T) satisfying x=X/Z, y=Y/T
+    scalar precomputed group element: (y-x:y+x:2*t*d), t=x*y
+    mb precomputed group element: (y-x:y+x:2*t*d), t=x*y
+    projective flavor of the mb precomputed: (Y-X:Y+X:2*T*d:Z), T=X*Y
+
+Add::
+
+    fe52_add(r->X, p->Y, p->X);      // X3 = Y1+X1
+    fe52_sub(r->Y, p->Y, p->X);      // Y3 = Y1-X1
+    fe52_mul(r->Z, r->X, q->yaddx);  // Z3 = X3*yplusx2
+    fe52_mul(r->Y, r->Y, q->ysubx);  // Y3 = Y3*yminisx2
+    fe52_mul(r->T, q->t2d, p->T);    // T3 = T1*xy2d2
+    fe52_add(t0, p->Z, p->Z);        // t0 = Z1+Z1
+    fe52_sub(r->X, r->Z, r->Y);      // X3 = Z3-Y3 = X3*yplusx2 - Y3*yminisx2 = (Y1+X1)*yplusx2 - (Y1-X1)*yminisx2
+    fe52_add(r->Y, r->Z, r->Y);      // Y3 = Z3+Y3 = X3*yplusx2 + Y3*yminisx2 = (Y1+X1)*yplusx2 + (Y1-X1)*yminisx2
+    fe52_add(r->Z, t0, r->T);        // Z3 = 2*Z1 + T1*xy2d2
+    fe52_sub(r->T, t0, r->T);        // T3 = 2*Z1 - T1*xy2d2
+
+Dbl::
+
+    fe52_sqr(r->X, p->X);
+    fe52_sqr(r->Z, p->Y);
+    fe52_sqr(r->T, p->Z);
+    fe52_add(r->T, r->T, r->T);
+    fe52_add(r->Y, p->X, p->Y);
+    fe52_sqr(t0, r->Y);
+    fe52_add(r->Y, r->Z, r->X);
+    fe52_sub(r->Z, r->Z, r->X);
+    fe52_sub(r->X, t0, r->Y);
+    fe52_sub(r->T, r->T, r->Z);
+
+Sign:
+ - Twisted-Edwards
+ - `Fixed window with full precomputation? (width = 4) <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/crypto_mb/src/ed25519/ifma_arith_ed25519.c#L287>`__ via ``mbx_ed25519_sign -> ifma_ed25519_mul_basepoint``
+ - Same as KeyGen.
+
+Verify:
+ - Twisted-Edwards
+ - `Fixed window with full precomputation? (width = 4) <https://github.com/intel/ipp-crypto/blob/ippcp_2021.9.0/sources/ippcp/crypto_mb/src/ed25519/ifma_arith_ed25519.c#L287>`__ for base point mult, then just Fixed window (width = 4) for the other mult, all via ``mbx_ed25519_verify -> ifma_ed25519_prod_point -> ifma_ed25519_mul_point + ifma_ed25519_mul_basepoint``
+ - Same as KeyGen.