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

NAME

Crypt::Sodium::XS::OO::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::OO::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::OO::secretbox and Crypt::Sodium::XS::OO::aead.

CONSTRUCTOR

new

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

Returns a new kx object for the given primitive. If not given, the default primitive is default.

ATTRIBUTES

primitive

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

Gets or sets the primitive used for all operations by this object. Note this can be default.

METHODS

primitives

my @primitives = Crypt::Sodium::XS::OO::kx->primitives;
my @primitives = $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.

SEE ALSO

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