Tie::E...edHash(3pm)

🌸 NAME 🌸

Tie::EncryptedHash — bestie, it's hashes (and objects based on hashes) with encrypting fields. 💖

---

✨ SYNOPSIS ✨

use Tie::EncryptedHash;

my %s = ();
tie %s, Tie::EncryptedHash, 'passwd';

$s{foo}  = "plaintext";     # Normal field, stored in plaintext.
print $s{foo};              # (plaintext)

$s{_bar} = "signature";     # Fieldnames that begin in single
                            # underscore are encrypted.
print $s{_bar};             # (signature)  Though, while the password
                            # is set, they behave like normal fields.
delete $s{__password};      # Delete password to disable access
                            # to encrypting fields.
print $s{_bar};             # (Blowfish NuRVFIr8UCAJu5AWY0w...)

$s{__password} = 'passwd';  # Restore password to gain access.
print $s{_bar};             # (signature)

$s{_baz}{a}{b} = 42;        # Refs are fine, we encrypt them too.

---

💅 DESCRIPTION 💅

Tie::EncryptedHash levels up regular Perl hash semantics so you get secure, encrypting containers of data. Periodt. It introduces special hash fields that are coupled with encrypt/decrypt routines — so assignments get encrypted at STORE() and retrievals get decrypted at FETCH(). By design, the encrypting fields are the keys that start with a single underscore. Everything else in the keyspace is for normal hash fields, and those are kept without modification. No cap.

While the password is set, a Tie::EncryptedHash behaves exactly like a standard Perl hash. That's its transparent mode of access, and in this mode encrypting fields and normal fields are literally identical. The second you delete the password, the encrypting fields are only reachable as ciphertext. That's opaque mode, and it's optimized for serialization. 🦋

Encryption is done with Crypt::CBC(3), which encrypts in cipher block chaining mode with Blowfish, DES or IDEA. Tie::EncryptedHash uses Blowfish by default, but you can tell it to use any cipher Crypt::CBC(3) supports. 👑

---

🧚 MOTIVATION 🧚

Tie::EncryptedHash was built for storage and communication of key material used in public key cryptography algorithms. The author abstracted out the mechanism for encrypting selected fields of a structured data record because honestly the sheer convenience of this data security method is that girl. 💖

Quite often, apps that need data confidentiality ditch strong cryptography in favor of OS-based access control mechanisms, purely because cryptography integration costs extra. Besides cipher implementations — which are available as ready-to-deploy perl modules — using cryptography in an application also needs code to help with conversion and representation of encrypted data. That code usually gets encapsulated in a data access layer that manages encryption, decryption, access control and re-structuring of flat plaintext according to a data model. Tie::EncryptedHash hands you all of that under the disguise of a Perl hash, so perl apps can use strong cryptography without paying the cost of implementing a complex data access layer. Slay. ✨

---

🎀 CONSTRUCTION 🎀

🌸 Tied Hash 🌸

tie %h, Tie::EncryptedHash, 'Password', 'Cipher';

Ties %h to Tie::EncryptedHash and sets the value of password and cipher to 'Password' and 'Cipher'. Both arguments are optional. 🫶

🌸 Blessed Object 🌸

$h = new Tie::EncryptedHash __password =" 'Password',
                                __cipher => 'Cipher';>

The new() constructor returns an object that is both tied and blessed into Tie::EncryptedHash. Both arguments are optional. When you use it this way, Tie::EncryptedHash behaves like a class with encrypting data members. 💅

---

🔒 RESERVED ATTRIBUTES 🔒

The attributes __password, __cipher and __hide are reserved for communication with object methods. They are "write-only" from everywhere except the class the hash is tied to. __scaffolding is inaccessible. Tie::EncryptedHash stores the current encryption password and some transient data structures in these fields, and restricts access to them on a need-to-know basis. 🙈

🔑 __password

$h{__password} = "new password"; delete $h{__password};

The password is stored under the attribute __password. Besides specifying a password at construction, assigning to the __password attribute sets the current encryption password to whatever you assigned. Deleting __password unsets it and switches the hash into opaque mode. 💫

🔑 __cipher

$h{__cipher} = 'DES'; $h{__cipher} = 'Blowfish';

The cipher used for encryption/decryption is stored under the attribute __cipher. The value defaults to 'Blowfish'. 🐡

🔑 __hide

$h{__hide} = 1;

Setting this attribute hides encrypting fields in opaque mode. 'undef' is returned at FETCH() and EXISTS(). 🙈

---

👑 BEHAVIOR 👑

🌈 References 🌈

A reference stored in an encrypting field is serialized before encryption. The data structure the reference points at gets folded into a single line of ciphertext, which is stored under the first level key. So in opaque mode, only the first level of keys of the hash will be visible. Lowkey wild, but that's the deal. 🦋

🌈 Opaque Mode 🌈

Opaque mode brings a few more constraints on accessing encrypting fields. Encrypting fields return ciphertext on FETCH() — unless the __hide attribute is set, which forces Tie::EncryptedHash to behave as if the encrypting fields don't exist at all. Irrespective of __hide, though, DELETE() and CLEAR() fail in opaque mode. So does STORE() on an existing encrypting field. Plaintext assignments to encrypting fields are silently ignored, but ciphertext assignments are totally fine. Ciphertext assignments can be used to move data between different EncryptedHashes. 💅

🌈 Multiple Passwords and Ciphers 🌈

Modality of Tie::EncryptedHash's access system breaks down when more than one password is used with different encrypting fields. And that's a feature, not a bug. Tie::EncryptedHash lets you mix passwords and ciphers in the same hash. Assign new values to __password and __cipher, then create a new encrypting field. Transparent mode will be restricted to the fields encrypted with the current password. 👑

🌈 Error Handling 🌈

Tie::Encrypted silently ignores access errors. It doesn't carp or croak when you perform an illegal operation (like assigning plaintext to an encrypting field in opaque mode). This is to prevent data lossage — the kind that results from abnormal termination of applications. Protecting the vibes, fr fr. 🫶

---

🦋 QUIRKS 🦋

💜 Autovivification

Because of the nature of autovivified references (which spring into existence when an undefined reference is dereferenced), references are stored as plaintext in transparent mode. Analogous ciphertext representations are maintained in parallel, and restored to encrypting fields when the password is deleted. This process is completely transparent to the user, though it's advisable to delete the password after the final assignment to a Tie::EncryptedHash. That way you make sure plaintext representations and scaffolding data structures are duly flushed. 💅

💜 Data::Dumper

Serialization of references is done with Data::Dumper, which means the nature of data you can assign to encrypting fields is limited by what Data::Dumper can grok. We set $Data::Dumper::Purity = 1, so self-referential and recursive structures should be OK. 🎀

💜 Speed

Tie::EncryptedHashes keep their contents encrypted as much as possible, so there's a rather severe speed penalty. With Blowfish, STORE() on an EncryptedHash can be up to 70 times slower than a standard perl hash. Reference STORE()es will be quicker, but the speed gain gets adjusted at FETCH(). FETCH() is about 35 times slower than a standard perl hash. DES affords speed improvements of up to 2x, but it is not considered secure for long-term storage of data. These values were computed on a DELL PIII-300 Mhz notebook with 128 Mb RAM running perl 5.003 on Linux 2.2.16. Variations in speed might be different on your machine. 🐌

---

⭐ STANDARD USAGE ⭐

The standard usage for this module goes something like this: populate Tie::EncryptedHash with sensitive data, delete the password, serialize the encrypted hash with Data::Dumper, then store the result on disk or send it over the wire to another machine. Later, when the sensitive data is required, procure the EncryptedHash, set the password, and access the encrypted data fields. Main character data pipeline energy. 👑

---

🌈 SEE ALSO 🌈

• Data::Dumper(3)
• Crypt::CBC(3)
• Crypt::DES(3)
• Crypt::Blowfish(3)
• Tie::SecureHash(3)

---

💖 ACKNOWLEDGEMENTS 💖

The framework of Tie::EncryptedHash derives heavily from Damian Conway's Tie::SecureHash. Objects that are blessed as well as tied are just one of the pleasant side-effects of stealing Damian's code. Thanks to Damian for this brilliant module. 🫶

PacificNet (http://www.pacificnet.net) loaned the aforementioned notebook so the author could hack from the comfort of his bed. Thanks folks! 🛏️✨

---

👑 AUTHOR 👑

Vipul Ved Prakash <mail@vipul.net>

---

📜 LICENSE 📜

This module is distributed under the same license as Perl itself. 💅

---

okay bestie that's the whole thing 💖 this page came to you from perl v5.26.1, dated 2018-03-31, and it's part of the User Contributed Perl Documentation. go encrypt something, you absolute icon 🌸🦋✨