NAME
Crypt::Sodium::XS::sign - Asymmetric (public/secret key) signatures and verification
SYNOPSIS
use Crypt::Sodium::XS::sign ":default";
my ($pk, $sk) = sign_keypair();
my $msg = "this is a message";
my $signed_message = 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::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.
FUNCTIONS
Nothing is exported by default. A :default tag imports the functions and constants as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :ed25519 imports sign_ed25519_open. You should use at least one import tag.
sign_detached
my $signature = sign_detached($message, $my_secret_key);sign_init
my $multipart = sign_init();Returns a multipart sign object. See "MULTI-PART INTERFACE".
sign_keypair
my ($public_key, $secret_key) = sign_keypair();
my ($public_key, $secret_key) = sign_keypair($seed);$seed is optional. If provided, it must be "sign_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.
sign_open
my $message = sign_open($signed_message, $their_public_key);sign
my $signed_message = sign($message, $my_secret_key);sign_verify
my $is_valid = sign_verify($message, $signature, $their_public_key);Counterpart to sign_detached.
sign_sk_to_pk
my $public_key = sign_sk_to_pk($secret_key);Returns the public key from the secret key.
sign_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 FUNCTIONS
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 primitive-specific functions 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::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 "sign_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);CONSTANTS
sign_BYTES
my $signature_length = sign_BYTES();sign_MESSAGEBYTES_MAX
my $message_max_length = sign_MESSAGEBYTES_MAX();sign_PUBLICKEYBYTES
my $public_key_length = sign_PUBLICKEYBYTES();sign_SECRETKEYBYTES
my $secret_key_length = sign_SECRETKEYBYTES();sign_SEEDBYTES
my $seed_length = sign_SEEDBYTES();PRIMITIVES
All constants (except _PRIMITIVE) and functions have sign_<primitive>-prefixed counterparts (e.g., sign_ed25519_verify, sign_ed25519_BYTES).
NOTE: The multi-part interface uses a deterministic pre-hashing algorithm with ed25519, which is not the same as simply sign_ed25519(hash_sha512($message)). This module (unlike libsodium) exposes it with the consistent sign_ed25519_init name (no "ph").
ed25519
SEE ALSO
- Crypt::Sodium::XS
- Crypt::Sodium::XS::OO::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:
RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel
#sodiumonirc.perl.org.Email the author directly.
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.