/ 
DBIx-Squirrel-1.5.5-TRIAL
River stage zero No dependents
/ DBIx::Squirrel::Crypt::Fernet

NAME

DBIx::Squirrel::Crypt::Fernet

SYNOPSIS

#############################
# Object-oriented Interface #
#############################

# Import the helper
use DBIx::Squirrel::Crypt::Fernet 'Fernet';

# Generate random key
$fernet = Fernet();

# Use pre-defined Base64-encoded key
$fernet = Fernet($key);

# Import nothing
use DBIx::Squirrel::Crypt::Fernet;

# Generate random key
$fernet = DBIx::Squirrel::Crypt::Fernet->new();

# Use pre-defined Base64-encoded key
$fernet = DBIx::Squirrel::Crypt::Fernet->new($key);

# Encrypt message
$token = $fernet->encrypt($message);

# Decrypt token
$message = $fernet->decrypt($token);

# Verify token
$bool = $fernet->verify($token);

# Decrypt token, check time-to-live (secs) has not expired
$message = $fernet->decrypt($token, $ttl);

# Verify token, check time-to-live (secs) has not expired
$bool = $fernet->verify($token, $ttl);

# Retrieve Base64-encoded key
$key = $fernet->to_string();
$key = "$fernet";

######################
# Exported functions #
######################

# Import functions
use DBIx::Squirrel::Crypt::Fernet qw(
    generatekey
    encrypt
    decrypt
    verify
);

# Import Crypt::Fernet-like interface
use DBIx::Squirrel::Crypt::Fernet qw(
    fernet_genkey
    fernet_encrypt
    fernet_decrypt
    fernet_verify
);

# Generate a Base64-encoded random key
$key = generatekey();
$key = fernet_genkey();

# Encrypt message
$token = encrypt($key, $message);
$token = fernet_encrypt($key, $message);

# Decrypt token
$message = decrypt($key, $token);
$message = fernet_decrypt($key, $token);

# Verify token
$bool = verify($key, $token);
$bool = fernet_verify($key, $token);

# Decrypt token, check time-to-live (secs) has not expired
$message = decrypt($key, $token, $ttl);
$message = fernet_decrypt($key, $token, $ttl);

# Verify token, check time-to-live (secs) has not expired
$bool = verify($key, $token, $ttl);
$bool = fernet_verify($key, $token, $ttl);

DESCRIPTION

Fernet takes a user-provided message (an arbitrary sequence of bytes), a 256-bit key, and the current time, and it produces a token containing the message in a form that can't be read or altered without the key.

See https://github.com/fernet/spec/blob/master/Spec.md for more detail.

METHODS

new

$obj = DBIx::Squirrel::Crypt::Fernet->new();
$obj = DBIx::Squirrel::Crypt::Fernet->new($key);

A constructor (also see Fernet).

If no arguments are passed then a random 32-byte Fernet key is generated. If a Base64-encoded key is passed then it will be decoded and its signing and encryption key fields extracted.

Take care never to display the binary signing and extraction keys, but to use the to_string method (or stringification) to recombine them into a Base64- encoded Fernet key.

generatekey

$key = $obj->generatekey();
$key = DBIx::Squirrel::Crypt::Fernet->generatekey();

Returns a Base64-encoded randomly-generated key.

encrypt

$token = $obj->encrypt($message);

Encrypts a message, returning a Base64-encode token.

decrypt

$message = $obj->decrypt($token);
$message = $obj->decrypt($token, $ttl);

Returns the decrypted message, or undef if the token could not be decrypted. If a time-to-live (seconds) is specified ($ttl) then a further check is made to ensure that the token has not expired.

verify

$bool = $obj->verify($token);
$bool = $obj->verify($token, $ttl);

Returns true if the token was signed using the same signing key as that embedded in the Fernet key. If a time-to-live (seconds) is specified ($ttl) then a further check is made to ensure that the token has not expired.

to_string

$key = $obj->to_string();
$key = "$obj";

Returns the Base64-encoded key.

EXPORTS

This package exports nothing by default.

Fernet

$obj = Fernet();
$obj = Fernet($key);

Alternative constructor (also see new).

Returns a new DBIx::Squirrel::Crypt::Fernet object.

If no arguments are passed then a random 32-byte Fernet key is generated. If a Base64-encoded key is passed then it will be decoded and its signing and encryption key fields extracted.

Take care never to display the binary signing and extraction keys, but to use the to_string method (or stringification) to recombine them into a Base64- encoded Fernet key.

generatekey

$key = generatekey();

Returns a Base64-encoded randomly-generated key.

encrypt

$token = encrypt($key, $message);

Encrypts a message, returning a Base64-encode token.

While a Base64-encoded key may be passed as the first argument, it would be more efficient to call the "two-faced" encrypt as a method on a Fernet object to avoid the repeated overhead of decoding and parsing-out the signing and encryption keys.

decrypt

$message = decrypt($key, $token);
$message = decrypt($key, $token, $ttl);

Returns the decrypted message, or undef if the token could not be decrypted. If a time-to-live (seconds) is specified ($ttl) then a further check is made to ensure that the token has not expired.

While a Base64-encoded key may be passed as the first argument, it would be more efficient to call the "two-faced" decrypt as a method on a Fernet object to avoid the repeated overhead of decoding and parsing-out the signing and encryption keys.

verify

$bool = verify($key, $token);
$bool = verify($key, $token, $ttl);

Returns true if the token was signed using the same signing key as that embedded in the Fernet key. If a time-to-live (seconds) is specified ($ttl) then a further check is made to ensure that the token has not expired.

While a Base64-encoded key may be passed as the first argument, it would be more efficient to call the "two-faced" verify as a method on a Fernet object to avoid the repeated overhead of decoding and parsing-out the signing and encryption keys.

LEGACY Crypt::Fernet INTERFACE

At the time I wanted to use Wan Leung Wong's Crypt::Fernet package, it had a few testing failures and would not build. I'm pretty sure the Crypt::CBC dependency introduced a breaking change. I did submit a fix, but deployment and communication have been problematic. It has probably been fixed by now, but I have decided to rework the original package, extend the interface, and have kept this namespace active. Nevertheless, the lion's share of the credit should go to the author of the original work.

The original Crypt::Fernet package exported four functions as its primary public interface, and this package does the same on request:

  • fernet_decrypt

  • fernet_genkey

  • fernet_encrypt

  • fernet_verify

fernet_genkey

$key = fernet_genkey();

Returns a Base64-encoded randomly-generated key.

fernet_encrypt

$token = fernet_encrypt($key, $message);

Encrypts a message, returning a Base64-encode token.

fernet_decrypt

$message = fernet_decrypt($key, $token);
$message = fernet_decrypt($key, $token, $ttl);

Returns the decrypted message, or undef if the token could not be decrypted. If a time-to-live (seconds) is specified ($ttl) then a further check is made to ensure that the token has not expired.

fernet_verify

$bool = fernet_verify($key, $token);
$bool = fernet_verify($key, $token, $ttl);

Returns true if the token was signed using the same signing key as that embedded in the Fernet key. If a time-to-live (seconds) is specified ($ttl) then a further check is made to ensure that the token has not expired.

AUTHORS

Iain Campbell <cpanic@cpan.org>

This is a rewrite of Crypt::Fernet, so credit for that original work belongs to Wan Leung Wong <wanleung@linkomnia.com>.

COPYRIGHT AND LICENSE

The DBIx::Squirrel module is Copyright (c) 2020-2025 Iain Campbell. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl 5.10.0 README file.

SUPPORT / WARRANTY

DBIx::Squirrel is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.