From 48ee6cfe03ef2ae23e866ff1da9d12cea1f3ddf4 Mon Sep 17 00:00:00 2001
From: J08nY
Date: Wed, 25 Oct 2023 18:05:26 +0200
Subject: Add BoringSSL to library docs.

---
 docs/libraries.rst | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)

diff --git a/docs/libraries.rst b/docs/libraries.rst
index 292d4bc..1112cc3 100644
--- a/docs/libraries.rst
+++ b/docs/libraries.rst
@@ -122,3 +122,121 @@ Verify:
    ``Ed25519.verify -> Ed25519.implVerify -> Ed25519.scalarMultStraus128Var``.
  - Many coordinate systems: Extended, half-Niels, affine.
  - Some HWCD formulas are used.
+
+
+BoringSSL
+=========
+
+| Version: ``bfa8369`` (commit bfa8369)
+| Repository: https://github.com/google/boringssl/
+| Docs: https://commondatastorage.googleapis.com/chromium-boringssl-docs/headers.html
+
+Primitives
+----------
+
+Supports P-224, P-256, P-384 and P-521.
+Also Curve25519.
+Uses fiat-crypto for the SECP curve field arithmetic.
+
+P-224
+^^^^^
+ - Short-Weierstrass
+ - `Comb <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p224-64.c#L995>`_ via ``mul_base -> ec_GFp_nistp224_point_mul_base``.
+   `Fixed Window <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p224-64.c#L947C13-L947C38>`_ via ``mul -> ec_GFp_nistp224_point_mul``.
+ - `Jacobian <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p224-64.c#L580>`_,
+ - Formulas unknown.
+
+P-256
+^^^^^
+ - Short-Weierstrass
+ - `Comb <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p256.c#L543>`_ via ``mul_base -> ec_GFp_nistp256_point_mul_base``.
+   `Fixed Window <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p256.c#L476>`_ via ``mul -> ec_GFp_nistp256_point_mul``.
+ - `Jacobian-3 <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p256.c#L238>`_,
+ - `add-2007-bl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p256.c#L238>`_,
+   `dbl-2001-b <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/p256.c#L184>`_
+
+P-384
+^^^^^
+ - Uses defaults (described below).
+
+P-521
+^^^^^
+- Uses defaults (described below).
+
+ECDH
+^^^^
+
+KeyGen:
+ - Short-Weierstrass
+ - ``EC_KEY_generate_key -> ec_point_mul_scalar_base -> meth.mul_base``.
+   Default: `Fixed Window <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/simple_mul.c#L24>`_, via ``ec_GFp_mont_mul_base -> ec_GFp_mont_mul``.
+ - `Jacobian <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_
+- `add-2007-bl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_, `dbl-2001-b <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L329>`_
+
+Derive:
+ - Short-Weierstrass
+ - ``ECDH_compute_key -> ec_point_mul_scalar -> meth.mul``.
+   Default: `Fixed Window <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/simple_mul.c#L24>`_, via ``ec_GFp_mont_mul``.
+ - `Jacobian <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_
+ - `add-2007-bl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_, `dbl-2001-b <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L329>`_
+
+ECDSA
+^^^^^
+
+KeyGen:
+ - Short-Weierstrass
+ - ``EC_KEY_generate_key -> ec_point_mul_scalar_base -> meth.mul_base``.
+   Default: `Fixed Window <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/simple_mul.c#L24>`_, via ``ec_GFp_mont_mul``.
+ - `Jacobian <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_
+ - `add-2007-bl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_, `dbl-2001-b <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L329>`_
+
+Sign:
+ - Short-Weierstrass
+ - ``ECDSA_sign -> ECDSA_do_sign -> ecdsa_sign_impl -> ec_point_mul_scalar_base -> meth.mul_base``.
+   Default: `Fixed Window <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/simple_mul.c#L24>`_, via ``ec_GFp_mont_mul``.
+ - `Jacobian <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_
+- `add-2007-bl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_, `dbl-2001-b <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L329>`_
+
+Verify:
+ - Short-Weierstrass
+ - ``ECDSA_verify -> ECDSA_do_verify -> ecdsa_do_verify_no_self_test -> ec_point_mul_scalar_public -> meth.mul_public or meth.mul_public_batch``.
+   Default: `Window NAF (w=4) based interleaving multi-exponentiation method <https://github.com/google/boringssl/blob/bfa8369/crypto/fipsmodule/ec/wnaf.c#L83>`_, via ``ec_GFp_mont_mul_public_batch``.
+ - `Jacobian <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_
+- `add-2007-bl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L218>`_, `dbl-2001-b <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/fipsmodule/ec/ec_montgomery.c#L329>`_
+
+X25519
+^^^^^^
+
+KeyGen:
+ - Twisted-Edwards
+ - ?? via ``X25519_keypair -> X25519_public_from_private -> x25519_ge_scalarmult_base``.
+ - Has `multiple coordinate systems <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/internal.h#L79>`_: projective, extended, completed, Duif
+ - Unknown formulas. `dbl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L617>`_, `add <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L624>`_
+
+Derive:
+ - Montgomery
+ - Ladder via ``X25519 -> x25519_scalar_mult -> x25519_NEON/x25519_scalar_mult_adx/x25519_scalar_mult_generic``
+ - Actually seems to use xz.
+ - Unknown formula (ladder).
+
+Ed25519
+^^^^^^^
+Based on ref10 of Ed25519.
+
+KeyGen:
+ - Twisted-Edwards
+ - ?? via ``ED25519_keypair -> ED25519_keypair_from_seed -> x25519_ge_scalarmult_base``.
+ - Has `multiple coordinate systems <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/internal.h#L79>`_: projective, extended, completed, Duif
+ - Unknown formulas. `dbl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L617>`_, `add <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L624>`_
+
+Sign:
+ - Twisted-Edwards
+ - ?? via ``ED25519_sign -> ED25519_keypair_from_seed -> x25519_ge_scalarmult_base``.
+ - Has `multiple coordinate systems <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/internal.h#L79>`_: projective, extended, completed, Duif
+ - Unknown formulas. `dbl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L617>`_, `add <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L624>`_
+
+Verify:
+ - Twisted-Edwards
+ - Sliding window (signed) with interleaving? via ``ED25519_verify -> ge_double_scalarmult_vartime``.
+ - Has `multiple coordinate systems <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/internal.h#L79>`_: projective, extended, completed, Duif
+ - Unknown formulas. `dbl <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L617>`_, `add <https://github.com/google/boringssl/blob/bfa8369795b7533a222a72b7a1bc928941cd66bf/crypto/curve25519/curve25519.c#L624>`_
-- 
cgit v1.3.1