A set of low-level APIs to perform computations over the edwards25519 curve, only useful to implement custom constructions.
Points are represented as their Y coordinate.
Example
Perform a secure two-party computation of f(x) = p(x)^k. x is the input sent to the second party by the first party after blinding it using a random invertible scalar r, and k is a secret key only known by the second party. p(x) is a hash-to-curve function.
1
// -------- First party -------- Send blinded p(x)
2
unsignedchar x[crypto_core_ed25519_UNIFORMBYTES];
3
randombytes_buf(x,sizeof x);
4
​
5
// Compute px = p(x), an EC point representative for x
6
unsignedchar px[crypto_core_ed25519_BYTES];
7
crypto_core_ed25519_from_uniform(px, x);
8
​
9
// Compute a = p(x) * g^r
10
unsignedchar r[crypto_core_ed25519_SCALARBYTES];
11
unsignedchar gr[crypto_core_ed25519_BYTES];
12
unsignedchar a[crypto_core_ed25519_BYTES];
13
crypto_core_ed25519_scalar_random(r);
14
crypto_scalarmult_ed25519_base_noclamp(gr, r);
15
crypto_core_ed25519_add(a, px, gr);
16
​
17
// -------- Second party -------- Send g^k and a^k
The crypto_core_ed25519_is_valid_point() function checks that p represents a point on the edwards25519 curve, in canonical form, on the main subgroup, and that the point doesn't have a small order.
It returns 1 on success, and 0 if the checks didn't pass.
Random group element
1
voidcrypto_core_ed25519_random(unsignedchar*p);
Copied!
Fills p with the representation of a random group element.
The crypto_core_ed25519_from_uniform() function maps a 32 bytes vector r to a point, and stores its compressed representation into p.
The point is guaranteed to be on the main subgroup.
This function directly exposes the Elligator 2 map, uses the high bit to set the sign of the X coordinate, and the resulting point is multiplied by the cofactor.
The crypto_scalarmult_ed25519() function multiplies a point p by a scalar n and puts the Y coordinate of the resulting point into q.
q should not be used as a shared key prior to hashing.
The function returns 0 on success, or -1 if n is 0 or if p is not on the curve, not on the main subgroup, is a point of small order, or is not provided in canonical form.
Note that n is "clamped" (the 3 low bits are cleared to make it a multiple of the cofactor, bit 254 is set and bit 255 is cleared to respect the original design).
The crypto_scalarmult_ed25519_base() function multiplies the base point (x, 4/5) by a scalar n (clamped) and puts the Y coordinate of the resulting point into q.
The function returns -1 if n is 0, and 0 otherwise.
Scalar multiplication without clamping
In order to prevent attacks using small subgroups, the scalarmult functions above clear lower bits of the scalar. This may be indesirable to build protocols that requires n to be invertible.
The noclamp variants of these functions do not clear these bits, and do not set the high bit either. These variants expect a scalar in the ]0..L[ range.
The function verifies that p is on the prime-order subgroup before performing the multiplication, and return -1 if this is not the case or n is 0. It returns 0 on success.
The function returns 0 on success, or -1 if n is 0.
Point addition/subtraction
1
intcrypto_core_ed25519_add(unsignedchar*r,
2
constunsignedchar*p,constunsignedchar*q);
Copied!
The crypto_core_ed25519_add() function adds the point p to the point q and stores the resulting point into r.
The function returns 0 on success, or -1 if p and/or q are not valid points.
1
intcrypto_core_ed25519_sub(unsignedchar*r,
2
constunsignedchar*p,constunsignedchar*q);
Copied!
The crypto_core_ed25519_sub() function subtracts the point p to the point q and stores the resulting point into r.
The function returns 0 on success, or -1 if p and/or q are not valid points.
Scalar arithmetic over L
Scalars should ideally be randomly chosen in the [0..L[ interval, L being the order of the main subgroup (2^252 + 27742317777372353535851937790883648493).
This can be achieved with the following function, introduced in libsodium 1.0.17:
The crypto_core_ed25519_scalar_reduce() function reduces s to s mod L and puts the crypto_core_ed25519_SCALARBYTES integer into r.
Note that s is much larger than r (64 bytes vs 32 bytes). Bits of s can be left to 0, but the interval s is sampled from should be at least 317 bits to ensure almost uniformity of r over L.