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

NAME

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

SYNOPSIS

# TODO

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 :<primitive> import tag is provided for each of the primitives listed in "PRIMITIVES". These tags import the core_<primitive>_* functions and constants for that primitive. A :all tag imports everything.

Note: Crypt::Sodium::XS::curve25519 does provide generic functions for curve25519. Only the primitive-specific functions are available, so there is no :default tag.

Note: Functions are prefixed with core_ (not curve25519_) for consistency with libsodium function names.

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. Returns true if so, false otherwise.

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, $flags);

Returns a Crypt::Sodium::XS::MemVault: $comp so that $s + $comp = 1 (mod L).

core_<primitive>_scalar_mul

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

Returns a Crypt::Sodium::XS::MemVault: $x * $y (mod L).

core_<primitive>_scalar_negate

my $neg = core_ed25519_scalar_negate($s, $flags);

Returns a Crypt::Sodium::XS::MemVault: $neg so that $s + $neg = 0 (mod L).

core_<primitive>_scalar_random

Returns a Crypt::Sodium::XS::MemVault: a representation of a random scalar in the ]0..L[ interval.

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

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, $flags);

Returns a Crypt::Sodium::XS::MemVault: $s reduced 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, $flags);

Returns a Crypt::Sodium::XS::MemVault: $x - $y (mod L).

CONSTANTS

core_<primitive>_BYTES

my $element_size = core_ed25519_bytes;

Returns the size of points, in bytes.

core_<primitive>_SCALARBYTES

my $scalar_size = core_ed25519_SCALARBYTES;

Returns the size of scalars, in bytes.

core_ed25519_UNIFORMBYTES

my $uniform_input_size = core_ed25519_UNIFORMBYTES;

For ed25519 only; returns the size, in bytes, of input to the "ed25519_from_uniform" function.

core_ristretto255_HASHBYTES

my $hash_input_size = core_ristretto255_HASHBYTES;

For ristretto255 only; returns the size, in bytes, of input to the "core_ristretto255_from_hash" function.

PRIMITIVES

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

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:

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.