/ 
Crypt-Sodium-XS-0.000028
River stage zero No dependents
/ Crypt::Sodium::XS::scalarmult

NAME

Crypt::Sodium::XS::scalarmult - Point-scalar multiplication on the Curve25519 curve.

SYNOPSIS

use Crypt::Sodium::XS::scalarmult ':default';
use Crypt::Sodium::XS 'sodium_random_bytes';

my $keysize = Crypt::Sodium::XS->box->SECRETKEYBYTES;
my $client_sk = sodium_random_bytes($keysize);
my $client_pk = scalarmult_base($client_sk);
my $server_sk = sodium_random_bytes($keysize);
my $server_pk = scalarmult_base($client_sk);

# !!! do not use output directly for key exchange; use Crypt::Sodium::XS::kx.
# if you really want to, you can manually do this:

use Crypt::Sodium::XS::generichash 'generichash_init';

# client side:
my $q = scalarmult($client_sk, $server_pk);
my $hasher = generichash_init();
$hasher->update($q, $client_pk, $server_pk);
my $client_shared_secret = $hasher->final;

# server side:
my $q = scalarmult($server_sk, $client_pk);
my $hasher = generichash_init();
$hasher->update($q, $client_pk, $server_pk);
my $server_shared_secret = $hasher->final;

# $client_shared_secret and $server_shared_secret are now identical keys.

DESCRIPTION

Crypt::Sodium::XS::scalarmult provides an API to multiply a point on the Curve25519 curve.

This can be used as a building block to construct key exchange mechanisms, or more generally to compute a public key from a secret key. For key exchange, you generally want to use Crypt::Sodium::XS::kx instead.

FUNCTIONS

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

scalarmult_keygen

my $secret_key = scalarmult_keygen();

Generates a new random secret key. Returns $secret_key as a Crypt::Sodium::XS::MemVault.

scalarmult_base

my $public_key = scalarmult_base($secret_key);

Given a user’s $secret_key, return the user’s public key.

Multiplies the base point (x, 4/5) by a scalar $secret_key (clamped) and returns the Y coordinate of the resulting point.

NOTE: With the ed25519 primitive, a $secret_key of 0 will croak.

scalarmult

my $q = scalarmult($my_secret_key, $their_public_key);

This function can be used to compute a shared secret $q given a user’s $my_secret_key and another user’s $their_public_key.

NOTE:

$q represents the X coordinate of a point on the curve. As a result, the number of possible keys is limited to the group size (≈2^252), which is smaller than the key space.

For this reason, and to mitigate subtle attacks due to the fact many (p, n) pairs produce the same result, using the output of the multiplication q directly as a shared key is not recommended.

A better way to compute a shared key is h(q | pk1 | pk2), with pk1 and pk2 being the public keys.

By doing so, each party can prove what exact public key they intended to perform a key exchange with (for a given public key, 11 other public keys producing the same shared secret can be trivially computed).

See "SYNOPSIS" for an example of this.

ed225519 notes ($secret_key is 'n', $public_key is 'p'):

NOTE: With the ed25519 primitive, this function will croak if $my_secret_key is 0 or if $their_public_key is not on the curve, not on the main subgroup, is a point of small order, or is not provided in canonical form.

Also with ed25519, $my_secret_key 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).

ed25519 SCALAR MULTIPLICATION WITHOUT CLAMPING

This section applies to primitive ed25519 only.

In order to prevent attacks using small subgroups, the scalarmult functions above clear lower bits of the scalar ($secret_key). This may be indesirable to build protocols that requires $secret_key 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.

These functions are only available for the ed25519 primitive.

scalarmult_ed25519_base_noclamp

scalarmult_ed25519_noclamp

CONTSANTS

scalarmult_BYTES

my $public_key_length = scalarmult_BYTES();

scalarmult_SCALARBYTES

my $shared_and_secret_key_length = scalarmult_SCALARBYTES();

PRIMITIVES

All functions have scalarmult_<primitive>-prefixed couterparts (e.g., scalarmult_ed25519_base, scalarmult_).

x25519 (default)

X25519 (ECDH over Curve25519). See RFC 7748.

ed25519

Low-level edwards25519 curve. Only to be used for creating custom constructions.

ristretto255

Ristretto is a new unified point compression format for curves over large-characteristic fields, which divides the curve’s cofactor by 4 or 8 at very little cost of performance, efficiently implementing a prime-order group.

libsodium 1.0.18+ implements ristreto255: ristretto on top of the Curve25519 curve.

Compared to Curve25519 points encoded as their coordinates, ristretto makes it easier to safely implement protocols originally designed for prime-order groups.

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::OO::scalarmult
https://doc.libsodium.org/advanced/scalar_multiplication
https://doc.libsodium.org/advanced/point-arithmetic

See 'Scalar Multiplication' for ed25519.

FEEDBACK

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

For any security sensitive reports, please email the author directly or contact privately via IRC.

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.