Doc updates [ci skip]

3 files changed, 288 insertions, 3 deletions

diff --git a/doc/manual/block_cipher.rst b/doc/manual/block_cipher.rst
index 316884682..6c8fa9c45 100644
--- a/doc/manual/block_cipher.rst
+++ b/doc/manual/block_cipher.rst
@@ -5,10 +5,10 @@ Block ciphers are a n-bit permutation for some small n, typically 64 or 128
 bits.  They are a cryptographic primitive used to generate higher level
 operations such as authenticated encryption.
 
-.. note::
+.. warning::
 
-   In general a bare block cipher is not what you should be using. You probably
-   want a cipher mode instead (see :ref:`cipher_modes`)
+   In almost all cases, a bare block cipher is not what you should be using.
+   You probably want an authenticated cipher mode instead (see :ref:`cipher_modes`)
 
 .. cpp:class:: BlockCipher
 
diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst
index f3c89cc19..8fff76550 100644
--- a/doc/manual/contents.rst
+++ b/doc/manual/contents.rst
@@ -30,6 +30,7 @@ Contents
    psk_db
    filters
    fpe
+   ecc
    compression
    pkcs11
    tpm
diff --git a/doc/manual/ecc.rst b/doc/manual/ecc.rst
new file mode 100644
index 000000000..72c90a310
--- /dev/null
+++ b/doc/manual/ecc.rst
@@ -0,0 +1,284 @@
+Elliptic Curve Operations
+============================
+
+In addition to high level operations for signatures, key agreement,
+and message encryption using elliptic curve cryptography, the library
+contains lower level interfaces for performing operations such as
+elliptic curve point multiplication.
+
+Only curves over prime fields are supported.
+
+Many of these functions take a workspace, either a vector of words or
+a vector of BigInts. These are used to minimize memory allocations
+during common operations.
+
+.. warning::
+   You should only use these interfaces if you know what you are doing.
+
+.. cpp:class:: EC_Group
+
+      .. cpp:function:: EC_Group(const OID& oid)
+
+         Initialize an ``EC_Group`` using an OID referencing the curve
+         parameters.
+
+      .. cpp:function:: EC_Group(const std::string& name)
+
+         Initialize an ``EC_Group`` using a name or OID (for example
+         "secp256r1", or "1.2.840.10045.3.1.7")
+
+      .. cpp:function:: EC_Group(const BigInt& p, \
+               const BigInt& a, \
+               const BigInt& b, \
+               const BigInt& base_x, \
+               const BigInt& base_y, \
+               const BigInt& order, \
+               const BigInt& cofactor, \
+               const OID& oid = OID())
+
+          Initialize an elliptic curve group from the relevant parameters. This
+          is used for example to create custom (application-specific) curves.
+
+      .. cpp:function:: EC_Group(const std::vector<uint8_t>& ber_encoding)
+
+         Initialize an ``EC_Group`` by decoding a DER encoded parameter block.
+
+      .. cpp:function:: std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const
+
+         Return the DER encoding of this group.
+
+      .. cpp:function:: std::string PEM_encode() const
+
+         Return the PEM encoding of this group (base64 of DER encoding plus
+         header/trailer).
+
+      .. cpp:function:: bool a_is_minus_3() const
+
+         Return true if the ``a`` parameter is congruent to -3 mod p.
+
+      .. cpp:function:: bool a_is_zero() const
+
+         Return true if the ``a`` parameter is congruent to 0 mod p.
+
+      .. cpp:function:: size_t get_p_bits() const
+
+         Return size of the prime in bits.
+
+      .. cpp:function:: size_t get_p_bytes() const
+
+         Return size of the prime in bytes.
+
+      .. cpp:function:: size_t get_order_bits() const
+
+         Return size of the group order in bits.
+
+      .. cpp:function:: size_t get_order_bytes() const
+
+         Return size of the group order in bytes.
+
+      .. cpp:function:: const BigInt& get_p() const
+
+         Return the prime modulus.
+
+      .. cpp:function:: const BigInt& get_a() const
+
+         Return the ``a`` parameter of the elliptic curve equation.
+
+      .. cpp:function:: const BigInt& get_b() const
+
+         Return the ``b`` parameter of the elliptic curve equation.
+
+      .. cpp:function:: const PointGFp& get_base_point() const
+
+         Return the groups base point element.
+
+      .. cpp:function:: const BigInt& get_g_x() const
+
+         Return the x coordinate of the base point element.
+
+      .. cpp:function:: const BigInt& get_g_y() const
+
+         Return the y coordinate of the base point element.
+
+      .. cpp:function:: const BigInt& get_order() const
+
+         Return the order of the group generated by the base point.
+
+      .. cpp:function:: const BigInt& get_cofactor() const
+
+         Return the cofactor of the curve. In most cases this will be 1.
+
+      .. cpp:function:: BigInt mod_order(const BigInt& x) const
+
+         Reduce argument ``x`` modulo the curve order.
+
+      .. cpp:function:: BigInt inverse_mod_order(const BigInt& x) const
+
+         Return inverse of argument ``x`` modulo the curve order.
+
+      .. cpp:function:: BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const
+
+         Multiply ``x`` and ``y`` and reduce the result modulo the curve order.
+
+      .. cpp:function:: bool verify_public_element(const PointGFp& y) const
+
+         Return true if ``y`` seems to be a valid group element.
+
+      .. cpp:function:: const OID& get_curve_oid() const
+
+         Return the OID used to identify the curve. May be empty.
+
+      .. cpp:function:: PointGFp point(const BigInt& x, const BigInt& y) const
+
+         Create and return a point with affine elements ``x`` and ``y``. Note
+         this function *does not* verify that ``x`` and ``y`` satisfy the curve
+         equation.
+
+      .. cpp:function:: PointGFp point_multiply(const BigInt& x, const PointGFp& pt, const BigInt& y) const
+
+         Multi-exponentation. Returns base_point*x + pt*y. Not constant time.
+         (Ordinarily used for signature verification.)
+
+      .. cpp:function:: PointGFp blinded_base_point_multiply(const BigInt& k, \
+                                            RandomNumberGenerator& rng, \
+                                            std::vector<BigInt>& ws) const
+
+         Return ``base_point*k`` in a way that attempts to resist side channels.
+
+      .. cpp:function:: BigInt blinded_base_point_multiply_x(const BigInt& k, \
+                                           RandomNumberGenerator& rng, \
+                                           std::vector<BigInt>& ws) const
+
+         Like `blinded_base_point_multiply` but returns only the x coordinate.
+
+      .. cpp:function:: PointGFp blinded_var_point_multiply(const PointGFp& point, \
+                                          const BigInt& k, \
+                                          RandomNumberGenerator& rng, \
+                                          std::vector<BigInt>& ws) const
+
+         Return ``point*k`` in a way that attempts to resist side channels.
+
+      .. cpp:function:: BigInt random_scalar(RandomNumberGenerator& rng) const
+
+         Return a random scalar (ie an integer between 1 and the group order).
+
+      .. cpp:function:: PointGFp zero_point() const
+
+         Return the zero point (aka the point at infinity).
+
+      .. cpp:function:: PointGFp OS2ECP(const uint8_t bits[], size_t len) const
+
+         Decode a point from the binary encoding. This function verifies that
+         the decoded point is a valid element on the curve.
+
+      .. cpp:function:: bool verify_group(RandomNumberGenerator& rng, bool strong = false) const
+
+         Attempt to verify the group seems valid.
+
+      .. cpp:function:: static const std::set<std::string>& known_named_groups()
+
+         Return a list of known groups, ie groups for which ``EC_Group(name)``
+         will succeed.
+
+.. cpp:class:: PointGFp
+
+   Stores elliptic curve points in Jacobian representation.
+
+   .. cpp:function:: std::vector<uint8_t> encode(PointGFp::Compression_Type format) const
+
+      Encode a point in a way that can later be decoded with `EC_Group::OS2ECP`.
+
+   .. cpp:function:: PointGFp& operator+=(const PointGFp& rhs)
+
+      Point addition.
+
+   .. cpp:function:: PointGFp& operator-=(const PointGFp& rhs)
+
+      Point subtraction.
+
+   .. cpp:function:: PointGFp& operator*=(const BigInt& scalar)
+
+      Point multiplication using Montgomery ladder.
+
+      .. warning::
+         Prefer the blinded functions in ``EC_Group``
+
+   .. cpp:function:: PointGFp& negate()
+
+      Negate this point.
+
+   .. cpp:function:: BigInt get_affine_x() const
+
+      Return the affine ``x`` coordinate of the point.
+
+   .. cpp:function:: BigInt get_affine_y() const
+
+      Return the affine ``y`` coordinate of the point.
+
+   .. cpp:function:: void force_affine()
+
+      Convert the point to its equivalent affine coordinates. Throws
+      if this is the point at infinity.
+
+   .. cpp:function:: static void force_all_affine(std::vector<PointGFp>& points, \
+                                                  secure_vector<word>& ws)
+
+      Force several points to be affine at once. Uses Montgomery's
+      trick to reduce number of inversions required, so this is much
+      faster than calling ``force_affine`` on each point in sequence.
+
+   .. cpp:function:: bool is_affine() const
+
+      Return true if this point is in affine coordinates.
+
+   .. cpp:function:: bool is_zero() const
+
+      Return true if this point is zero (aka point at infinity).
+
+   .. cpp:function:: bool on_the_curve() const
+
+      Return true if this point is on the curve.
+
+   .. cpp:function:: void randomize_repr(RandomNumberGenerator& rng)
+
+      Randomize the point representation.
+
+   .. cpp:function:: bool operator==(const PointGFp& other) const
+
+      Point equality. This compares the affine representations.
+
+   .. cpp:function:: void add(const PointGFp& other, std::vector<BigInt>& workspace)
+
+      Point addition, taking a workspace.
+
+   .. cpp:function:: void add_affine(const PointGFp& other, std::vector<BigInt>& workspace)
+
+      Mixed (Jacobian+affine) addition, taking a workspace.
+
+      .. warning::
+
+         This function assumes that ``other`` is affine, if this is
+         not correct the result will be invalid.
+
+   .. cpp:function:: void mult2(std::vector<BigInt>& workspace)
+
+      Point doubling.
+
+   .. cpp:function:: void mult2i(size_t i, std::vector<BigInt>& workspace)
+
+      Repeated point doubling.
+
+   .. cpp:function:: PointGFp plus(const PointGFp& other, std::vector<BigInt>& workspace) const
+
+      Point addition, returning the result.
+
+   .. cpp:function:: PointGFp double_of(std::vector<BigInt>& workspace) const
+
+      Point doubling, returning the result.
+
+   .. cpp:function:: PointGFp zero() const
+
+      Return the point at infinity
+
+
+