NAME

Crypt::Sodium::XS::curve25519 - Low-level functions over Curve25519

SYNOPSIS

...

DESCRIPTION

Crypt::Sodium::XS::curve25519 provides an API to libsodium's low-level core functions over the Curve25519 curve. These functions are not usually needed, and must only be used to implement custom constructions.

FUNCTIONS

Nothing is exported by default. A separate import tag is provided for functions and constants for each of the primitives listed in "PRIMITIVES". For example, :ed25519 imports core_ed25519_base. You should use at least one import tag. A :all tag imports everything.

NOTE: Crypt::Sodium::XS::curve25519 does not provide a default primitive. All functions must be called in their core_<primitive>_* form.

Scalar arithmetic over L

The core_<primitive>_scalar_* functions operate over scalars in the [0..L[ interval, L being the order of the main subgroup (2^252 + 27742317777372353535851937790883648493).

Non-reduced inputs are expected to be within that interval.

ristretto255_available

my $has_ristretto255 = ristretto255_available();

Returns true if the version of libsodium this module was built with had the ristretto255 primitive available, false otherwise.

core_<primitive>_add

my $r = core_ed25519_add($p, $q);

Adds the element represented by $p to the element $q and returns the resulting element.

The function croaks if $p and/or $q are not valid encoded elements.

core_<primitive>_is_valid_point

my $is_valid = core_ed25519_is_valid_point($point);

Checks that $point 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 true on success, and false if the checks didn’t pass.

core_<primitive>_random

my $point = core_ed25519_random();

Returns the representation of a random group element.

core_ed25519_from_uniform

core_ristretto255_from_hash

my $vector = sodium_random_bytes(ed25519_UNIFORMBYTES);
my $point = core_ed25519_from_uniform($vector);
my $vector2 = sodium_random_bytes(ristretto255_HASHBYTES);
my $point2 = core_ristretto255_from_hash($vector);

NOTE: Different functions for primitives ed25519 and ristretto255!

Maps a 32 bytes $vector to a point, and returns its compressed representation.

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.

core_<primitive>_scalar_add

my $r = core_E<lt>primitiveE<gt>_add($p, $q);

Adds the point $p to the point $q.

The function croaks if $p and/or $q are not valid points.

core_<primitive>_sub

my $r = core_ed25519_sub($p, $q);

Subtracts the point $q from the point $p.

The function croaks if $p and/or $q are not valid points.

core_<primitive>_scalar_complement

my $comp = core_ed25519_scalar_complement($s);

Returns $comp so that $s + $comp = 1 (mod L).

core_<primitive>_scalar_mul

my $z = core_ed25519_scalar_mul($x, $y);

Returns $x * $y (mod L).

core_<primitive>_scalar_negate

my $neg = core_ed25519_scalar_negate($s);

Returns $neg so that $s + $neg = 0 (mod L).

core_<primitive>_scalar_random

Returns a representation of a random scalar in the ]0..L[ interval.

my $r = core_E<lt>primitiveE<gt>_scalar_random();

A scalar in the [0..L[ interval can also be obtained by reducing a possibly larger value with "core_ed25519_scalar_reduce".

core_<primitive>_scalar_reduce

my $r = core_ed25519_scalar_reduce($s);

Reduces $s to $s mod L.

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.

core_<primitive>_scalar_sub

my $z = core_ed25519_scalar_sub($x, $y);

Returns $x - $y (mod L).

CONSTANTS

core_<primitive>_BYTES

Size of points, in bytes.

core_<primitive>_SCALARBYTES

Size of scalars, in bytes.

core_ed25519_UNIFORMBYTES

core_ristretto255_HASHBYTES

Input size to "core_ed25519_from_uniform" and "core_ristretto255_from_hash", respectively.

PRIMITIVES

All functions have core_<primitive>-prefixed couterparts (e.g., core_ed25519_add, core_ristretto255_SCALARBYTES).

• ed25519

• ristretto255

  Check "ristretto255_available" to see if this primitive can be used.

SEE ALSO

Crypt::Sodium::XS

Crypt::Sodium::XS::scalarmult

See this module for point-scalar multiplication with ed25519 and ristretto255.

Crypt::Sodium::XS::OO::curve25519

https://doc.libsodium.org/advanced/scalar_multiplication

https://doc.libsodium.org/advanced/point-arithmetic

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

• RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS

• IRC channel #sodium on irc.perl.org.

• Email the author directly.

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

Copyright (c) 2022 Brad Barden. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Crypt::Sodium::XS

perl -MCPAN -e shell
install Crypt::Sodium::XS