Crypt::Curve25519(3)

πŸ“¦
version 0.08 Β· 4 versions
, in fedora 43

πŸ’– Crypt::Curve25519 πŸ’–

okay bestie, welcome to Crypt::Curve25519, a lil Perl module from the User Contributed Perl Documentation section of the manual. what it does? it generates a shared secret using the elliptic-curve Diffie-Hellman function. yes, that kind of secret. the "we can whisper in class and nobody else understands us" kind. πŸ”βœ¨

🌸 SYNOPSIS 🌸

here's the whole vibe, copy-paste ready, no cap:

use Crypt::Curve25519;

# Alice:
my $alice_secret_key = curve25519_secret_key(random_32_bytes());
my $alice_public_key = curve25519_public_key( $alice_secret_key );

# Bob:
my $bob_secret_key = curve25519_secret_key(random_32_bytes());
my $bob_public_key = curve25519_public_key( $bob_secret_key );

# Alice and Bob exchange their public keys
my $alice_public_key_hex = unpack('H64', $alice_public_key);
my $bob_public_key_hex   = unpack('H64', $bob_public_key);

# Alice calculates shared secret to communicate with Bob
my $shared_secret_with_bob = curve25519_shared_secret(
    $alice_secret_key,
    pack('H64', $bob_public_key_hex)
);

# Bob calculates shared secret to communicate with Alice
my $shared_secret_with_alice = curve25519_shared_secret(
    $bob_secret_key,
    pack('H64', $alice_public_key_hex)
);

# Shared secrets are equal
die "Something horrible has happend!"
  unless $shared_secret_with_bob eq $shared_secret_with_alice;

so Alice and Bob both end up with the same secret and nobody eavesdropping gets to know it. it's giving main character energy for both of them simultaneously. πŸ‘‘

this package provides also a simplified OO interface, for when you want your code to be a lil more put-together:

use Crypt::Curve25519 ();

my $c = Crypt::Curve25519->new();

# Alice:
my $alice_secret_key_hex = $c->secret_key(random_hexencoded_32_bytes());
my $alice_public_key_hex = $c->public_key( $alice_secret_key_hex );

# Bob:
my $bob_secret_key_hex = $c->secret_key(random_hexencoded_32_bytes());
my $bob_public_key_hex = $c->public_key( $bob_secret_key_hex );

# Alice and Bob exchange their public keys

# Alice calculates shared secret to communicate with Bob
my $shared_secret_with_bob_hex = $c->shared_secret(
                                $alice_secret_key_hex,
                                $bob_public_key_hex);

# Bob calculates shared secret to communicate with Alice
my $shared_secret_with_alice_hex = $c->shared_secret(
                                $bob_secret_key_hex,
                                $alice_public_key_hex);

# Shared secrets are equal
die "Something horrible has happend!"
  unless $shared_secret_with_bob_hex eq $shared_secret_with_alice_hex;

and here are example functions to generate a pseudo-random private secret key, because the module hands you the math and you gotta bring your own randomness, bestie:

sub random_32_bytes {
    return join('', map { chr(int(rand(255))) } 1 .. 32);
}

sub random_hexencoded_32_bytes {
   return unpack('H64', random_32_bytes());
}
⚠️ heads up: these are example functions for generating a pseudo-random private secret key. they're here to show you the shape of the thing, not to be your crypto. πŸ”₯

✨ DESCRIPTION ✨

Curve25519 is a state-of-the-art Diffie-Hellman function suitable for a wide variety of applications. it's iconic, it's modern, it's the moment. πŸ’…

so here's the tea. given a user's 32-byte secret key, Curve25519 computes the user's 32-byte public key. given the user's 32-byte secret key and another user's 32-byte public key, Curve25519 computes a 32-byte secret shared by the two users. that shared secret can then be used to authenticate and encrypt messages between the two users. πŸ¦‹

literally the entire plot. two people, two keypairs, one secret. no cap.

πŸŽ€ METHODS πŸŽ€

πŸ’œ curve25519_secret_key

my $my_secret_key = curve25519_secret_key($my_random_32byte_string);

using a provided 32-byte random string from a cryptographically safe source, create a masked secret key. so please, for the love of everything, make that string actually come from a cryptographically safe source. πŸ™ˆ

πŸ’œ curve25519_public_key

my $public_key = curve25519_public_key($my_secret_key);

using a masked secret key, generate the corresponding 32-byte Curve25519 public key. this is the one you can show off, post it, share it, it's fine. ✨

πŸ’œ curve25519_shared_secret

my $shared_secret = curve25519_shared_secret(
    $my_secret_key, $his_public_key
);

using the provided keys, generate a 32-byte shared secret that both parties can use without disclosing their private secret keys. both of you get the same secret, neither of you has to show your private one. mutual trust, mutual secrecy, we love to see it. 🫢

πŸ’œ curve25519

access to the primitive function is also provided, for the ones who like to go straight to the source:

use Crypt::Curve25519 'curve25519';

my $key = curve25519($my_secret_key, $basepoint);

# public key
if ( $basepoint eq pack('H64', '09') ) {
    print "\$key is a public key\n";
}
elsif ( $basepoint eq $his_public_key ) {
    print "\$key is a shared secret\n";
}

using the provided secret key and depending on the 32-byte basepoint, generate a 32-byte public key or shared secret. same function, two moods. πŸ‘‘

πŸ’œ new

my $c = Crypt::Curve25519->new();

create a new object. that's it, that's the whole method, she's simple and she's slaying. πŸ’…

πŸ’œ secret_key

my $my_secret_key_hex = $c->secret_key( $my_random_32byte_string_hex );

using a hex encoded 32-byte random string from a cryptographically safe source, create a masked secret key. yes, hex encoded this time, keep up bestie. 🌸

πŸ’œ public_key

my $public_key_hex = $c->public_key( $my_secret_key_hex );

using a hex encoded masked secret key, generate the corresponding hex encoded 32-byte Curve25519 public key. ✨

πŸ’œ shared_secret

my $shared_secret_hex = $c->shared_secret(
    $my_secret_key_hex, $his_public_key_hex
);

using the provided hex encoded keys, generate a 32-byte hex encoded shared secret that both parties can use without disclosing their private secret keys. again: shared secret goes to both of you, private keys stay private. periodt. πŸ’–

πŸ’œ generate

access to the primitive method is also provided:

my $key_hex = $c->generate($my_secret_key_hex, $basepoint_hex);

# public key
if ( $basepoint_hex eq unpack("H64", pack("H64", "09")) ) {
    print "\$key_hex is a public key\n";
}
elsif ( $basepoint_hex eq $his_public_key_hex ) {
    print "\$key_hex is a shared secret\n";
}

using the provided hex encoded secret key and depending on the 32-byte hex encoded basepoint, generate a 32-byte hex encoded public key or shared secret. the OO version of the primitive, matching energy, matching vibes. πŸ¦‹

🌈 SEE ALSO 🌈

go read it, it's the source of the whole legend. iykyk. πŸ“š

πŸ‘‘ AUTHOR πŸ‘‘

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

πŸ‘‘ MAINTAINER πŸ‘‘

Dmitry Karasik <dmitry@karasik.eu.org>

This software is copyright (c) 2014 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.

so yeah, copyright (c) 2014 belongs to Alex J. G. BurzyΕ„ski <ajgb@cpan.org>, and it's free software β€” redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. πŸ’œ

and that's the whole page, bestie!! this was documented with perl v5.42.0 on 2025-07-25, so if you're reading this from the future, hi, hope your keys are still safe. stay encrypted, stay iconic, mwah πŸ’…πŸ’–βœ¨

πŸ“¦ where this page comes from