/ 
Crypt-Age-Simple-0.001
/ Crypt::Age::Simple::Decrypt

NAME

Crypt::Age::Simple::Decrypt - Streaming decrypter for Crypt::Age::Simple

SYNOPSIS

use Crypt::Age::Simple::Decrypt;

# initialize with scrypt of X25519 "identities"
my $decrypter = Crypt::Age::Simple::Decrypt->new(
   identity => { scrypt => $password },
   max_header_size => 150, # standard size of a scrypt header
);
my $decrypter = Crypt::Age::Simple::Decrypt->new(
   identity => { X25519 => $identity },
);

# you can give data in as a plain scalar
$decrypter->pump($some_ciphertext_as_string);

# data out is in an array of references to scalars
my $aref = $decrypter->get_chunks;
my $cleartext = join '', { $$_ } $aref->@*;

# pump() works with scalar reference too, for minimal copying around
$decrypter->pump(\$some_ciphertext_as_reference);

# finish() marks the end of the ciphertext so that the last chunks
# can also be properly decrypted
$decrypter->finish;

# again, get_chunks gives back an array of scalar references
$cleartext .= join '', { $$_ } $decrypter->get_chunks->@*;

DESCRIPTION

This module provides a streaming interface for age decryption (see age).

INTERFACE

The interface is object-oriented. A typical usage is like this:

Methods:

finish

$obj->finish;

Mark the data provision as completed, i.e. no more "pump". It is necessary to call this method in order to get the final chunk from "get_chunks".

identity

my $id = $self->identity;

The identity to use for decryption (technically, to derive the file key).

Accepts:

  • Code reference. It is called with the parsed $header as the only input argument and it is supposed to return the file key.

  • Array reference (assumes X25519), holding a list of identities (private keys).

  • Plain scalar (assumes scrypt), holding a password.

  • Hash reference. It is assumed to only hold a key/value pair, the key being the type. Currently supported: scrypt, X25519, x25519. The value holds the corresponding input value.

is_complete

my $bool = $obj->is_complete;

Boolean value representing whether the decryption is complete or if it still has data to extract.

is_error

my $bool = $obj->is_error;

Boolean value representing if the object is in a state of error, e.g. for bad parsing or unmatched identities.

max_header_size

my $value = $obj->max_header_size;

Maximum size allowed for the header. Its value is set upon construction (see "new"). Setting a maximum value is a security measure against abuse.

new

my $obj = Crypt::Age::Simple::Decrypt->new($identity); # OR
my $obj = Crypt::Age::Simple::Decrypt->new(\%args); # OR
my $obj = Crypt::Age::Simple::Decrypt->new(%args); # OR
my $obj = Crypt::Age::Simple::Decrypt->new($identity, %args);

Constructor.

Arguments can be passed as a hash reference or a list of key/value pairs. If the list of arguments holds an odd number of elements, the first is considered associated to the identity key.

The following keys are valid:

  • identity the identity used to unwrap the file key, see "identity". This argument is required.

  • max_header_size the maximum size allowed for the header, as a security measure. See also accessor "max_header_size".

get_chunks

my $aref = $obj->get_chunks; # OR
my $aref = $obj->get_chunks($n);

Get at most $n available chunks of decrypted data, or all of them if $n is missing or otherwise false.

Dies if the object is in a state of error.

Returns an array reference holding scalar references, pointing to the decrypted data.

has_header

my $bool = $obj->has_header;

Boolean test to check if the header has already been parsed or not.

my $header = $obj->header;

The parsed header, if already available.

pump

$obj->pump($scalar); # OR
$obj->pump(\$scalar); # OR
$obj->pump(\@array_of_scalar_refs);

Add data to the object. Depending on what you have, you can pass it as scalar, ref to scalar, or ref to an array holding scalar refs.

After passing the final part of the data make sure to call "finish" or "get_chunks" will never give you back the last chunk of decrypted plaintext.

BUGS AND LIMITATIONS

Minimum perl version 5.24.

SEE ALSO

AUTHOR

Flavio Poletti <flavio@polettix.it>

COPYRIGHT AND LICENSE

Copyright 2026 by Flavio Poletti <flavio@polettix.it>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.