/ 
Crypt-Sodium-XS-0.000027
River stage zero No dependents
/ Crypt::Sodium::XS::OO::sign

NAME

Crypt::Sodium::XS::OO::sign - Asymmetric (public/secret key) signatures and verification

SYNOPSIS

use Crypt::Sodium::XS;

my $sign = Crypt::Sodium::XS->sign;

my ($pk, $sk) = $sign->keypair;
my $msg = "this is a message";

my $signed_message = $sign->sign($msg, $sk);
die "invalid signature" unless $sign->open($signed_message, $pk);

my $sig = $sign->detached($msg, $sk);
die "invalid signature" unless $sign->verify($msg, $sig, $pk);

my $multipart = $sign->init;
$multipart->update("this is");
$multipart->update(" a", " message");
$sig = $multipart->final_sign($sk);
$multipart = $sign->init;
$multipart->update($msg);
die "invalid signature" unless $multipart->final_verify($sig, $pk);

DESCRIPTION

With Crypt::Sodium::XS::OO::sign, a signer generates a key pair with:

a secret key

Used to append a signature to any number of messages.

a public key

Can be used by anybody to verify that the signature appended to a message was actually issued by the creator of the public key.

Verifiers need to already know and ultimately trust a public key before messages signed using it can be verified.

Warning: this is different from authenticated encryption. Appending a signature does not change the representation of the message itself.

CONSTRUCTOR

new

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

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

METHODS

PRIMITIVE

my $sign = Crypt::Sodium::XS::OO::sign->new;
my $default_primitive = $sign->PRIMITIVE;

BYTES

my $signature_length = $sign->BYTES;

MESSAGEBYTES_MAX

my $message_max_length = $sign->MESSAGEBYTES_MAX;

PUBLICKEYBYTES

my $public_key_length = $sign->PUBLICKEYBYTES;

SECRETKEYBYTES

my $secret_key_length = $sign->SECRETKEYBYTES;

SEEDBYTES

my $seed_length = $sign->SEEDBYTES;

primitives

my @primitives = $pwhash->primitives;

Returns a list of all supported primitive names (including 'default').

detached

my $signature = $sign->detached($message, $my_secret_key);

init

my $multipart = $sign->init;

Returns a multipart sign object. See "MULTI-PART INTERFACE".

keypair

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

$seed is optional. If provided, it must be "SEEDBYTES" in length. Using the same seed will generate the same key pair, so it must be kept confidential. If omitted, a key pair is randomly generated.

open

my $message = $sign->open($signed_message, $their_public_key);

sign

my $signed_message = $sign->sign($message, $my_secret_key);

verify

my $is_valid = $sign->verify($message, $signature, $their_public_key);

Counterpart to sign_detached.

sk_to_pk

my $public_key = $sign->sk_to_pk($secret_key);

Returns the public key from the secret key.

sk_to_seed

my $seed = $sign->sk_to_seed($secret_key);

Returns the seed that was used to create the secret key.

ed25519 to curve25519 METHODS

Ed25519 keys can be converted to X25519 keys, so that the same key pair can be used both for authenticated encryption (Crypt::Sodium::XS::box) and for signatures (Crypt::Sodium::XS::sign).

If you can afford it, using distinct keys for signing and for encryption is still highly recommended.

The following algorithm-specific methods perform these conversions:

pk_to_curve25519

my ($public_key, $secret_key) = $sign->keypair;
my $curve_public_key = $sign->ed25519_pk_to_curve25519($public_key);

sk_to_curve25519

my ($public_key, $secret_key) = $sign->keypair;
my $curve_secret_key = $sign->ed25519_pk_to_curve25519($secret_key);

to_curve25519

my ($public_key, $secret_key) = $sign->keypair;
my ($curve_pk, $curve_sk) $sign->to_curve25519($public_key, $secret_key);

MULTI-PART INTERFACE

If the message doesn’t fit in memory, then it can be provided as a sequence of arbitrarily-sized chunks.

This uses the Ed25519ph signature system, which pre-hashes the message. In other words, what gets signed is not the message itself but its image through a hash function.

If the message can fit in memory and be supplied as a single chunk, then the single-part API should be preferred.

Note: Ed25519ph(m) is intentionally not equivalent to Ed25519(SHA512(m)).

Because of this, signatures created with "sign_detached" cannot be verified with the multipart interface, and vice versa.

If, for some reason, you need to pre-hash the message yourself, then use the multi-part "Crypt::Sodium::XS::OO::generichash" APIs and sign the 512-bit output, preferably prefixed by your protocol name (or anything that will make the hash unique for a given use case).

A multipart sign object is created by calling the "init" method. Data to be signed or validated is added by calling the "update" method of that object as many times as desired. An output signature is generated by calling its "final_sign" method with a secret key, or signature verification is performed by calling "final_verify".

The multipart sign object is an opaque object which provides the following methods:

update

$multipart->update($message);
$multipart->update(@messages);

clone

my $multipart_copy = $multipart->clone;

final_sign

my $signature = $multipart->final_sign($my_secret_key);

final_verify

my $is_valid = $multipart->final_verify($signature, $their_public_key);

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::sign
https://doc.libsodium.org/public-key_cryptography/public-key_signatures
https://doc.libsodium.org/advanced/ed25519-curve25519

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.