nettle: Curve 25519

1 
1 6.7.3.3 Curve25519
1 ..................
1 
1 Curve25519 is an elliptic curve of Montgomery type, y^2 = x^3 + 486662
1 x^2 + x (mod p), with p = 2^255 - 19.  Montgomery curves have the
1 advantage of simple and efficient point addition based on the
1 x-coordinate only.  This particular curve was proposed by D. J.
1 Bernstein in 2006, for fast Diffie-Hellman key exchange, and is also
1 described in ‘RFC 7748’.  The group generator is defined by x = 9 (there
1 are actually two points with x = 9, differing by the sign of the
1 y-coordinate, but that doesn’t matter for the curve25519 operations
1 which work with the x-coordinate only).
1 
1    The curve25519 functions are defined as operations on octet strings,
1 representing 255-bit scalars or x-coordinates, in little-endian byte
1 order.  The most significant input bit, i.e, the most significant bit of
1 the last octet, is always ignored.
1 
1    For scalars, in addition, the least significant three bits are
1 ignored, and treated as zero, and the second most significant bit is
1 ignored too, and treated as one.  Then the scalar input string always
1 represents 8 times a number in the range 2^251 <= s < 2^252.
1 
1    Of all the possible input strings, only about half correspond to
1 x-coordinates of points on curve25519, i.e., a value x for which the the
1 curve equation can be solved for y.  The other half correspond to points
1 on a related “twist curve”.  The function ‘curve25519_mul’ uses a
1 Montgomery ladder for the scalar multiplication, as suggested in the
1 curve25519 literature, and required by ‘RFC 7748’.  The output is
1 therefore well defined for _all_ possible inputs, no matter if the input
1 string represents a valid point on the curve or not.
1 
1    Note that the curve25519 implementation in earlier versions of Nettle
1 deviates slightly from ‘RFC 7748’, in that bit 255 of the x coordinate
1 of the point input to curve25519_mul was not ignored.  The
1 ‘nette/curve25519.h’ defines a preprocessor symbol
1 ‘NETTLE_CURVE25519_RFC7748’ to indicate conformance with the standard.
1 
1    Nettle defines Curve 25519 in ‘<nettle/curve25519.h>’.
1 
1  -- Constant: NETTLE_CURVE25519_RFC7748
1      Defined to 1 in Nettle versions conforming to RFC 7748.  Undefined
1      in earlier versions.
1 
1  -- Constant: CURVE25519_SIZE
1      The size of the strings representing curve25519 points and scalars,
1      32.
1 
1  -- Function: void curve25519_mul_g (uint8_t *Q, const uint8_t *N)
1      Computes Q = N G, where G is the group generator and N is an
1      integer.  The input argument N and the output argument Q use a
1      little-endian representation of the scalar and the x-coordinate,
1      respectively.  They are both of size ‘CURVE25519_SIZE’.
1 
1      This function is intended to be compatible with the function
1      ‘crypto_scalar_mult_base’ in the NaCl library.
1 
1  -- Function: void curve25519_mul (uint8_t *Q, const uint8_t *N, const
1           uint8_t *P)
1      Computes Q = N P, where P is an input point and N is an integer.
1      The input arguments N and P and the output argument Q use a
1      little-endian representation of the scalar and the x-coordinates,
1      respectively.  They are all of size ‘CURVE25519_SIZE’.
1 
1      This function is intended to be compatible with the function
1      ‘crypto_scalar_mult’ in the NaCl library.
1 
1 6.7.3.4 EdDSA
1 .............
1 
1 EdDSA is a signature scheme proposed by D. J. Bernstein et al.  in 2011.
1 It is defined using a “Twisted Edwards curve”, of the form -x^2 + y^2 =
1 1 + d x^2 y^2.  The specific signature scheme Ed25519 uses a curve which
1 is equivalent to curve25519: The two groups used differ only by a simple
1 change of coordinates, so that the discrete logarithm problem is of
1 equal difficulty in both groups.
1 
1    Unlike other signature schemes in Nettle, the input to the EdDSA sign
1 and verify functions is the possibly large message itself, not a hash
1 digest.  EdDSA is a variant of Schnorr signatures, where the message is
1 hashed together with other data during the signature process, providing
1 resilience to hash-collisions: A successful attack finding collisions in
1 the hash function does not automatically translate into an attack to
1 forge signatures.  EdDSA also avoids the use of a randomness source by
1 generating the needed signature nonce from a hash of the private key and
1 the message, which means that the message is actually hashed twice when
1 creating a signature.  If signing huge messages, it is possible to hash
1 the message first and pass the short message digest as input to the sign
1 and verify functions, however, the resilience to hash collision is then
1 lost.
1 
1  -- Constant: ED25519_KEY_SIZE
1      The size of a private or public Ed25519 key, 32 octets.
1 
1  -- Constant: ED25519_SIGNATURE_SIZE
1      The size of an Ed25519 signature, 64 octets.
1 
1  -- Function: void ed25519_sha512_public_key (uint8_t *PUB, const
1           uint8_t *PRIV)
1      Computes the public key corresponding to the given private key.
1      Both input and output are of size ‘ED25519_KEY_SIZE’.
1 
1  -- Function: void ed25519_sha512_sign (const uint8_t *PUB, const
1           uint8_t *PRIV, size_t LENGTH, const uint8_t *MSG, uint8_t
1           *SIGNATURE)
1      Signs a message using the provided key pair.
1 
1  -- Function: int ed25519_sha512_verify (const uint8_t *PUB, size_t
1           LENGTH, const uint8_t *MSG, const uint8_t *SIGNATURE)
1      Verifies a message using the provided public key.  Returns 1 if the
1      signature is valid, otherwise 0.
1