source: project/wiki/eggref/5/message-digest-utils

Last change on this file was 36737, checked in by Kon Lovett, 10 months ago

rel 4.1.2

File size: 15.7 KB
Line 
1[[tags: egg]]
2
3
4== message-digest-utils
5
6[[toc:]]
7
8
9== Documentation
10
11Message Digest provides support for message digest primitives. A message-digest is
12a function taking some input source and returning a fixed-length hash.
13
14For best results the source object(s) to be accumulated into the digest should be
15something easily treated as a {{bytevector}}.
16
17
18=== Message Digest Byte Vector
19
20Digest routines for string & blob.
21
22==== Usage
23
24<enscript highlight=scheme>
25(import message-digest-byte-vector)
26</enscript>
27
28==== message-digest-update-blob
29
30<procedure>(message-digest-update-blob DIGEST BLOB [START [END]])</procedure>
31
32Update the {{DIGEST}} with a {{BLOB}}, optionally sliced by {{START END}}.
33
34==== message-digest-update-string
35
36<procedure>(message-digest-update-string DIGEST STRING [START [END]])</procedure>
37
38Update the {{DIGEST}} with a {{STRING}}, optionally sliced by {{START END}}.
39
40==== message-digest-string
41
42<procedure>(message-digest-string PRIM STRING [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
43
44Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
45{{STRING}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
46
47{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
48
49==== message-digest-blob
50
51<procedure>(message-digest-blob PRIM BLOB [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
52
53Returns the {{result}} for the digest algorithm {{PRIM}} applied to
54{{BLOB}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
55
56{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
57
58==== message-digest-string!
59
60<procedure>(message-digest-string! PRIM STRING BUFFER [START [END]]) -> message-digest-result-type</procedure>
61
62Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
63{{STRING}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
64
65==== message-digest-blob!
66
67<procedure>(message-digest-blob! PRIM BLOB BUFFER [START [END]]) -> message-digest-result-type</procedure>
68
69Returns the {{result}} for the digest algorithm {{PRIM}} applied to
70{{BLOB}}, optionally sliced by {{START END}}, in the {{{BUFFER}}}.
71
72==== message-digest-update-substring (DEPRECATED)
73
74<procedure>(message-digest-update-substring DIGEST STRING START END)</procedure>
75
76Update the {{DIGEST}} with a substring {{STRING START END}}.
77
78
79=== Message Digest Int
80
81Provides digest update operations for character and integer datatypes.
82
83==== Usage
84
85<enscript highlight=scheme>
86(import message-digest-int)
87</enscript>
88
89==== message-digest-update-char-u8
90
91<procedure>(message-digest-update-char-u8 DIGEST CHAR)</procedure>
92
93Update the {{DIGEST}} with the low-order 8-bits of a character {{CHAR}}.
94
95==== message-digest-update-char
96
97<procedure>(message-digest-update-char DIGEST CHAR [ENDIAN])</procedure>
98
99Update the {{DIGEST}} with a the character {{CHAR}} 32-bit integer value
100treated as {{ENDIAN}}.
101
102{{ENDIAN}} default is {{(machine-byte-order)}}.
103
104==== message-digest-update-char-be
105
106<procedure>(message-digest-update-char-be DIGEST CHAR)</procedure>
107
108Update the {{DIGEST}} with a the character {{CHAR}} 32-bit integer value
109treated as big-endian.
110
111==== message-digest-update-char-le
112
113<procedure>(message-digest-update-char-le DIGEST CHAR)</procedure>
114
115Update the {{DIGEST}} with a the character {{CHAR}} 32-bit integer value
116treated as little-endian.
117
118==== message-digest-update-u8
119
120<procedure>(message-digest-update-u8 DIGEST U8)</procedure>
121
122Update the {{DIGEST}} with an 8-bit integer {{U8}}.
123
124==== message-digest-update-u16
125
126<procedure>(message-digest-update-u16 DIGEST U16 [ENDIAN])</procedure>
127
128Update the {{DIGEST}} with a 16-bit integer {{U16}} treated as {{ENDIAN}}.
129
130{{ENDIAN}} default is {{(machine-byte-order)}}.
131
132==== message-digest-update-u16-be
133
134<procedure>(message-digest-update-u16-be DIGEST U16)</procedure>
135
136Update the {{DIGEST}} with a 16-bit integer {{U16}} treated as big-endian.
137
138==== message-digest-update-u16-le
139
140<procedure>(message-digest-update-u16-le DIGEST U16)</procedure>
141
142Update the {{DIGEST}} with a 16-bit integer {{U16}} treated as little-endian.
143
144==== message-digest-update-u32
145
146<procedure>(message-digest-update-u32 DIGEST U32 [ENDIAN])</procedure>
147
148Update the {{DIGEST}} with a 32-bit integer {{U32}} treated as {{ENDIAN}}.
149
150{{ENDIAN}} default is {{(machine-byte-order)}}.
151
152==== message-digest-update-u32-be
153
154<procedure>(message-digest-update-u32-be DIGEST U32)</procedure>
155
156Update the {{DIGEST}} with a 32-bit integer {{U32}} treated as big-endian.
157
158==== message-digest-update-u32-le
159
160<procedure>(message-digest-update-u32-le DIGEST U32)</procedure>
161
162Update the {{DIGEST}} with a 32-bit integer {{U32}} treated as little-endian.
163
164==== message-digest-update-u64
165
166<procedure>(message-digest-update-u64 DIGEST U64 [ENDIAN])</procedure>
167
168Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as {{ENDIAN}}.
169
170{{ENDIAN}} default is {{(machine-byte-order)}}.
171
172==== message-digest-update-u64-be
173
174<procedure>(message-digest-update-u64-be DIGEST U64)</procedure>
175
176Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as big-endian.
177
178==== message-digest-update-u64-le
179
180<procedure>(message-digest-update-u64-le DIGEST U64)</procedure>
181
182Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as little-endian.
183
184
185=== Message Digest Update Item
186
187Provides digest update operations for Scheme objects.
188
189==== Usage
190
191<enscript highlight=scheme>
192(import message-digest-update-item)
193</enscript>
194
195==== message-digest-update-file
196
197<procedure>(message-digest-update-file DIGEST FILENAME)</procedure>
198
199Update the {{DIGEST}} with the contents of file {{FILENAME}}.
200
201==== message-digest-update-procedure
202
203<procedure>(message-digest-update-procedure DIGEST THUNK)</procedure>
204
205Update the {{DIGEST}} with a {{THUNK}} until it returns {{#f}}.
206
207{{THUNK}} is a {{(-> byte-source)}}.
208
209==== message-digest-update-port
210
211<procedure>(message-digest-update-port DIGEST INPUT-PORT)</procedure>
212
213Update the {{DIGEST}} with {{byte-source}} from an {{INPUT-PORT}} until
214{{#!eof}} encountered.
215
216Uses the {{message-digest-chunk-read-maker}} to create a reader for the port.
217
218==== message-digest-update-object
219
220<procedure>(message-digest-update-object DIGEST SOURCE [START [END]])</procedure>
221
222Update the {{DIGEST}} with some {{SOURCE}}.
223
224{{SOURCE}} maybe
225
226; {{input-port}} : as in {{message-digest-update-port}}
227; {{procedure}} : as in {{message-digest-update-procedure}}
228; {{string}} :
229; {{blob}} :
230; {{srfi-4-vector}} :
231; {{*}} : {{((message-digest-chunk-converter) SOURCE)}} -> {{byte-source}}.
232
233If {{START END}} supplied, and possible, the {{byte-source}} is sliced.
234
235
236=== Message Digest Item
237
238Provides digest operations for whole Scheme objects.
239
240==== Usage
241
242<enscript highlight=scheme>
243(import message-digest-item)
244</enscript>
245
246==== message-digest-object
247
248<procedure>(message-digest-object PRIM SOURCE [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
249
250Returns the result for the digest algorithm {{PRIM}} applied to
251{{SOURCE}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
252
253{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
254
255==== message-digest-file
256
257<procedure>(message-digest-file PRIM FILENAME [RESULT-FORM]) -> message-digest-result-type</procedure>
258
259Returns the result for the digest algorithm {{PRIM}} applied to the file
260{{FILENAME}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
261
262{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
263
264==== message-digest-port
265
266<procedure>(message-digest-port PRIM INPUT-PORT [RESULT-FORM]) -> message-digest-result-type</procedure>
267
268Returns the result for the digest algorithm {{PRIM}} applied to
269{{INPUT-PORT}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
270
271{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
272
273==== message-digest-object!
274
275<procedure>(message-digest-object! PRIM SOURCE BUFFER [START [END]]) -> message-digest-result-type</procedure>
276
277Returns the result for the digest algorithm {{PRIM}} applied to
278{{SOURCE}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
279
280==== message-digest-file!
281
282<procedure>(message-digest-file! PRIM FILENAME BUFFER) -> message-digest-result-type</procedure>
283
284Returns the result for the digest algorithm {{PRIM}} applied to the file
285{{FILENAME}} in the {{BUFFER}}. Reads until {{#!eof}} encountered.
286
287==== message-digest-port!
288
289<procedure>(message-digest-port! PRIM INPUT-PORT BUFFER) -> message-digest-result-type</procedure>
290
291Returns the result for the digest algorithm {{PRIM}} applied to
292{{INPUT-PORT}} in the {{BUFFER}}. Reads until {{#!eof}} encountered.
293
294
295=== Message Digest SRFI 4
296
297Provides digest operations for SRFI-4 packed-vectors.
298
299==== Usage
300
301<enscript highlight=scheme>
302(import message-digest-srfi-4)
303</enscript>
304
305==== message-digest-update-u8vector
306
307<procedure>(message-digest-update-u8vector DIGEST U8VECTOR [START [END]])</procedure>
308
309Update the {{DIGEST}} with a {{U8VECTOR}}, optionally sliced by {{START END}}.
310
311==== message-digest-u8vector
312
313<procedure>(message-digest-u8vector PRIM U8VECTOR [RESULT-FORM [START [END]]]) -> message-digest-result-type</procedure>
314
315Returns the result for the digest algorithm {{PRIM}} applied to
316{{U8VECTOR}}, optionally sliced by {{START END}}, in the {{RESULT-FORM}}.
317
318{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
319
320==== message-digest-u8vector!
321
322<procedure>(message-digest-u8vector! PRIM U8VECTOR BUFFER [START [END]]) -> message-digest-result-type</procedure>
323
324Returns the result for the digest algorithm {{PRIM}} applied to
325{{U8VECTOR}}, optionally sliced by {{START END}}, in the {{BUFFER}}.
326
327==== message-digest-update-subu8vector (DEPRECATED)
328
329<procedure>(message-digest-update-subu8vector DIGEST U8VECTOR START END)</procedure>
330
331Update the {{DIGEST}} with a subvector {{U8VECTOR START END}}.
332
333==== message-digest-update-bytevector (DEPRECATED)
334
335<procedure>(message-digest-update-bytevector DIGEST BYTEVECTOR [LENGTH])</procedure>
336
337Update the {{DIGEST}} with the {{BYTEVECTOR}}, a {{blob}}, {{string}}, or
338{{srfi-4-vector}}.
339
340The {{LENGTH}} is the byte count. Default is the size in bytes of the
341{{BYTEVECTOR}}.
342
343
344=== Message Digest Port
345
346Provides a {{port}} abstraction for a {{message-digest-primitive}}.
347
348==== Usage
349
350<enscript highlight=scheme>
351(import message-digest-port)
352</enscript>
353
354==== Common Argument Definitions
355
356{{PORT}} is a {{digest-output-port}}.
357
358==== digest-output-port
359
360<procedure>(digest-output-port? OBJ) -> boolean</procedure>
361<procedure>(check-digest-output-port LOC OBJ [NAM])</procedure>
362<procedure>(error-digest-output-port LOC OBJ [NAM])</procedure>
363<procedure>(digest-output-port-name PORT) -> string</procedure>
364
365==== open-output-digest
366
367<procedure>(open-output-digest PRIM) -> digest-output-port</procedure>
368
369Returns a message digest output port for the supplied algorithm {{PRIM}}.
370
371The initialization phase.
372
373==== get-output-digest
374
375<procedure>(get-output-digest PORT [RESULT-FORM]) -> string</procedure>
376
377Closes the {{PORT}} and returns the result as a {{RESULT-FORM}}.
378
379{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
380
381The finalization phase.
382
383==== call-with-output-digest
384
385<procedure>(call-with-output-digest PRIM PROC [RESULT-FORM]) -> message-digest-result-type</procedure>
386
387Returns the result of the call of {{PROC}} with an {{open-output-digest}} for
388{{PRIM}} in the {{RESULT-FORM}}.
389
390{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
391
392==== with-output-to-digest
393
394<procedure>(with-output-to-digest PRIM THUNK [RESULT-FORM]) -> message-digest-result-type</procedure>
395
396Invoke the procedure {{THUNK}} with {{(current-output-port)}} bound to a
397{{digest-output-port}} and return in the {{RESULT-FORM}}.
398
399{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
400
401
402=== Message Digest Chunk
403
404An inchoate ''Chunking'' API.
405
406==== Usage
407
408<enscript highlight=scheme>
409(import message-digest-chunk)
410</enscript>
411
412==== message-digest-chunk-port-read-maker
413
414<parameter>(message-digest-chunk-port-read-maker [CTOR]) -> procedure</parameter>
415
416Supplies the procedure used to create an input procedure.
417
418; {{CTOR}} : {{(PORT #!optional SIZE) -> (-> byte-source)}}
419; {{PORT}} : source open input port
420; {{SIZE}} : chunk size, default {{(message-digest-chunk-size)}}
421
422The default {{CTOR}} returns a reader from {{PORT}} in {{SIZE}} bytes.
423
424==== message-digest-chunk-fileno-read-maker
425
426<parameter>(message-digest-chunk-fileno-read-maker [CTOR]) -> procedure</parameter>
427
428Supplies the procedure used to create an input procedure.
429
430; {{CTOR}} : {{(FD #!optional TOTAL SIZE) -> (-> byte-source)}}
431; {{FD}} : source open fileno
432; {{TOTAL}} : total size, default {{(file-size FD))}}
433; {{SIZE}} : chunk size, default {{(message-digest-chunk-size)}}
434
435The default {{CTOR}} returns a reader conditioned on memory-mapped-file
436support.
437
438==== message-digest-chunk-size
439
440<parameter>(message-digest-chunk-size [SIZE]) -> positive-integer</parameter>
441
442The number of bytes to read from a binary-stream during the message-digest
443update phase. Used by the default {{message-digest-chunk-read-maker}}.
444
445; {{SIZE}} : {{positive-integer}}, default {{1024}}
446
447==== message-digest-chunk-converter
448
449<parameter>(message-digest-chunk-converter [CONV]) -> (or #f procedure)</parameter>
450
451The procedure used to translate an arbitrary object into something
452suitable for an {{UPDATE}} procedure. See {{make-message-digest-primitive}}.
453
454; {{CONV}} : {{(* -> byte-source)}} or {{#f}}, default {{#f}}
455
456Should the {{CONV}} be {{#f}} or return {{#f}} then no translation is
457attempted.
458
459
460== Examples
461
462Uses the message-digest port abstraction to get an MD5 digest of a string:
463
464<enscript highlight=scheme>
465(import message-digest-port md5) ; Or sha1, or sha2, ...
466
467(call-with-output-digest (md5-primitive) (cut display "foo" <>))
468;=> "acbd18db4cc2f85cedef654fccc4a4d8"
469</enscript>
470
471
472== Bugs and Limitations
473
474* Only messages on a byte-boundary supported. Bit-boundary messages are not
475handled.
476
477* The number update routines will not process an {{integer}} represented as
478anything other than a {{fixnum}} or {{flonum}}.
479
480* Since Chicken does not really have a binary port the {{digest-output-port}}
481will only accumulate strings. For example, writing a 16-bit integer is
482actually writing the result of {{number->string}} and not the 16-bit value
483itself! To get this effect the value must first be packed into a {{string}}
484and then written. However, the {{extras#write-byte}} routine should function
485as expected with a {{digest-output-port}}.
486
487* The chunk-converter and source-reader interface is clumsy.
488
489
490== Notes
491
492* If someone needs to construct a {{message-digest}} phase procedure that
493cannot be built upon the existing public API please contact the maintainer.
494There are some routines that can be exported to aid in such a project. It must
495be pointed out that the message-digest port/file API is implemented using only
496the existing public API.
497
498
499== Requirements
500
501[[check-errors]]
502[[blob-utils]]
503[[string-utils]]
504
505
506== Author
507
508[[/users/kon-lovett|Kon Lovett]]
509
510
511== Version history
512
513; 4.1.2 : .
514; 4.0.0 : CHICKEN 5 release.
515
516
517== License
518
519  Copyright (C) 2018 Kon Lovett.  All rights reserved.
520
521  Permission is hereby granted, free of charge, to any person obtaining a
522  copy of this software and associated documentation files (the Software),
523  to deal in the Software without restriction, including without limitation
524  the rights to use, copy, modify, merge, publish, distribute, sublicense,
525  and/or sell copies of the Software, and to permit persons to whom the
526  Software is furnished to do so, subject to the following conditions:
527
528  The above copyright notice and this permission notice shall be included
529  in all copies or substantial portions of the Software.
530
531  THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
532  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
533  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
534  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
535  OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
536  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
537  OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.