/ 
File-SOPS-0.001
/ File::SOPS::Encrypted

NAME

File::SOPS::Encrypted - Parse and generate SOPS encrypted values

VERSION

version 0.001

SYNOPSIS

use File::SOPS::Encrypted;

# Parse an encrypted value string
my $enc = File::SOPS::Encrypted->parse(
    'ENC[AES256_GCM,data:xyz,iv:abc,tag:def,type:str]'
);

# Check if a string is encrypted
if (File::SOPS::Encrypted->is_encrypted($string)) {
    my $decrypted = $enc->decrypt_value(key => $data_key, aad => $path);
}

# Encrypt a value
my $enc = File::SOPS::Encrypted->encrypt_value(
    value => 'secret',
    key   => $data_key,
    aad   => 'database:password',
);

# Get encrypted string representation
my $string = $enc->to_string;
# => ENC[AES256_GCM,data:...,iv:...,tag:...,type:str]

DESCRIPTION

File::SOPS::Encrypted handles parsing and generation of SOPS encrypted value strings. Each encrypted value in a SOPS file is represented as:

ENC[AES256_GCM,data:base64,iv:base64,tag:base64,type:str]

Values are encrypted with AES-256-GCM using:

  • A shared data key (32 bytes, encrypted separately for each recipient)

  • A random initialization vector (IV) per value (12 bytes)

  • Additional Authenticated Data (AAD) derived from the value's path

  • Type preservation (str, int, float, bool, bytes)

algorithm

Encryption algorithm. Currently only AES256_GCM is supported. Defaults to AES256_GCM.

data

Encrypted ciphertext as raw bytes. Required.

iv

Initialization vector (IV) as raw bytes, 12 bytes for AES-GCM. Required.

tag

Authentication tag as raw bytes, 16 bytes for AES-GCM. Required.

type

Original value type for deserialization. One of: str, int, float, bool, bytes.

Defaults to str.

parse

my $enc = File::SOPS::Encrypted->parse($string);
# Returns undef if $string is not encrypted

Parses a SOPS encrypted value string.

Takes a string like ENC[AES256_GCM,data:...,iv:...,tag:...,type:str] and returns a File::SOPS::Encrypted object with decoded attributes.

Returns undef if the string is not in the encrypted format.

is_encrypted

if (File::SOPS::Encrypted->is_encrypted($string)) {
    # It's an encrypted value
}

Class method to check if a string is in SOPS encrypted format.

Returns true if the string matches the ENC[...] pattern.

to_string

my $string = $enc->to_string;
# => ENC[AES256_GCM,data:xyz==,iv:abc==,tag:def==,type:str]

Serializes the encrypted value to SOPS string format.

Returns a string representation with base64-encoded components.

encrypt_value

my $enc = File::SOPS::Encrypted->encrypt_value(
    value => 'secret',
    key   => $data_key,        # 32 bytes
    aad   => 'database:password',  # Additional Authenticated Data
    type  => 'str',            # optional, auto-detected
);

Class method to encrypt a value.

Encrypts a scalar value using AES-256-GCM with a random IV. Returns a File::SOPS::Encrypted object.

The aad (Additional Authenticated Data) is typically the path to the value in the data structure (e.g., database:password), used to prevent value substitution attacks.

Type is auto-detected from the value if not specified: int, float, bool, or str.

decrypt_value

my $value = $enc->decrypt_value(
    key => $data_key,  # 32 bytes
    aad => 'database:password',
);

Decrypts the encrypted value.

Returns the decrypted value with type conversion applied (int, float, bool are converted to appropriate Perl types).

Dies if authentication fails (wrong key, corrupted data, or mismatched AAD).

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.