/ 
Crypt-Sodium-XS-0.000029
River stage zero No dependents
/ Crypt::Sodium::XS::OO::curve25519

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.

CONSTRUCTOR

new

my $curve25519 = Crypt::Sodium::XS::OO::curve25519->new(primitive => 'ed25519');
my $curve25519 = Crypt::Sodium::XS->curve25519(primitive => 'ristretto255');

Returns a new curve25519 object for the given primitive. The primitive argument is required.

ATTRIBUTES

primitive

my $primitive = $curve25519->primitive;
$curve25519->primitive('aegis256');

The primitive used for all operations by this object.

METHODS

Scalar arithmetic over L

The scalar_* and methods 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

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

PRIMITIVE

my $primitive = $aead->PRIMITIVE;

BYTES

Size of points, in bytes.

SCALARBYTES

Size of scalars, in bytes.

UNIFORMBYTES

For ed25519 only; input size to the "from_uniform" method.

HASHBYTES

For ristretto255 only; input size to the "from_hash" method.

primitives

add

my $r = $curve25519->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.

is_valid_point

my $is_valid = $curve25519->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.

random

my $point = $curve25519->random;

Returns the representation of a random group element.

from_uniform

core_ristretto255_from_hash

$curve25519->primitve('ed25519');
my $vector = sodium_random_bytes($curve25519->UNIFORMBYTES);
my $point = $curve25519->from_uniform($vector);
$curve25519->primitive('ristretto255');
my $vector2 = sodium_random_bytes($curve25519->HASHBYTES);
my $point2 = $curve25519->from_hash($vector);

NOTE: Different methods 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.

scalar_add

my $r = $curve25519->add($p, $q);

Adds the point $p to the point $q.

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

core_ed25519_sub

my $point = $curve25519->sub($p, $q);

Subtracts the point $q from the point $p.

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

scalar_complement

my $comp = $curve25519->scalar_complement($s);

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

scalar_mul

my $z = $curve25519->scalar_mul($x, $y);

Returns $x * $y (mod L).

scalar_negate

my $neg = $curve25519->scalar_negate($s);

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

scalar_random

my $r = $curve25519->scalar_random;

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

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

scalar_reduce

my $r = $curve25519->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.

scalar_sub

my $z = $curve25519->scalar_sub($x, $y);

Returns $x - $y (mod L).

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::scalarmult

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

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:

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.