/ 
File-SOPS-0.001
/ File::SOPS::Backend::Age

NAME

File::SOPS::Backend::Age - age encryption backend for SOPS

VERSION

version 0.001

SYNOPSIS

use File::SOPS::Backend::Age;

# Encrypt data key for recipients
my $encrypted_keys = File::SOPS::Backend::Age->encrypt_data_key(
    data_key   => $random_32_bytes,
    recipients => ['age1ql3z7hjy...', 'age1xyz...'],
);

# Decrypt data key
my $data_key = File::SOPS::Backend::Age->decrypt_data_key(
    age_keys   => $encrypted_keys,
    identities => ['AGE-SECRET-KEY-1...'],
);

# Check if can decrypt
if (File::SOPS::Backend::Age->can_decrypt(
    age_keys   => $encrypted_keys,
    identities => \@identities,
)) {
    # One of the identities can decrypt
}

DESCRIPTION

This module provides the age encryption backend for File::SOPS. It handles encrypting and decrypting the SOPS data key (32 random bytes) using age public/secret keys.

age (Actually Good Encryption) uses X25519 for key agreement and ChaCha20-Poly1305 for encryption.

The data key is encrypted separately for each recipient, allowing multiple people/systems to decrypt the same SOPS file.

encrypt_data_key

my $encrypted_keys = File::SOPS::Backend::Age->encrypt_data_key(
    data_key   => $random_32_bytes,
    recipients => \@age_public_keys,
);

Class method to encrypt a data key for multiple age recipients.

The data_key should be 32 random bytes (the AES-256 key used for value encryption).

The recipients parameter must be an ArrayRef of age public keys (e.g., age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p).

Returns an ArrayRef of HashRefs, each containing:

{
    recipient => 'age1...',
    enc       => '-----BEGIN AGE ENCRYPTED FILE-----...'
}

The encrypted data is PEM-armored for compatibility with the reference SOPS implementation.

decrypt_data_key

my $data_key = File::SOPS::Backend::Age->decrypt_data_key(
    age_keys   => $encrypted_keys,  # from metadata
    identities => \@age_secret_keys,
);

Class method to decrypt a data key using age identities.

The age_keys parameter should be an ArrayRef of encrypted key entries from the SOPS metadata (as returned by "encrypt_data_key").

The identities parameter must be an ArrayRef of age secret keys (e.g., AGE-SECRET-KEY-1QYQSZQGPQYQSZQGPQYQSZQGPQYQSZQGPQYQSZQGPQYQSZ...).

Tries each encrypted key until one can be decrypted with the provided identities.

Returns the decrypted data key (32 bytes) on success.

Dies if none of the identities can decrypt any of the encrypted keys.

can_decrypt

if (File::SOPS::Backend::Age->can_decrypt(
    age_keys   => $encrypted_keys,
    identities => \@identities,
)) {
    # Can decrypt
}

Class method to check if any of the provided identities can decrypt the data key.

Returns true if decryption is possible, false otherwise.

This is a non-throwing version of "decrypt_data_key".

SEE ALSO

SUPPORT

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.