1Tie::EncryptedHash(3) User Contributed Perl DocumentationTie::EncryptedHash(3)
2
3
4

NAME

6       Tie::EncryptedHash - Hashes (and objects based on hashes) with
7       encrypting fields.
8

SYNOPSIS

10           use Tie::EncryptedHash;
11
12           my %s = ();
13           tie %s, Tie::EncryptedHash, 'passwd';
14
15           $s{foo}  = "plaintext";     # Normal field, stored in plaintext.
16           print $s{foo};              # (plaintext)
17
18           $s{_bar} = "signature";     # Fieldnames that begin in single
19                                       # underscore are encrypted.
20           print $s{_bar};             # (signature)  Though, while the password
21                                       # is set, they behave like normal fields.
22           delete $s{__password};      # Delete password to disable access
23                                       # to encrypting fields.
24           print $s{_bar};             # (Blowfish NuRVFIr8UCAJu5AWY0w...)
25
26           $s{__password} = 'passwd';  # Restore password to gain access.
27           print $s{_bar};             # (signature)
28
29           $s{_baz}{a}{b} = 42;        # Refs are fine, we encrypt them too.
30

DESCRIPTION

32       Tie::EncryptedHash augments Perl hash semantics to build secure,
33       encrypting containers of data.  Tie::EncryptedHash introduces special
34       hash fields that are coupled with encrypt/decrypt routines to encrypt
35       assignments at STORE() and decrypt retrievals at FETCH().  By design,
36       encrypting fields are associated with keys that begin in single
37       underscore.  The remaining keyspace is used for accessing normal hash
38       fields, which are retained without modification.
39
40       While the password is set, a Tie::EncryptedHash behaves exactly like a
41       standard Perl hash.  This is its transparent mode of access.
42       Encrypting and normal fields are identical in this mode.  When password
43       is deleted, encrypting fields are accessible only as ciphertext.  This
44       is Tie::EncryptedHash's opaque mode of access, optimized for
45       serialization.
46
47       Encryption is done with Crypt::CBC(3) which encrypts in the cipher
48       block chaining mode with Blowfish, DES or IDEA.  Tie::EncryptedHash
49       uses Blowfish by default, but can be instructed to employ any cipher
50       supported by Crypt::CBC(3).
51

MOTIVATION

53       Tie::EncryptedHash was designed for storage and communication of key
54       material used in public key cryptography algorithms.  I abstracted out
55       the mechanism for encrypting selected fields of a structured data
56       record because of the sheer convenience of this data security method.
57
58       Quite often, applications that require data confidentiality eschew
59       strong cryptography in favor of OS-based access control mechanisms
60       because of the additional costs of cryptography integration.  Besides
61       cipher implementations, which are available as ready-to-deploy perl
62       modules, use of cryptography in an application requires code to aid
63       conversion and representation of encrypted data.  This code is usually
64       encapsulated in a data access layer that manages encryption,
65       decryption, access control and re-structuring of flat plaintext
66       according to a data model.  Tie::EncryptedHash provides these functions
67       under the disguise of a Perl hash so perl applications can use strong
68       cryptography without the cost of implementing a complex data access
69       layer.
70

CONSTRUCTION

72   Tied Hash
73       "tie %h, Tie::EncryptedHash, 'Password', 'Cipher';"
74
75       Ties %h to Tie::EncryptedHash and sets the value of password and cipher
76       to 'Password' and 'Cipher'.  Both arguments are optional.
77
78   Blessed Object
79       "$h = new Tie::EncryptedHash __password =" 'Password',
80                                __cipher => 'Cipher';>
81
82       The new() constructor returns an object that is both tied and blessed
83       into Tie::EncryptedHash.  Both arguments are optional.  When used in
84       this manner, Tie::EncryptedHash behaves like a class with encrypting
85       data members.
86

RESERVED ATTRIBUTES

88       The attributes __password, __cipher and __hide are reserved for
89       communication with object methods.  They are "write-only" from
90       everywhere except the class to which the hash is tied.  __scaffolding
91       is inaccessible.  Tie::EncryptedHash stores the current encryption
92       password and some transient data structures in these fields and
93       restricts access to them on need-to-know basis.
94
95   __password
96       "$h{__password} = "new password"; delete $h{__password};"
97
98       The password is stored under the attribute "__password".  In addition
99       to specifying a password at construction, assigning to the __password
100       attribute sets the current encryption password to the assigned value.
101       Deleting the __password unsets it and switches the hash into opaque
102       mode.
103
104   __cipher
105       "$h{__cipher} = 'DES'; $h{__cipher} = 'Blowfish';"
106
107       The cipher used for encryption/decryption is stored under the attribute
108       __cipher.  The value defaults to 'Blowfish'.
109
110   __hide
111       "$h{__hide} = 1;"
112
113       Setting this attribute hides encrypting fields in opaque mode.  'undef'
114       is returned at FETCH() and EXISTS().
115

BEHAVIOR

117   References
118       A reference stored in an encrypting field is serialized before
119       encryption.  The data structure represented by the reference is folded
120       into a single line of ciphertext which is stored under the first level
121       key.  In the opaque mode, therefore, only the first level of keys of
122       the hash will be visible.
123
124   Opaque Mode
125       The opaque mode introduces several other constraints on access of
126       encrypting fields.  Encrypting fields return ciphertext on FETCH()
127       unless __hide attribute is set, which forces Tie::EncryptedHash to
128       behave as if encrypting fields don't exist.  Irrespective of __hide,
129       however, DELETE() and CLEAR() fail in opaque mode.  So does STORE() on
130       an existing encrypting field.  Plaintext assignments to encrypting
131       fields are silently ignored, but ciphertext assignments are fine.
132       Ciphertext assignments can be used to move data between different
133       EncryptedHashes.
134
135   Multiple Passwords and Ciphers
136       Modality of Tie::EncryptedHash's access system breaks down when more
137       than one password is used to with different encrypting fields.  This is
138       a feature.  Tie::EncryptedHash lets you mix passwords and ciphers in
139       the same hash.  Assign new values to __password and __cipher and create
140       a new encrypting field.  Transparent mode will be restricted to fields
141       encrypted with the current password.
142
143   Error Handling
144       Tie::Encrypted silently ignores access errors.  It doesn't carp/croak
145       when you perform an illegal operation (like assign plaintext to an
146       encrypting field in opaque mode).  This is to prevent data lossage, the
147       kind that results from abnormal termination of applications.
148

QUIRKS

150   Autovivification
151       Due to the nature of autovivified references (which spring into
152       existence when an undefined reference is dereferenced), references are
153       stored as plaintext in transparent mode.  Analogous ciphertext
154       representations are maintained in parallel and restored to encrypting
155       fields when password is deleted.  This process is completely
156       transparent to the user, though it's advisable to delete the password
157       after the final assignment to a Tie::EncryptedHash.  This ensures
158       plaintext representations and scaffolding data structures are duly
159       flushed.
160
161   Data::Dumper
162       Serialization of references is done with Data::Dumper, therefore the
163       nature of data that can be assigned to encrypting fields is limited by
164       what Data::Dumper can grok.  We set $Data::Dumper::Purity = 1, so self-
165       referential and recursive structures should be OK.
166
167   Speed
168       Tie::EncryptedHash'es keep their contents encrypted as much as
169       possible, so there's a rather severe speed penalty.  With Blowfish,
170       STORE() on EncryptedHash can be upto 70 times slower than a standard
171       perl hash.  Reference STORE()'es will be quicker, but speed gain will
172       be adjusted at FETCH().  FETCH() is about 35 times slower than a
173       standard perl hash.  DES affords speed improvements of upto 2x, but is
174       not considered secure for long-term storage of data.  These values were
175       computed on a DELL PIII-300 Mhz notebook with 128 Mb RAM running perl
176       5.003 on Linux 2.2.16.  Variations in speed might be different on your
177       machine.
178

STANDARD USAGE

180       The standard usage for this module would be something along the lines
181       of: populate Tie::EncryptedHash with sensitive data, delete the
182       password, serialize the encrypted hash with Data::Dumper, store the
183       result on disk or send it over the wire to another machine.  Later,
184       when the sensitive data is required, procure the EncryptedHash, set the
185       password and accesses the encrypted data fields.
186

SEE ALSO

188       Data::Dumper(3), Crypt::CBC(3), Crypt::DES(3), Crypt::Blowfish(3),
189       Tie::SecureHash(3)
190

ACKNOWLEDGEMENTS

192       The framework of Tie::EncryptedHash derives heavily from Damian
193       Conway's Tie::SecureHash.  Objects that are blessed as well as tied are
194       just one of the pleasant side-effects of stealing Damian's code.
195       Thanks to Damian for this brilliant module.
196
197       PacificNet (http://www.pacificnet.net) loaned me the aforementioned
198       notebook to hack from the comfort of my bed.  Thanks folks!
199

AUTHOR

201       Vipul Ved Prakash <mail@vipul.net>
202

LICENSE

204       This module is distributed under the same license as Perl itself.
205
206
207
208perl v5.38.0                      2023-07-21             Tie::EncryptedHash(3)
Impressum