The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Crypt-NaCl-Sodium-1.0.8.0
River stage one • 1 direct dependent • 2 total dependents
/ Crypt::NaCl::Sodium::sign

NAME

Crypt::NaCl::Sodium::sign - Public-key signatures (Ed25519)

VERSION

version 1.0.8.0

SYNOPSIS

use Crypt::NaCl::Sodium qw( :utils );

my $crypto_sign = Crypt::NaCl::Sodium->sign();

my ($a_skey, $a_pkey, $a_key, $b_skey,
    $b_pkey, $b_key, $msg, $opened, $sealed);

## Alice
########

# Alice generates secret keypair
($a_pkey, $a_skey) = $crypto_sign->keypair();

# ... and shares the public key with Bob
send_to( Bob => { public_key => $a_pkey } );

# now Alice can sign her messages
# while Bob can verify that Alice has signed them

# a message to Bob
$msg = "Hi Bob!";

# Alice signs and seals the message using combined mode
$sealed = $crypto_sign->seal( $msg, $a_skey );

# message is ready for Bob
send_to( Bob => { sealed => $sealed } );

## Bob
########

# Bob generates his secret keypair
($b_pkey, $b_skey) = $crypto_sign->keypair();

# ... and shares his public key with Alice
send_to( Alice => { public_key => $b_pkey } );

# Bob receives the public key from Alice
$a_key = receive_for( Bob => 'public_key' );

# Bob is now ready to receive first message from Alice
$sealed = receive_for( Bob => 'sealed' );

# since Bob already has Alice's public key we have all information required
# to verify and open a message
$opened = $crypto_sign->open( $sealed, $a_key );

# now it is time to reply
$msg = "Hello Alice!";

# this time we use detached mode
$mac = $crypto_sign->mac( $msg, $b_skey );

# Alice needs both to verify Bob's message
send_to( Alice => { mac => $mac } );
send_to( Alice => { msg => $msg } );

## Alice
########

# Alice receives the public key from Bob
$b_key = receive_for( Alice => 'public_key' );

# Bob used the detached mode
$mac = receive_for( Alice => 'mac' );
$msg = receive_for( Alice => 'msg' );

# since we already have the message, all left to do is to verify that Bob
# indeed has sent it
unless ( $crypto_sign->verify($mac, $msg, $b_key) ) {
    die "Impostor alert!";
}

# NOTE: send_to() and receive_for() and user functions providing transport of
# messages

DESCRIPTION

crypto_sign system provides the public-key signature scheme for message signing and verification. It is designed to meet the standard notion of unforgeability under chosen-message attacks.

The crypto_sign allows public verifiability (or receiver-assisted public verifiability) - any holder of the message, MAC and the sender's public key can verify its authenticity.

METHODS

keypair

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

# or deterministically derived from a single key seed
my ($public_key, $secret_key) = $crypto_sign->keypair( $seed );

Helper method to generate a random secret key and corresponding public key to be used by $crypto_sign.

See "seed" for more details when generating key pair using given $seed.

The length of the $public_key equals "PUBLICKEYBYTES".

The length of the $secret_key equals "SECRETKEYBYTES".

NOTE: keep the secret key confidential.

Returns Data::BytesLocker objects.

public_key

my $public_key = $crypto_sign->public_key( $secret_key );

Computes the public key for corresponding secret key.

The length of the $public_key equals "PUBLICKEYBYTES".

Returns Data::BytesLocker objects.

seed

my $seed = $crypto_sign->seed();

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

Helper method to generate a random seed, that can be used to deterministically compute the key pair derived from it.

The length of the $seed equals "SEEDBYTES".

Returns Data::BytesLocker objects.

extract_seed

my $seed = $crypto_sign->extract_seed( $secret_key );

Returns the $seed extracted from given $secret_key. The seed is either random one or the one given to "keypair" method.

The length of the $seed equals "SEEDBYTES".

Returns Data::BytesLocker objects.

to_curve25519_keypair

my ($pkey_c25519, $skey_c25519) = $crypto_sign->to_curve25519_keypair(
                                    $public_key, $secret_key );

Ed25519 keys generated by "keypair" could be converted to Curve25519 keys, so that the same key pair can be used both for authenticated encryption crypto_box and for signatures crypto_sign.

The length of the $pkey_c25519 is equal to $crypto_box->PUBLICKEYBYTES.

The length of the $skey_c25519 is equal to $crypto_box->SECRETKEYBYTES.

NOTE: keep the secret key confidential.

Returns Data::BytesLocker objects.

seal

# combined mode - MAC and unencrypted message stored together
my $sealed = $crypto_sign->seal($msg, $secret_key);

Seals the plaintext message using given $secret_key.

The length of the $sealed is up to the length of $msg + "BYTES".

Returns Data::BytesLocker object.

mac

# detached mode - MAC of the message returned
my $mac = $crypto_sign->mac($msg, $secret_key);

Returns the MAC without attaching a copy of the original message to it.

The length of the $mac is up to the value of "BYTES".

Returns Data::BytesLocker object.

open

my $msg;
eval {
    $msg = $crypto_sign->open($sealed, $sender_public_key);
};
if ( $@ ) {
    warn "Message forged!";
} else {
    print "Verified message: $msg\n";
}

Verifies the signature of sealed message $sealed and extract the plaintext message out of it using sender's given $sender_public_key.

Function croaks if the verification fails.

The length of the $msg is equal to the length of $sealed - length of the prepended signature.

Returns Data::BytesLocker object.

verify

unless ( $crypto_sign->verify( $mac, $msg, $sender_public_key ) ) {
    die "Impostor alert!";
}

Verifies the integrity and authenticity of the $msg using given $mac and $sender_public_key.

Method returns true if message has been verified, false otherwise.

CONSTANTS

SECRETKEYBYTES

my $skey_length = $crypto_sign->SECRETKEYBYTES;

Returns the length of secret key.

PUBLICKEYBYTES

my $pkey_length = $crypto_sign->PUBLICKEYBYTES;

Returns the length of public key.

SEEDBYTES

my $seed_length = $crypto_sign->SEEDBYTES;

Returns the length of seed key.

BYTES

my $max_mac_length = $crypto_sign->BYTES;

Returns the maximum length of the MAC.

ALGORITHM DETAILS

crypto_sign is implemented using Ed25519, which has several attractive features: fast signing and verification, high security level comparable to AES-128, small keys and signatures, and is immune to side-channel attacks.

SEE ALSO

AUTHOR

Alex J. G. Burzyński <ajgb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Alex J. G. Burzyński <ajgb@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.