Update docs

Changelog.rst

@@ -8,6 +8,7 @@ New features
 ------------
 * Add support for curves Ed25519 and Ed448, including export and import of keys.
 * Add support for EdDSA signatures.
+* Add support for Asymmetric Key Packages (RFC5958) to import private keys.
 
 Resolved issues
 ---------------

Doc/src/public_key/ecc.rst

@@ -47,8 +47,8 @@ and subsequently reload it back into the application::
     >>> key = ECC.import_key(f.read())
 
 The ECC key can be used to perform or verify signatures, using the modules
-:mod:`Crypto.Signature.DSS` (ECDSA, NIST curves only)
-or :mod:`Crypto.Signature.eddsa` (EdDSA, Ed25519 and Ed448 curve only).
+:mod:`Crypto.Signature.DSS` (ECDSA; NIST curves only)
+or :mod:`Crypto.Signature.eddsa` (EdDSA; Ed25519 and Ed448 curve only).
 
 .. _ECC: http://andrea.corbellini.name/2015/05/17/elliptic-curve-cryptography-a-gentle-introduction/
 .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf

lib/Crypto/PublicKey/ECC.py

@@ -461,9 +461,9 @@ class UnsupportedEccFeature(ValueError):
 
 
 class EccPoint(object):
-    """A class to abstract a point over an Elliptic Curve.
+    """A class to model a point on an Elliptic Curve.
 
-    The class support special methods for:
+    The class supports operators for:
 
     * Adding two points: ``R = S + T``
     * In-place addition: ``S += T``
@@ -559,14 +559,16 @@ def _is_eddsa(self):
         return self._curve.name in ("ed25519", "ed448")
 
     def is_point_at_infinity(self):
-        """``True`` if this is the point-at-infinity."""
+        """``True`` if this is the *point-at-infinity*."""
+
         if self._is_eddsa():
             return self.x == 0
         else:
             return self.xy == (0, 0)
 
     def point_at_infinity(self):
-        """Return the point-at-infinity for the curve this point is on."""
+        """Return the *point-at-infinity* for the curve."""
+
         if self._is_eddsa():
             return EccPoint(0, 1, self._curve_name)
         else:
@@ -606,8 +608,8 @@ def size_in_bits(self):
     def double(self):
         """Double this point (in-place operation).
 
-        :Return:
-            :class:`EccPoint` : this same object (to enable chaining)
+        Returns:
+            This same object (to enable chaining).
         """
 
         double_func = lib_func(self, "double")
@@ -705,15 +707,17 @@ class EccKey(object):
     :ivar curve: The name of the curve as defined in the `ECC table`_.
     :vartype curve: string
 
-    :ivar point: an ECC point representating the public component
-    :vartype point: :class:`EccPoint`
+    :ivar pointQ: an ECC point representating the public component.
+    :vartype pointQ: :class:`EccPoint`
 
-    :ivar d: A scalar representating the private component.
-             Only for NIST P curves.
+    :ivar d: A scalar that represents the private component
+             in NIST P curves. It is smaller than the
+             order of the generator point.
     :vartype d: integer
 
-    :ivar seed: A seed representating the private component.
-                Only for Ed25519 (32 bytes) or Ed448 (57 bytes) curves.
+    :ivar seed: A seed that representats the private component
+                in EdDSA curves
+                (Ed25519, 32 bytes; Ed448, 57 bytes).
     :vartype seed: bytes
     """
 
@@ -1046,9 +1050,11 @@ def export_key(self, **kwargs):
               into ``bytes`` according to Section 2.3.3 of `SEC1`_
               (which is a subset of the older X9.62 ITU standard).
               Only for NIST P-curves.
-            - ``'raw'``. The public key will be encoded as ``byte``,
-              without metadata. For NIST P-curves: equivalent to ``'SEC1'``.
-              For EdDSA curves: ``bytes`` in the format defined in `RFC8032`_.
+            - ``'raw'``. The public key will be encoded as ``bytes``,
+              without any metadata.
+
+              * For NIST P-curves: equivalent to ``'SEC1'``.
+              * For EdDSA curves: ``bytes`` in the format defined in `RFC8032`_.
 
           passphrase (byte string or string):
             The passphrase to use for protecting the private key.
@@ -1196,11 +1202,11 @@ def construct(**kwargs):
         Mandatory. The name of the elliptic curve, as defined in the `ECC table`_.
 
       d (integer):
-        Mandatory for a private key on a NIST P-curve (e.g., P-256):
+        Mandatory for a private key and a NIST P-curve (e.g., P-256):
         the integer in the range ``[1..order-1]`` that represents the key.
 
       seed (bytes):
-        Mandatory for a private key on an EdDSA curve.
+        Mandatory for a private key and an EdDSA curve.
         It must be 32 bytes for Ed25519, and 57 bytes for Ed448.
 
       point_x (integer):
@@ -1690,9 +1696,12 @@ def import_key(encoded, passphrase=None, curve_name=None):
         For a SEC1 encoding only. This is the name of the curve,
         as defined in the `ECC table`_.
 
-    To import EdDSA private and public keys, when encoded as raw ``bytes``,
-    use :func:`Crypto.Signature.eddsa.import_public_key`
-    and :func:`Crypto.Signature.eddsa.import_private_key`.
+    .. note::
+
+        To import EdDSA private and public keys, when encoded as raw ``bytes``, use:
+
+        * :func:`Crypto.Signature.eddsa.import_public_key`, or
+        * :func:`Crypto.Signature.eddsa.import_private_key`.
 
     Returns:
       :class:`EccKey` : a new ECC key object

lib/Crypto/Signature/eddsa.py

@@ -45,7 +45,7 @@ def import_public_key(encoded):
     Args:
       encoded (bytes):
         The EdDSA public key to import.
-        It must be 32 bytes long for Ed25519, and 57 for Ed448.
+        It must be 32 bytes for Ed25519, and 57 bytes for Ed448.
 
     Returns:
       :class:`Crypto.PublicKey.EccKey` : a new ECC key object.
@@ -72,7 +72,7 @@ def import_private_key(encoded):
     Args:
       encoded (bytes):
         The EdDSA private key to import.
-        It must be 32 bytes long for Ed25519, and 57 for Ed448.
+        It must be 32 bytes for Ed25519, and 57 bytes for Ed448.
 
     Returns:
       :class:`Crypto.PublicKey.EccKey` : a new ECC key object.
@@ -123,13 +123,13 @@ def sign(self, msg_or_hash):
 
         Args:
           msg_or_hash (bytes or a hash object):
-            The message to verify (*PureEdDSA*) or
-            the hash that was carried out over the message (*HashEdDSA*).
+            The message to sign (``bytes``, in case of *PureEdDSA*) or
+            the hash that was carried out over the message (hash object, for *HashEdDSA*).
 
-            The hash object is :class:`Crypto.Hash.SHA512` object) for Ed25519,
-            and :class:`Crypto.Hash.SHAKE256` object) for Ed448.
+            The hash object must be :class:`Crypto.Hash.SHA512` for Ed25519,
+            and :class:`Crypto.Hash.SHAKE256` object for Ed448.
 
-        :return: The signature as ``bytes``
+        :return: The signature as ``bytes``. It is always 64 bytes for Ed25519, and 114 bytes for Ed448.
         :raise TypeError: if the EdDSA key has no private half
         """
 
@@ -209,14 +209,15 @@ def verify(self, msg_or_hash, signature):
 
         Args:
           msg_or_hash (bytes or a hash object):
-            The message to verify (*PureEdDSA*) or
-            the hash that was carried out over the message (*HashEdDSA*).
+            The message to verify (``bytes``, in case of *PureEdDSA*) or
+            the hash that was carried out over the message (hash object, for *HashEdDSA*).
 
-            The hash object is :class:`Crypto.Hash.SHA512` object) for Ed25519,
-            and :class:`Crypto.Hash.SHAKE256` object) for Ed448.
+            The hash object must be :class:`Crypto.Hash.SHA512` object for Ed25519,
+            and :class:`Crypto.Hash.SHAKE256` for Ed448.
 
           signature (``bytes``):
             The signature that needs to be validated.
+            It must be 64 bytes for Ed25519, and 114 bytes for Ed448.
 
         :raise ValueError: if the signature is not authentic
         """
@@ -312,18 +313,18 @@ def new(key, mode, context=None):
     can perform or verify an EdDSA signature.
 
     Args:
-        key (:class:`Crypto.PublicKey.ECC` on curve ``Ed25519`` or ``Ed448``):
+        key (:class:`Crypto.PublicKey.ECC` object:
             The key to use for computing the signature (*private* keys only)
             or for verifying one.
+            The key must be on the curve ``Ed25519`` or ``Ed448``.
 
         mode (string):
             This parameter must be ``'rfc8032'``.
 
         context (bytes):
             Up to 255 bytes of `context <https://datatracker.ietf.org/doc/html/rfc8032#page-41>`_,
             which is a constant byte string to segregate different protocols or
-            uses of the same key.
-            Do not specify a context, if you want a Pure EdDSA signature.
+            different applications of the same key.
     """
 
     if not isinstance(key, EccKey) or not key._is_eddsa():