1Tie::EncryptedHash(3) User Contributed Perl DocumentationTie::EncryptedHash(3)
2
6 Tie::EncryptedHash - Hashes (and objects based on hashes) with encrypt‐
7 ing fields.
8
10 use Tie::EncryptedHash;
11 my %s = ();
13 tie %s, Tie::EncryptedHash, 'passwd';
14 $s{foo} = "plaintext"; # Normal field, stored in plaintext.
16 print $s{foo}; # (plaintext)
17 $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 $s{__password} = 'passwd'; # Restore password to gain access.
27 print $s{_bar}; # (signature)
28 $s{_baz}{a}{b} = 42; # Refs are fine, we encrypt them too.
30
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 under‐
37 score. The remaining keyspace is used for accessing normal hash
38 fields, which are retained without modification.
39 While the password is set, a Tie::EncryptedHash behaves exactly like a
41 standard Perl hash. This is its transparent mode of access. Encrypt‐
42 ing and normal fields are identical in this mode. When password is
43 deleted, encrypting fields are accessible only as ciphertext. This is
44 Tie::EncryptedHash's opaque mode of access, optimized for serializa‐
45 tion.
46 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
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 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, decryp‐
65 tion, access control and re-structuring of flat plaintext according to
66 a data model. Tie::EncryptedHash provides these functions under the
67 disguise of a Perl hash so perl applications can use strong cryptogra‐
68 phy without the cost of implementing a complex data access layer.
69
71 Tied Hash
72 "tie %h, Tie::EncryptedHash, 'Password', 'Cipher';"
74 Ties %h to Tie::EncryptedHash and sets the value of password and cipher
76 to 'Password' and 'Cipher'. Both arguments are optional.
77 Blessed Object
79 "$h = new Tie::EncryptedHash __password =" 'Password',
81 __cipher => 'Cipher';>
82 The new() constructor returns an object that is both tied and blessed
84 into Tie::EncryptedHash. Both arguments are optional. When used in
85 this manner, Tie::EncryptedHash behaves like a class with encrypting
86 data members.
87
89 The attributes __password, __cipher and __hide are reserved for commu‐
90 nication with object methods. They are "write-only" from everywhere
91 except the class to which the hash is tied. __scaffolding is inacces‐
92 sible. Tie::EncryptedHash stores the current encryption password and
93 some transient data structures in these fields and restricts access to
94 them on need-to-know basis.
95 __password
97 "$h{__password} = "new password"; delete $h{__password};"
99 The password is stored under the attribute "__password". In addition
101 to specifying a password at construction, assigning to the __password
102 attribute sets the current encryption password to the assigned value.
103 Deleting the __password unsets it and switches the hash into opaque
104 mode.
105 __cipher
107 "$h{__cipher} = 'DES'; $h{__cipher} = 'Blowfish';"
109 The cipher used for encryption/decryption is stored under the attribute
111 __cipher. The value defaults to 'Blowfish'.
112 __hide
114 "$h{__hide} = 1;"
116 Setting this attribute hides encrypting fields in opaque mode. 'undef'
118 is returned at FETCH() and EXISTS().
119
121 References
122 A reference stored in an encrypting field is serialized before encryp‐
124 tion. The data structure represented by the reference is folded into a
125 single line of ciphertext which is stored under the first level key.
126 In the opaque mode, therefore, only the first level of keys of the hash
127 will be visible.
128 Opaque Mode
130 The opaque mode introduces several other constraints on access of
132 encrypting fields. Encrypting fields return ciphertext on FETCH()
133 unless __hide attribute is set, which forces Tie::EncryptedHash to
134 behave as if encrypting fields don't exist. Irrespective of __hide,
135 however, DELETE() and CLEAR() fail in opaque mode. So does STORE() on
136 an existing encrypting field. Plaintext assignments to encrypting
137 fields are silently ignored, but ciphertext assignments are fine.
138 Ciphertext assignments can be used to move data between different
139 EncryptedHashes.
140 Multiple Passwords and Ciphers
142 Modality of Tie::EncryptedHash's access system breaks down when more
144 than one password is used to with different encrypting fields. This is
145 a feature. Tie::EncryptedHash lets you mix passwords and ciphers in
146 the same hash. Assign new values to __password and __cipher and create
147 a new encrypting field. Transparent mode will be restricted to fields
148 encrypted with the current password.
149 Error Handling
151 Tie::Encrypted silently ignores access errors. It doesn't carp/croak
153 when you perform an illegal operation (like assign plaintext to an
154 encrypting field in opaque mode). This is to prevent data lossage, the
155 kind that results from abnormal termination of applications.
156
158 Autovivification
159 Due to the nature of autovivified references (which spring into exis‐
161 tence when an undefined reference is dereferenced), references are
162 stored as plaintext in transparent mode. Analogous ciphertext repre‐
163 sentations are maintained in parallel and restored to encrypting fields
164 when password is deleted. This process is completely transparent to
165 the user, though it's advisable to delete the password after the final
166 assignment to a Tie::EncryptedHash. This ensures plaintext representa‐
167 tions and scaffolding data structures are duly flushed.
168 Data::Dumper
170 Serialization of references is done with Data::Dumper, therefore the
172 nature of data that can be assigned to encrypting fields is limited by
173 what Data::Dumper can grok. We set $Data::Dumper::Purity = 1, so self-
174 referential and recursive structures should be OK.
175 Speed
177 Tie::EncryptedHash'es keep their contents encrypted as much as possi‐
179 ble, so there's a rather severe speed penalty. With Blowfish, STORE()
180 on EncryptedHash can be upto 70 times slower than a standard perl hash.
181 Reference STORE()'es will be quicker, but speed gain will be adjusted
182 at FETCH(). FETCH() is about 35 times slower than a standard perl
183 hash. DES affords speed improvements of upto 2x, but is not considered
184 secure for long-term storage of data. These values were computed on a
185 DELL PIII-300 Mhz notebook with 128 Mb RAM running perl 5.003 on Linux
186 2.2.16. Variations in speed might be different on your machine.
187
189 The standard usage for this module would be something along the lines
190 of: populate Tie::EncryptedHash with sensitive data, delete the pass‐
191 word, serialize the encrypted hash with Data::Dumper, store the result
192 on disk or send it over the wire to another machine. Later, when the
193 sensitive data is required, procure the EncryptedHash, set the password
194 and accesses the encrypted data fields.
195
197 Data::Dumper(3), Crypt::CBC(3), Crypt::DES(3), Crypt::Blowfish(3),
198 Tie::SecureHash(3)
199
201 The framework of Tie::EncryptedHash derives heavily from Damian Con‐
202 way's Tie::SecureHash. Objects that are blessed as well as tied are
203 just one of the pleasant side-effects of stealing Damian's code.
204 Thanks to Damian for this brilliant module.
205 PacificNet (http://www.pacificnet.net) loaned me the aforementioned
207 notebook to hack from the comfort of my bed. Thanks folks!
208
210 Vipul Ved Prakash <mail@vipul.net>
211
213 Artistic.
214perl v5.8.8 2007-04-18 Tie::EncryptedHash(3)