/ 
Crypt-Sodium-XS-0.001000
River stage zero No dependents
/ Crypt::Sodium::XS::kx

NAME

Crypt::Sodium::XS::kx - Shared key derivation from client/server asymmetric key pairs

SYNOPSIS

use Crypt::Sodium::XS;
my $kx = Crypt::Sodium::XS->kx;

# client
my ($client_pk, $client_sk) = $kx->keypair;
my ($server_pk, $server_sk) = $kx->keypair;

# client must have server's public key
# shared keys for server->client (client_rx) and client->server (client_tx)
my ($client_rx, $client_tx)
  = $kx->client_session_keys($client_pk, $client_sk, $server_pk);

# server must have client's public key
# shared keys for client->server (server_rx) and server->client (server_tx)
my ($server_rx, $server_tx)
  = $kx->client_session_keys($server_pk, $server_sk, $client_pk);

DESCRIPTION

Using Crypt::Sodium::XS::kx, two parties can securely compute a set of shared keys using their peer's public key and their own secret key.

One party must act as the "client" side of communications. The other party must act as the "server" side of communications.

The shared keys can be used used with symmetric encryption protocols such as Crypt::Sodium::XS::secretbox and Crypt::Sodium::XS::aead.

CONSTRUCTOR

The constructor is called with the Crypt::Sodium::XS->kx method.

my $kx = Crypt::Sodium::XS->kx;
my $kx = Crypt::Sodium::XS->kx(primitive => 'x25519blake2b');

Returns a new kx object.

Implementation detail: the returned object is blessed into Crypt::Sodium::XS::OO::kx.

ATTRIBUTES

primitive

my $primitive = $kx->primitive;
$kx->primitive('x25519blake2b');

Gets or sets the primitive used for all operations by this object. It must be one of the primitives listed in "PRIMITIVES", including default.

METHODS

primitives

my @primitives = $kx->primitives;
my @primitives = Crypt::Sodium::XS::kx->primitives;

Returns a list of all supported primitive names, including default.

Can be called as a class method.

PRIMITIVE

my $primitive = $kx->PRIMITIVE;

Returns the primitive used for all operations by this object. Note this will never be default but would instead be the primitive it represents.

keypair

my ($public_key, $secret_key) = $kx->keypair($seed, $flags);

$seed is optional. It must be "SEEDBYTES" in length. It may be a Crypt::Sodium::XS::MemVault. Using the same seed will generate the same key pair, so it must be kept confidential. If omitted, a key pair is randomly generated.

$flags is optional. It is the flags used for the $secret_key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.

Returns a public key of "PUBLICKEYBYTES" bytes and a Crypt::Sodium::XS::MemVault: the secret key of "SECRETKEYBYTES" bytes.

client_session_keys

my ($client_rx, $client_tx)
  = $kx->client_session_keys($client_pk, $client_sk, $server_pk, $flags);

$client_pk is a public key. It must be "PUBLICKEYBYTES" bytes.

$client_sk is a secret key. It must be "SECRETKEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$server_pk is a public key. It must be "PUBLICKEYBYTES" bytes.

$flags is optional. It is the flags used for both the $client_rx and $client_tx Crypt::Sodium::XS::MemVaults. See Crypt::Sodium::XS::ProtMem.

Returns two Crypt::Sodium::XS::MemVaults: a secret key of "SECRETKEYBYTES" bytes intended for decrypting on the client side, and a secret key of "SECRETKEYBYTES" intended for encrypting on the client side.

server_session_keys

my ($server_rx, $server_tx)
  = $kx->client_session_keys($server_pk, $server_sk, $client_pk, $flags);

$server_pk is a public key. It must be "PUBLICKEYBYTES" bytes.

$server_sk is a secret key. It must be "SECRETKEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$client_pk is a public key. It must be "PUBLICKEYBYTES" bytes.

$flags is optional. It is the flags used for both the $server_rx and $server_tx Crypt::Sodium::XS::MemVaults. See Crypt::Sodium::XS::ProtMem.

Returns two Crypt::Sodium::XS::MemVaults: a secret key of "SECRETKEYBYTES" bytes intended for decrypting on the server side, and a secret key of "SECRETKEYBYTES" intended for encrypting on the server side.

PUBLICKEYBYTES

my $public_key_length = $kx->PUBLICKEYBYTES;

The size, in bytes, of a public key.

SECRETKEYBYTES

my $secret_key_length = $kx->SECRETKEYBYTES;

The size, in bytes, of a secret key.

SEEDBYTES

my $seed_length = $kx->SEEDKEYBYTES;

The size, in bytes, of a seed used by "keypair".

SESSIONKEYBYTES

my $session_key_length = $kx->SESSIONKEYBYTES;

The size, in bytes, of a secret shared session key.

PRIMITIVES

  • x25519blake2b (default)

FUNCTIONS

The object API above is the recommended way to use this module. The functions and constants documented below can be imported instead or in addition.

Nothing is exported by default. A :default tag imports the functions and constants documented below. A separate :<primitive> import tag is provided for each of the primitives listed in "PRIMITIVES". These tags import the kx_<primitive>_* functions and constants for that primitive. A :all tag imports everything.

kx_keypair

kx_<primitive>_keypair

my ($public_key, $secret_key) = kx_keypair($seed, $flags);

Same as "keypair".

kx_client_session_keys

kx_<primitive>_client_session_keys

my ($client_rx, $client_tx)
  = kx_client_session_keys($client_pk, $client_sk, $server_pk, $flags);

Same as "client_session_keys".

kx_server_session_keys

kx_<primitive>_server_session_keys

my ($server_rx, $server_tx)
  = kx_client_session_keys($server_pk, $server_sk, $client_pk, $flags);

Same as "server_session_keys".

CONSTANTS

kx_PRIMITIVE

my $default_primitive = kx_PRIMITIVE();

Returns the name of the default primitive.

kx_PUBLICKEYBYTES

kx_<primitive>_PUBLICKEYBYTES

Same as "PUBLICKEYBYTES".

kx_SECRETKEYBYTES

kx_<primitive>_SECRETKEYBYTES

my $secret_key_length = kx_SECRETKEYBYTES();

Same as "SECRETKEYBYTES".

kx_SEEDBYTES

kx_<primitive>_SEEDBYTES

my $seed_length = kx_SEEDKEYBYTES();

Same as "SEEDBYTES".

kx_SESSIONKEYBYTES

kx_<primitive>_SESSIONKEYBYTES

my $session_key_length = kx_SESSIONKEYBYTES();

Same as "SESSIONKEYBYTES".

SEE ALSO

Crypt::Sodium::XS
https://doc.libsodium.org/key_exchange

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.