/ 
Crypt-Sodium-XS-0.000039
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::kx ":default";

# 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.

FUNCTIONS

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);

$seed is optional. It must be "kx_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 "kx_PUBLICKEYBYTES" bytes and a Crypt::Sodium::XS::MemVault: the secret key of "kx_SECRETKEYBYTES" bytes.

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);

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

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

$server_pk is a public key. It must be "kx_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 "kx_SECRETKEYBYTES" bytes intended for decrypting on the client side, and a secret key of "kx_SECRETKEYBYTES" intended for encrypting on the client side.

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);

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

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

$client_pk is a public key. It must be "kx_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 "kx_SECRETKEYBYTES" bytes intended for decrypting on the server side, and a secret key of "SECRETKEYBYTES" intended for encrypting on the server side.

CONSTANTS

kx_PRIMITIVE

my $default_primitive = kx_PRIMITIVE();

Returns the name of the default primitive.

kx_PUBLICKEYBYTES

kx_<primitive>_PUBLICKEYBYTES

my $public_key_length = kx_PUBLICKEYBYTES();

The size, in bytes, of a public key.

kx_SECRETKEYBYTES

kx_<primitive>_SECRETKEYBYTES

my $secret_key_length = kx_SECRETKEYBYTES();

The size, in bytes, of a secret key.

kx_SEEDBYTES

kx_<primitive>_SEEDBYTES

my $seed_length = kx_SEEDKEYBYTES();

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

kx_SESSIONKEYBYTES

kx_<primitive>_SESSIONKEYBYTES

my $session_key_length = kx_SESSIONKEYBYTES();

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

PRIMITIVES

All constants (except _PRIMITIVE) and functions have kx_<primitive>-prefixed couterparts (e.g., kx_x25519blake2b_keypair, kx_x25519blake2b_PUBLICKEYBYTES).

  • x25519blake2b (default)

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::OO::kx
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.