Debian Codegraph @

README

raw
1 NAME
2
3 DBIx::Class::EncodedColumn - Automatically encode columns
4
5 SYNOPSIS
6
7 In your DBIx::Class Result class (sometimes erroneously referred to as
8 the 'table' class):
9
10 __PACKAGE__->load_components(qw/EncodedColumn ... Core/);
11
12 #Digest encoder with hex format and SHA-1 algorithm
13 __PACKAGE__->add_columns(
14 'password' => {
15 data_type => 'CHAR',
16 size => 40,
17 encode_column => 1,
18 encode_class => 'Digest',
19 encode_args => {algorithm => 'SHA-1', format => 'hex'},
20 }
21
22 #SHA-1 / hex encoding / generate check method
23 __PACKAGE__->add_columns(
24 'password' => {
25 data_type => 'CHAR',
26 size => 40 + 10,
27 encode_column => 1,
28 encode_class => 'Digest',
29 encode_args => {algorithm => 'SHA-1', format => 'hex', salt_length => 10},
30 encode_check_method => 'check_password',
31 }
32
33 #MD5 / base64 encoding / generate check method
34 __PACKAGE__->add_columns(
35 'password' => {
36 data_type => 'CHAR',
37 size => 22,
38 encode_column => 1,
39 encode_class => 'Digest',
40 encode_args => {algorithm => 'MD5', format => 'base64'},
41 encode_check_method => 'check_password',
42 }
43
44 #Eksblowfish bcrypt / cost of 8/ no key_nul / generate check method
45 __PACKAGE__->add_columns(
46 'password' => {
47 data_type => 'CHAR',
48 size => 59,
49 encode_column => 1,
50 encode_class => 'Crypt::Eksblowfish::Bcrypt',
51 encode_args => { key_nul => 0, cost => 8 },
52 encode_check_method => 'check_password',
53 }
54
55 In your application code:
56
57 #updating the value.
58 $row->password('plaintext');
59 my $digest = $row->password;
60
61 #checking against an existing value with a check_method
62 $row->check_password('old_password'); #true
63 $row->password('new_password');
64 $row->check_password('new_password'); #returns true
65 $row->check_password('old_password'); #returns false
66
67 Note: The component needs to be loaded before Core and other components
68 such as Timestamp. Core should always be last.
69
70 E.g:
71 __PACKAGE__->load_components(qw/EncodedColumn TimeStamp Core/);
72
73 DESCRIPTION
74
75 This DBIx::Class component can be used to automatically encode a
76 column's contents whenever the value of that column is set.
77
78 This module is similar to the existing DBIx::Class::DigestColumns, but
79 there is some key differences:
80
81 DigestColumns performs the encode operation on insert and update, and
82 EncodedColumn performs the operation when the value is set, or on new.
83
84 DigestColumns supports only algorithms of the Digest family.
85 EncodedColumn employs a set of thin wrappers around different cipher
86 modules to provide support for any cipher you wish to use and wrappers
87 are very simple to write (typically less than 30 lines).
88
89 EncodedColumn supports having more than one encoded column per table
90 and each column can use a different cipher.
91
92 Encode adds only one item to the namespace of the object utilizing it
93 (_column_encoders).
94
95 There is, unfortunately, some features that EncodedColumn doesn't
96 support. DigestColumns supports changing certain options at runtime, as
97 well as the option to not automatically encode values on set. The
98 author of this module found these options to be non-essential and
99 omitted them by design.
100
101 Options added to add_column
102
103 encode_column => 1
104
105 Enable automatic encoding of column values. If this option is not set
106 to true any other options will become no-ops.
107
108 encode_check_method => $method_name
109
110 By using the encode_check_method attribute when you declare a column
111 you can create a check method for that column. The check method accepts
112 a plain text string, and returns a boolean that indicates whether the
113 digest of the provided value matches the current value.
114
115 encode_class
116
117 The class to use for encoding. Available classes are:
118
119 Crypt::Eksblowfish::Bcrypt - uses
120 DBIx::Class::EncodedColumn::Crypt::Eksblowfish::Bcrypt and requires
121 Crypt::Eksblowfish::Bcrypt to be installed
122
123 Digest - uses DBIx::Class::EncodedColumn::Digest requires Digest to be
124 installed as well as the algorithm required (Digest::SHA,
125 Digest::Whirlpool, etc)
126
127 Crypt::OpenPGP - DBIx::Class::EncodedColumn::Crypt::OpenPGP and
128 requires Crypt::OpenPGP to be installed
129
130 Please see the relevant class's documentation for information about the
131 specific arguments accepted by each and make sure you include the
132 encoding algorithm (e.g. Crypt::OpenPGP) in your application's
133 requirements.
134
135 EXTENDED METHODS
136
137 The following DBIx::Class::ResultSource method is extended:
138
139 register_column - Handle the options described above.
140
141 The following DBIx::Class::Row methods are extended by this module:
142
143 new - Encode the columns on new() so that copy and create DWIM.
144
145 set_column - Encode values whenever column is set.
146
147 SEE ALSO
148
149 DBIx::Class::DigestColumns, DBIx::Class, Digest
150
151 AUTHOR
152
153 Guillermo Roditi (groditi) <[email protected]>
154
155 Inspired by the original module written by Tom Kirkpatrick (tkp)
156 <[email protected]> featuring contributions from Guillermo Roditi (groditi)
157 <[email protected]> and Marc Mims <[email protected]>
158
159 CONTRIBUTORS
160
161 jshirley - J. Shirley <[email protected]>
162
163 kentnl - Kent Fredric <[email protected]>
164
165 mst - Matt S Trout <[email protected]>
166
167 wreis - Wallace reis <[email protected]>
168
169 COPYRIGHT
170
171 Copyright (c) the DBIx::Class::EncodedColumn "AUTHOR" and
172 "CONTRIBUTORS" as listed above.
173
174 LICENSE
175
176 This library is free software and may be distributed under the same
177 terms as perl itself.
178