source: project/wiki/eggref/4/message-digest @ 15594

Last change on this file since 15594 was 15594, checked in by Kon Lovett, 11 years ago

Rel 2.0.0

File size: 6.8 KB
Line 
1[[tags: egg]]
2
3== message-digest
4
5[[toc:]]
6
7
8== Documentation
9
10Message Digest provides support for message digest primitives. A message-digest
11is a function taking an arbitrary input and returning a fixed-length hash. For best
12results the input should be something easily treated as a byte-block.
13
14=== make-binary-message-digest
15
16 [procedure] (make-binary-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => STRING
17
18Returns the message-digest for {{SOURCE}} as a string of bytes.
19
20{{SOURCE}} is any Scheme-object. See the {{UPDATE}} entry below for
21interpretation of the {{SOURCE}}.
22
23{{CONTEXT-INFO}} is either a procedure that returns an object {{CONTEXT}}, or a
24{{positive fixnum}}. When a fixnum a memory-block of length {{CONTEXT-INFO}} is
25allocated (and automatically free'ed). The {{CONTEXT}} is often a {{pointer}}
26but maybe any Scheme-object.
27
28{{DIGEST-LENGTH}} is the fixnum count of bytes in the result string.
29
30The phase procedures:
31
32 [procedure] ({{INIT}} CONTEXT)
33
34Initialization phase procedure. Sets up the {{CONTEXT}}, if necessary.
35The result is ignored.
36
37 [procedure] ({{UPDATE}} CONTEXT BUFFER COUNT)
38
39Accumulation phase procedure. Must accumulate the {{BUFFER}}, where {{BUFFER}}
40is a Scheme-object. Will be called one or more times. The result is ignored.
41
42Where {{SOURCE}} is-a:
43
44; {{string}} : {{BUFFER}} = {{SOURCE}}.
45; {{blob}} : {{BUFFER}} = {{SOURCE}}.
46; {{procedure}} : updates with {{BUFFER}} = {{(procedure)}} until {{#f = (procedure)}}.
47; {{input-port}} : like {{procedure}} above but from {{message-digest-chunk-reader}}.
48; {{object}} : {{BUFFER}} = {{(message-digest-chunk-converter SOURCE)}}.
49
50Where the actual number of bytes in the {{BUFFER}} can be determined {{COUNT}} will
51be a {{positive-integer}}. Otherwise {{COUNT}} is {{-1}}.
52
53See {{message-digest-chunk-size}} to set the number of bytes read per update invocation.
54
55See {{message-digest-chunk-reader}} to set the chunk reader procedure creator.
56
57See {{message-digest-chunk-converter}} to set the chunk representation translation procedure.
58
59 [procedure] ({{FINAL}} CONTEXT RESULT)
60
61Finalization phase procedure. Must build the resulting message-digest in the
62supplied {{RESULT}} string of length {{DIGEST-LENGTH}}. The result is ignored.
63
64The optional {{CALLER}} is for identification.
65
66=== make-message-digest
67
68 [procedure] (make-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => STRING
69
70Exactly as above but returns the message-digest for {{SOURCE}} using
71{{byte-string->hexadecimal}}.
72
73=== message-digest-primitive
74
75  [record] (message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL ID)
76
77The meaning of the fields are exactly as above.
78
79 [procedure] message-digest?
80 [procedure] message-digest-context-info
81 [procedure] message-digest-digest-length
82 [procedure] message-digest-init
83 [procedure] message-digest-update
84 [procedure] message-digest-final
85 [procedure] message-digest-name
86
87=== message-digest-primitive-apply
88
89 [procedure] (message-digest-primitive-apply MESSAGE-DIGEST-PRIMITIVE SOURCE [CALLER])
90
91Returns a binary-message-digest of {{SOURCE}} using {{MESSAGE-DIGEST-PRIMITIVE}}.
92
93=== Parameters
94
95=== message-digest-chunk-size
96
97 [parameter] (message-digest-chunk-size [SIZE])
98
99The number of bytes to read during the message-digest update phase.
100{{SIZE}} is a {{positive fixnum}}, default {{1024}}.
101
102=== message-digest-chunk-reader
103
104 [parameter] (message-digest-chunk-reader [READER-CREATOR])
105
106The procedure used to create an input procedure.
107
108  [procedure] ({{READER-CREATOR}} INPUT-PORT) => PROCEDURE/0
109
110The default {{READER-CREATOR}} will return a reader that takes from {{INPUT-PORT}}
111in {{(message-digest-chunk-size)}} bytes. The {{INPUT-PORT}} is treated as a
112binary-stream no matter how it is defined.
113
114=== message-digest-chunk-converter
115
116 [parameter] (message-digest-chunk-converter [CONVERTER])
117
118The procedure used to translate an arbitrary Scheme-object into something
119suitable for an {{UPDATE}} procedure. Should the {{CONVERTER}} be
120{{#f}} then no translation is attempted.
121
122  [procedure] ({{CONVERTER}} OBJECT) => OBJECT
123
124The default {{CONVERTER}} will convert a {{heterogeneous-vector}} to a {{blob}}
125with shared-storage. No translation otherwise.
126
127=== Auxillary Procedures
128
129==== byte-string->substring-list
130
131 [procedure] (byte-string->substring-list STRING CHUNK-SIZE [START [END]]) => LIST
132
133Returns a list of {{CHUNK-SIZE}} substrings of {{STRING}}, on the interval
134[{{START}} {{END}}). Defaults are [0 string-length).
135
136Any remaining substring less than {{CHUNK-SIZE}} is appended to the list.
137
138==== byte-string->substring-list/shared
139
140 [procedure] (byte-string->substring-list/shared STRING CHUNK-SIZE [START [END]]) => LIST
141
142Returns a list of {{CHUNK-SIZE}} substrings of {{STRING}}, on the interval
143[{{START}} {{END}}). Defaults are [0 byte-string-length).
144
145Any remaining substring less than {{CHUNK-SIZE}} is appended to the list.
146
147The substrings can share storage with the {{STRING}}!
148
149==== byte-string->hexadecimal
150
151 [procedure] (byte-string->hexadecimal STRING [START [END]]) => STRING
152
153Returns a hex-encoded representation of {{STRING}}, on the interval [{{START}}
154{{END}}). Defaults are [0 byte-string-length).
155
156
157== Usage
158
159<enscript language=scheme>
160(require-library message-digest)
161(import message-digest)
162</enscript>
163
164
165== Examples
166
167
168== Notes
169
170* Unlike the Chicken 3 version does not provide the {{->blob}} and
171{{->blob/shared}} procedures.
172
173
174== Requirements
175
176[miscmacros]
177[check-errors]
178
179
180== Bugs and Limitations
181
182* Uses the core {{string}} type for a message-digest. Probably should use a {{blob}}.
183
184* {{byte-string->substring-list/shared}}, {{byte-string->substring-list}}, and
185{{byte-string->hexadecimal}} do not really belong here.
186
187
188== Author
189
190[[kon lovett]]
191
192
193== Version history
194
195; 2.0.0 : Release for Chicken 4 [From a diff provided by Christian Kellermann]
196
197
198== License
199
200Copyright (C) 2009 Kon Lovett.  All rights reserved.
201
202Permission is hereby granted, free of charge, to any person obtaining a
203copy of this software and associated documentation files (the Software),
204to deal in the Software without restriction, including without limitation
205the rights to use, copy, modify, merge, publish, distribute, sublicense,
206and/or sell copies of the Software, and to permit persons to whom the
207Software is furnished to do so, subject to the following conditions:
208
209The above copyright notice and this permission notice shall be included
210in all copies or substantial portions of the Software.
211
212THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
213IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
214FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
215THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
216OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
217ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
218OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.