Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 155 lines (123 sloc) 6.488 kb
618bcb9 @skids Initial commit
authored
1 perl6sum
2 ========
3
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
4 Sum:: Perl 6 modules implementing checksums, hashes, etc.
304717f @skids Add a caveat regarding current blockers to running this package
authored
5
7d52902 @skids Work on the welcome mat a bit.
authored
6 ## Purpose
7
8 This suite of modules intends to become a thorough, idiomatic Perl 6
9 interface to checksum and digest algorithms, for both academic use
10 and for production applications. It supports both efficient
11 external libraries, and pure Perl 6 implementations of algorithms.
12
5b784f9 @skids Proofread corrections, clarify resource concerns.
authored
13 Currently, for production use, it is recommended only to use
7d52902 @skids Work on the welcome mat a bit.
authored
14 the modules with external libraries implementing desired algorithms.
15 At this time, the libraries supported are libcrypto, librhash,
16 and libmhash. These libraries are not strictly dependencies,
17 as runtime fallback code will use pure Perl 6 implementations when the
18 libraries are not present. So, projects using these modules
19 in production should take care to add dependencies appropriate
20 to the use case. The default behavior will always be to use
21 the fastest available option and fall back in the order of
22 decreasing performance, to the extent that there has been time to
23 compare the options.
24
25 The pure Perl 6 implementations are currently, intentionally,
26 not optimized. Some implementations are written in a way that
27 makes them easy to audit from the formal specification of the
28 algorithm. Others have been written to intentionally use,
29 and sometimes over-use, certain features of Perl 6 or certain
30 programming styles. They are kept this way as fodder for
31 optimization work on the Perl 6 core, until such a time as
32 having fast pure Perl 6 implementations is both possible and
33 needed by someone.
34
35 For example, the MD5 implementation currently runs 10 times
36 slower than the more basic, less fully featured, implementation
37 in the official ecosystem's "Digest::MD5" perl5-workalike module,
38 even though that module itself has probably not been very extensively
39 tweaked to avoid rakudo's current slow paths.
40
41 The pure Perl 6 implementations also try to implement features
42 useful for academic/cryptanalysis purposes, by supporting messages
43 that do not pack into bits, supporting variations of algorithms
44 that are obselete or have never seen real-world applications,
45 and supporting tuning of internal parameters or easy modification
46 of the code through subclassing.
47
48 ## Idioms
49
50 A few useful idioms should be pointed out. The first is that,
51 although prefabricated classes will eventually be provided, all
52 the functionality is available in role form, and as such may
53 be mixed into classes that might want to provide automatic
54 checksums:
55
56 class myStream does Sum::SHA1 does Sum::Marshal::Raw {
57 ...
58 method rx {
59 my $received_data;
60 ...
5b784f9 @skids Proofread corrections, clarify resource concerns.
authored
61 self.push($received_data);
7d52902 @skids Work on the welcome mat a bit.
authored
62 }
63 }
64
65 Another is that the objects may be used as a "tap" on a feed,
66 creating a checksum of all the values passed through that
67 feed without interfering with the feed result:
68
69 @pbytes <== $mySHA1 <== $myMD5 <== generate_packet();
70 ...
71 $packet = blob8.new[@pbytes,
72 $mySHA1.finalize.Buf.values,
73 net_endian(+@pbytes)]
74
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
75 ## 5to6
a5e79d1 @skids Temporarily remove POD synopsys tests.
authored
76
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
77 There are a few key differences between the way one uses
797810e @skids Update github front page
authored
78 objects from Sum:: versus the Perl 5 Digest:: interface.
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
79
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
80 1. Use .push, not ->add to add elements to the Sum.
81 There is an .add method but its exact behavior changes
82 with the algorithm and the backend. Only use .add
83 directly when optimizing for site-specific use cases.
84
85 2. Use .finalize, not ->digest. This change makes it clearer
86 that the calculation is complete and (in most algorithms)
87 more addends cannot be pushed to the digest. This also
88 brings Perl 6 in line with the prevalent vernacular.
89
90 3. While it is possible (and easy) to build a Sum class that will
91 take strings as arguments to .push, it is more advisable
92 to keep decisions about encoding visible at the point
93 of use. Consider this behavior of Perl 5 Digest:: when
94 you encounter characters with ordinal values between
95 129 and 255:
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
96
1774db1 @b2gills Change to a Markdown ordered list
b2gills authored
97 use Digest::SHA sha1_base64;
98 use Encode qw(encode_utf8);
99 say sha1_base64(encode_utf8('here is a french brace »'));
100 # S+YAQNtj1tluLgYewYgoWvdrSgQ
101 say sha1_base64( 'here is a french brace »')";
102 # 5hoNlI0QihTToOzKPc8pdMwEhWM
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
103
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
104 However, in Perl 5 you MUST use encode_utf8 if you handle any
105 characters with ordinals above 255. There is too much opportunity
106 for mixed encoding problems to happen when parts of a message are
107 pushed at different locations in the code.
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
108
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
109 By not accepting plain strings, users must consciously
110 choose an encoding and that helps them avoid accidentally mixing
111 encodings.
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
112
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
113 Fortunately, encoding is a built-in capability of Perl 6:
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
114
1774db1 @b2gills Change to a Markdown ordered list
b2gills authored
115 $sha.push('here is a french brace »'.encode('utf8'));
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
116
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
117 4. Note that the return value of .finalize is the finalized
118 Sum object. This can be coerced to common types you might
814cc87 @skids Fix a typo and explain absence of base32/64
authored
119 want and formatted by using many built-in Perl 6
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
120 methods. Also, .finalize takes arguments, which are just
121 passed to .push. Together this gives the following idiom
122 for one-shot purposes:
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
123
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
124 say mysha.new.finalize($buffer).Int.fmt("%20x");
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
125
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
126 There are some shortcuts built in, which also have the
127 benefit of including leading zeros.
797810e @skids Update github front page
authored
128
1774db1 @b2gills Change to a Markdown ordered list
b2gills authored
129 say mysha.new.finalize($buffer).fmt(); # lowercase hex (e.g. sha1_hex)
130 say mysha.new.finalize($buffer).fmt("%2.2x",":"); # colon octets
131 say mysha.new.finalize($buffer).base(16); # uppercase hex
132 say mysha.new.finalize($buffer).base(2); # binary text
797810e @skids Update github front page
authored
133
814cc87 @skids Fix a typo and explain absence of base32/64
authored
134 Base32 and Base64 is not yet implemented pending a review of
135 which variations of these encodings are used in modern applications.
136
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
137 5. There is no ->reset method, and .new does not re-use
138 the Perl 6 object when called on an instance, it just
139 creates a new Perl 6 object. Sum objects are meant
140 to be thrown away after use. Replacing them is easy:
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
141
1774db1 @b2gills Change to a Markdown ordered list
b2gills authored
142 # assuming $md has a Sum in it, or was constrained when defined.
143 $md .= new;
17a8f7c @skids I hate to do this but... change the return value of .finalize
authored
144
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
145 If you are concerned about tying up crypto resources, the
146 only thing to worry about is to ensure you finalize the object
147 before discarding it. The backends should be smart enough to
148 free up resources promptly upon finalization.
5b784f9 @skids Proofread corrections, clarify resource concerns.
authored
149
afcdba6 @skids Correct spacing of list paragraphs as suggested by b2gills++
authored
150 6. Just about everything in perl 6 has a .clone method,
151 including Sum objects. However, not all back-ends
152 can clone their instances. Using a class that does
153 Sum::Partial is one way to guarantee that only backends
154 that support cloning contexts are used.
Something went wrong with that request. Please try again.