package mirage-crypto-ec

Type for private keys.

In the usual setting, the private key only be generated and used for key exchange. But it can be useful to create values of type secret with a known value, for example to check against test vectors. One can use the following pattern to do this:

let (secret, _) = gen_key ~rng:(fun _ -> known_data) 

gen_key ~rng generates a private and a public key for Ephemeral Diffie-Hellman. The returned key pair MUST only be used for a single key exchange.

rng is the function used to repeteadly generate a private key until a valid candidate is obtained. rng's int parameter is the size of the Cstruct.t to generate. If rng returns an invalid length buffer, Failure _ is raised.

The generated private key is checked to be greater than zero and lower than the group order meaning the public key cannot be the point at inifinity.

key_exchange secret received_public_key performs Diffie-Hellman key exchange using your secret and the data received from the other party. Returns the shared secret or an error if the received data is wrongly encoded, doesn't represent a point on the curve or represent the point at infinity.

The shared secret is returned as is i.e. not stripped from leading 0x00 bytes.

The public key encoding is described in SEC 1 from SECG.