/ 
Crypt-Age-0.001
/ Crypt::Age::Header

NAME

Crypt::Age::Header - age file header parsing and generation

VERSION

version 0.001

SYNOPSIS

use Crypt::Age::Header;

# Create header for encryption
my $header = Crypt::Age::Header->create($file_key, \@recipient_public_keys);
my $header_text = $header->to_string;

# Parse header during decryption
my $offset = 0;
my $header = Crypt::Age::Header->parse(\$ciphertext, \$offset);

# Unwrap file key
my $file_key = $header->unwrap_file_key(\@identity_secret_keys);

DESCRIPTION

This module handles parsing and generation of age file headers.

An age file header is a text section at the beginning of an age file that contains:

  • Version line (age-encryption.org/v1)

  • One or more recipient stanzas (each wrapping the file key)

  • MAC footer (authenticates the header)

The header format is:

age-encryption.org/v1
-> X25519 <base64-ephemeral-public-key>
<base64-wrapped-file-key>
--- <base64-mac>

This is an internal module used by Crypt::Age.

stanzas

ArrayRef of Crypt::Age::Stanza objects representing recipient stanzas.

Each stanza wraps the file key for one recipient.

mac

The header MAC as raw bytes (32 bytes).

Used to authenticate the header and verify that the correct file key was unwrapped.

create

my $header = Crypt::Age::Header->create($file_key, \@recipients);

Creates a new header for encrypting to multiple recipients.

Parameters:

  • $file_key - The 16-byte file key to wrap

  • \@recipients - ArrayRef of Bech32-encoded public keys (age1...)

Returns a Crypt::Age::Header object with stanzas for each recipient and a computed MAC.

to_string

my $header_text = $header->to_string;

Serializes the header to text format.

Returns a string containing the version line, all stanzas, and the MAC footer, suitable for writing to the beginning of an age file.

parse

my $header = Crypt::Age::Header->parse(\$data, \$offset);

Parses an age header from encrypted data.

Parameters:

  • \$data - ScalarRef to the complete age file data

  • \$offset - ScalarRef to offset, updated to point past the header

Returns a Crypt::Age::Header object. The $offset is updated to point to the start of the payload.

Dies if the header format is invalid.

verify_mac

my $ok = $header->verify_mac($file_key);

Verifies that the header MAC is correct for the given file key.

Returns true if the MAC is valid, false otherwise. Used to confirm that the correct file key was unwrapped from a stanza.

unwrap_file_key

my $file_key = $header->unwrap_file_key(\@identities);

Attempts to unwrap the file key using one or more identities.

Parameters:

  • \@identities - ArrayRef of Bech32-encoded secret keys (AGE-SECRET-KEY-1...)

Tries each identity against each stanza until one successfully unwraps the file key and verifies the MAC. Returns the 16-byte file key.

Dies if no matching identity is found or if MAC verification fails.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-crypt-age/issues.

IRC

You can reach Getty on irc.perl.org for questions and support.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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