nettle: ECDSA

1 
1 6.7.3.2 ECDSA
1 .............
1 
1 ECDSA is a variant of the DSA digital signature scheme (⇒DSA),
1 which works over an elliptic curve group rather than over a (subgroup
1 of) integers modulo p.  Like DSA, creating a signature requires a unique
1 random nonce (repeating the nonce with two different messages reveals
1 the private key, and any leak or bias in the generation of the nonce
1 also leaks information about the key).
1 
1    Unlike DSA, signatures are in general not tied to any particular hash
1 function or even hash size.  Any hash function can be used, and the hash
1 value is truncated or padded as needed to get a size matching the curve
1 being used.  It is recommended to use a strong cryptographic hash
1 function with digest size close to the bit size of the curve, e.g.,
1 SHA256 is a reasonable choice when using ECDSA signature over the curve
1 secp256r1.  A protocol or application using ECDSA has to specify which
1 curve and which hash function to use, or provide some mechanism for
1 negotiating.
1 
1    Nettle defines ECDSA in ‘<nettle/ecdsa.h>’.  We first need to define
1 the data types used to represent public and private keys.
1 
1  -- struct: struct ecc_point
1      Represents a point on an elliptic curve.  In particular, it is used
1      to represent an ECDSA public key.
1 
1  -- Function: void ecc_point_init (struct ecc_point *P, const struct
1           ecc_curve *ECC)
1      Initializes P to represent points on the given curve ECC.
1      Allocates storage for the coordinates, using the same allocation
1      functions as GMP.
1 
1  -- Function: void ecc_point_clear (struct ecc_point *P)
1      Deallocate storage.
1 
1  -- Function: int ecc_point_set (struct ecc_point *P, const mpz_t X,
1           const mpz_t Y)
1      Check that the given coordinates represent a point on the curve.
1      If so, the coordinates are copied and converted to internal
1      representation, and the function returns 1.  Otherwise, it returns
1      0.  Currently, the infinity point (or zero point, with additive
1      notation) is not allowed.
1 
1  -- Function: void ecc_point_get (const struct ecc_point *P, mpz_t X,
1           mpz_t Y)
1      Extracts the coordinate of the point P.  The output parameters X or
1      Y may be NULL if the caller doesn’t want that coordinate.
1 
1  -- struct: struct ecc_scalar
1      Represents an integer in the range 0 < x < group order, where the
1      “group order” refers to the order of an ECC group.  In particular,
1      it is used to represent an ECDSA private key.
1 
1  -- Function: void ecc_scalar_init (struct ecc_scalar *S, const struct
1           ecc_curve *ECC)
1      Initializes S to represent a scalar suitable for the given curve
1      ECC.  Allocates storage using the same allocation functions as GMP.
1 
1  -- Function: void ecc_scalar_clear (struct ecc_scalar *S)
1      Deallocate storage.
1 
1  -- Function: int ecc_scalar_set (struct ecc_scalar *S, const mpz_t Z)
1      Check that Z is in the correct range.  If so, copies the value to S
1      and returns 1, otherwise returns 0.
1 
1  -- Function: void ecc_scalar_get (const struct ecc_scalar *S, mpz_t Z)
1      Extracts the scalar, in GMP ‘mpz_t’ representation.
1 
1    To create and verify ECDSA signatures, the following functions are
1 used.
1 
1  -- Function: void ecdsa_sign (const struct ecc_scalar *KEY, void
1           *RANDOM_CTX, nettle_random_func *RANDOM, size_t DIGEST_LENGTH,
1           const uint8_t *DIGEST, struct dsa_signature *SIGNATURE)
1      Uses the private key KEY to create a signature on DIGEST.
1      RANDOM_CTX and RANDOM is a randomness generator.
1      ‘random(random_ctx, length, dst)’ should generate ‘length’ random
1      octets and store them at ‘dst’.  The signature is stored in
1      SIGNATURE, in the same was as for plain DSA.
1 
1  -- Function: int ecdsa_verify (const struct ecc_point *PUB, size_t
1           LENGTH, const uint8_t *DIGEST, const struct dsa_signature
1           *SIGNATURE)
1      Uses the public key PUB to verify that SIGNATURE is a valid
1      signature for the message digest DIGEST (of LENGTH octets).
1      Returns 1 if the signature is valid, otherwise 0.
1 
1    Finally, generating a new ECDSA key pair:
1 
1  -- Function: void ecdsa_generate_keypair (struct ecc_point *PUB, struct
1           ecc_scalar *KEY, void *RANDOM_CTX, nettle_random_func
1           *RANDOM);
1      PUB and KEY is where the resulting key pair is stored.  The structs
1      should be initialized, for the desired ECC curve, before you call
1      this function.
1 
1      RANDOM_CTX and RANDOM is a randomness generator.
1      ‘random(random_ctx, length, dst)’ should generate ‘length’ random
11      octets and store them at ‘dst’.  For advice, see ⇒
      Randomness.
1