/ 
Crypt-Age-Simple-0.001
/ Crypt::Age::Simple::Encrypt

NAME

Crypt::Age::Simple::Encrypt - Streaming encrypter for Crypt::Age::Simple

SYNOPSIS

use Crypt::Age::Simple::Encrypt;

# initialize with scrypt of X25519 "recipients"
my $encrypter = Crypt::Age::Simple::Encrypt->new(
   recipients => { scrypt => $password },
);
my $encrypter = Crypt::Age::Simple::Encrypt->new(
   recipients => {
      scrypt => { password => $password, work_factor => 20},
   },
);
my $encrypter = Crypt::Age::Simple::Encrypt->new(
   recipients => { X25519 => $recipient_s },
);

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

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

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

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

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

DESCRIPTION

This module provides a streaming interface for age encryption (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".

recipients

my $rec = $self->recipients;

The recipients to use for encryption (technically, to wrap the file key).

Accepts:

  • Code reference. It is called with the randomly generated $file_key and it is supposed to provide back a reference to a scalar holding the whole header section of the age data (this does not inlcude the nonce for the binary data section).

  • Array reference (assumes X25519), holding a list of recipients (public 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.

For the scrypt type, the value provided can either be the password, or a reference to a hash holding two possible keys: password and work_factor. The latter represents the work factor as a base-2 logarithm (e.g. value 18 represents a scrypt work factor of 2^18).

is_complete

my $bool = $obj->is_complete;

Boolean value representing whether the encryption 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.

new

my $obj = Crypt::Age::Simple::Encrypt->new($recipients); # OR
my $obj = Crypt::Age::Simple::Encrypt->new(\%args); # OR
my $obj = Crypt::Age::Simple::Encrypt->new(%args); # OR
my $obj = Crypt::Age::Simple::Encrypt->new($recipients, %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 recipients key.

The following keys are valid:

  • recipients the recipient(s) used to wrap the file key, see "recipients". This argument is required.

get_chunks

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

Get at most $n available chunks of age 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.

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.