Changeset 18851 in project


Ignore:
Timestamp:
07/17/10 06:30:11 (10 years ago)
Author:
Kon Lovett
Message:

Release 2.1.0 doc.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/message-digest

    r18231 r18851  
    88
    99Message Digest provides support for message digest primitives. A message-digest
    10 is a function taking an arbitrary input and returning a fixed-length hash. For best
    11 results the input should be something easily treated as a byte-block.
    12 
    13 === make-binary-message-digest
    14 
    15 <procedure>(make-binary-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => STRING</procedure>
    16 
    17 Returns the message-digest for {{SOURCE}} as a string of bytes.
    18 
    19 {{SOURCE}} is any Scheme-object. See the {{UPDATE}} entry below for
    20 interpretation of the {{SOURCE}}.
    21 
    22 {{CONTEXT-INFO}} is either a procedure that returns an object {{CONTEXT}}, or a
    23 {{positive fixnum}}. When a fixnum a memory-block of length {{CONTEXT-INFO}} is
    24 allocated (and automatically free'ed). The {{CONTEXT}} is often a {{pointer}}
    25 but maybe any Scheme-object.
    26 
    27 {{DIGEST-LENGTH}} is the fixnum count of bytes in the result string.
    28 
    29 The phase procedures:
    30 
    31  (INIT CONTEXT)
    32 
    33 Initialization phase procedure. Sets up the {{CONTEXT}}, if necessary.
    34 The result is ignored.
    35 
    36  (UPDATE CONTEXT BUFFER COUNT)
    37 
    38 Accumulation phase procedure. Must accumulate the {{BUFFER}}, where {{BUFFER}}
    39 is a Scheme-object. Will be called one or more times. The result is ignored.
    40 
    41 Where {{SOURCE}} is-a:
    42 
    43 ; {{string}} : {{BUFFER}} = {{SOURCE}}.
    44 ; {{blob}} : {{BUFFER}} = {{SOURCE}}.
    45 ; {{procedure}} : updates with {{BUFFER}} = {{(procedure)}} until {{#f = (procedure)}}.
    46 ; {{input-port}} : like {{procedure}} above but from {{message-digest-chunk-reader}}.
    47 ; {{object}} : {{BUFFER}} = {{(message-digest-chunk-converter SOURCE)}}.
    48 
    49 Where the actual number of bytes in the {{BUFFER}} can be determined {{COUNT}} will
    50 be a {{positive-integer}}. Otherwise an error is signaled.
    51 
    52 See {{message-digest-chunk-size}} to set the number of bytes read per update invocation.
    53 
    54 See {{message-digest-chunk-reader}} to set the chunk reader procedure creator.
    55 
    56 See {{message-digest-chunk-converter}} to set the chunk representation translation procedure.
    57 
    58  (FINAL CONTEXT RESULT)
    59 
    60 Finalization phase procedure. Must build the resulting message-digest in the
    61 supplied {{RESULT}} string of length {{DIGEST-LENGTH}}. The result is ignored.
    62 
    63 The optional {{CALLER}} is for identification.
    64 
    65 === make-message-digest
    66 
    67 <procedure>(make-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => STRING</procedure>
    68 
    69 Exactly as above but returns the message-digest for {{SOURCE}} using
    70 {{byte-string->hexadecimal}}.
    71 
    72 === message-digest-primitive
    73 
    74 <procedure>(make-message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL ID)</procedure>
    75 
    76 Create a {{message-digest-primitive}} record object. The meaning of
    77 the fields are exactly as above. Predicates and accessors follow:
    78 
    79 <procedure>(message-digest-primitive? OBJ)</procedure>
     10is a function taking some input source and returning a fixed-length hash. For best
     11results the source should be something easily treated as a byte-block.
     12
     13
     14=== Parameters
     15
     16=== message-digest-chunk-read-maker
     17
     18<parameter>(message-digest-chunk-read-maker [READER-CREATOR])</parameter>
     19
     20The procedure used to create an input procedure.
     21
     22<procedure>(READER-CREATOR INPUT-PORT) => PROCEDURE/0</procedure>
     23
     24The default {{READER-CREATOR}} will return a procedure, {{READER}}, that reads
     25from {{INPUT-PORT}} in {{(message-digest-chunk-size)}} bytes.
     26
     27The {{READER}} must return an object suitable for treatment as a byte-source.
     28See {{SOURCE}}.
     29
     30=== message-digest-chunk-size
     31
     32<parameter>(message-digest-chunk-size [SIZE])</parameter>
     33
     34The number of bytes to read from a binary-stream during the message-digest
     35update phase. Used by the default {{message-digest-chunk-read-maker}}.
     36
     37{{SIZE}} is a {{positive integer}}, default {{1024}}.
     38
     39=== message-digest-chunk-converter
     40
     41<parameter>(message-digest-chunk-converter [CONVERTER])</parameter>
     42
     43The procedure used to translate an arbitrary object into something
     44suitable for an {{UPDATE}} procedure. See {{make-message-digest-primitive}}.
     45
     46<procedure>(CONVERTER OBJECT) => {{object}}</procedure>
     47
     48Should the {{CONVERTER}} be {{#f}} then no translation is attempted or return
     49{{#f}} then no translation is attempted.
     50
     51The {{CONVERTER}} must return an object suitable for treatment as a
     52byte-source. See {{SOURCE}}.
     53
     54=== Message Digest Primitive
     55
     56==== Common Argument Definitions
     57
     58{{PRIMITIVE}} is a {{message-digest-primitive}}
     59
     60==== message-digest-primitive
     61
     62<procedure>(message-digest-primitive? OBJ) => {{boolean}}</procedure>
     63<procedure>(check-message-digest-primitive LOC OBJ [NAM])</procedure>
     64<procedure>(error-message-digest-primitive LOC OBJ [NAM])</procedure>
    8065<procedure>(message-digest-primitive-context-info PRIMITIVE)</procedure>
    8166<procedure>(message-digest-primitive-digest-length PRIMITIVE)</procedure>
     
    8570<procedure>(message-digest-primitive-name PRIMITIVE)</procedure>
    8671
    87 === message-digest-primitive-apply
    88 
    89 <procedure>(message-digest-primitive-apply MESSAGE-DIGEST-PRIMITIVE SOURCE [CALLER])</procedure>
    90 
    91 Returns 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])</parameter>
    98 
    99 The 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])</parameter>
    105 
    106 The procedure used to create an input procedure.
    107 
    108 <procedure>(READER-CREATOR INPUT-PORT) => PROCEDURE/0</procedure>
    109 
    110 The default {{READER-CREATOR}} will return a reader that takes from {{INPUT-PORT}}
    111 in {{(message-digest-chunk-size)}} bytes. The {{INPUT-PORT}} is treated as a
    112 binary-stream no matter how it is defined.
    113 
    114 === message-digest-chunk-converter
    115 
    116 <parameter>(message-digest-chunk-converter [CONVERTER])</parameter>
    117 
    118 The procedure used to translate an arbitrary Scheme-object into something
    119 suitable for an {{UPDATE}} procedure. Should the {{CONVERTER}} be
    120 {{#f}} then no translation is attempted.
    121 
    122 <procedure>(CONVERTER OBJECT) => OBJECT</procedure>
    123 
    124 The default {{CONVERTER}} will convert a {{heterogeneous-vector}} to a {{blob}}
    125 with shared-storage. No translation otherwise.
     72==== make-message-digest-primitive
     73
     74<procedure>(make-message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL ID) => {{message-digest-primitive}}</procedure>
     75
     76Create a {{message-digest-primitive}} object. The reification of a
     77message digest algorithm.
     78
     79{{CONTEXT-INFO}} is either a procedure that returns an object {{CONTEXT}}, or an
     80{{integer}}. When an integer a memory-block of length {{CONTEXT-INFO}}
     81is allocated (and automatically free'ed).
     82
     83{{CONTEXT}} is an opaque object, except when the {{CONTEXT-INFO}} is an
     84integer. In which case it is known that the object is a {{pointer}} to a block
     85of non-garbage collected memory.
     86
     87{{DIGEST-LENGTH}} is the count of bytes in the {{RESULT-STRING}}.
     88
     89 {{(INIT CONTEXT)}}
     90
     91Initialization phase procedure. Sets up the {{CONTEXT}}, if necessary.
     92
     93 {{(UPDATE CONTEXT BUFFER COUNT)}}
     94
     95Accumulation phase procedure. Must accumulate the {{BUFFER}}, where {{BUFFER}}
     96is a {{string}} or {{blob}}. Will be called one or more times.
     97
     98The foreign type specifier {{scheme-pointer}} is suitable as a foreign-lambda
     99argument type for the {{BUFFER}} argument since the contents of both are a
     100bytevector.
     101
     102Where the actual number of bytes in the {{BUFFER}} can be determined {{COUNT}} will
     103be a {{positive-integer}}.
     104
     105 {{(FINAL CONTEXT RESULT-STRING)}}
     106
     107Finalization phase procedure. Must build the resulting message-digest in the
     108supplied {{RESULT-STRING}}, a {{string}} of length {{DIGEST-LENGTH}}.
     109
     110
     111=== Message Digest
     112
     113==== Common Argument Definitions
     114
     115{{RESULT-FORM}} is one of:
     116
     117; {{'string}} : the result bytes as a string. Note - these are raw bytes, not characters!
     118; {{'hex}} : the result bytes encoded as a string of hexadecimal digits.
     119; {{'blob}} : the result bytes as a blob.
     120; {{'u8vector}} : the result bytes as a u8vector.
     121
     122{{DIGEST}} is a {{message-digest}}.
     123
     124{{ENDIAN}} is one of {{'big-endian}}, {{'little-endian}}.
     125
     126{{SOURCE}} is a Scheme object
     127
     128The {{BUFFER}} argument for the {{UPDATE}} phase, see
     129{{make-message-digest-primitive}}, is translated as:
     130
     131; {{string}} : {{BUFFER}} = {{SOURCE}}.
     132; {{blob}} : {{BUFFER}} = {{SOURCE}}.
     133; {{srfi-4-vector}} : {{BUFFER}} = {{(XXXvector->blob/shared SOURCE)}}.
     134; {{object}} : {{BUFFER}} = {{(message-digest-chunk-converter SOURCE)}}.
     135
     136(Note - the above considered byte sources)
     137
     138; {{procedure}} : updates with {{BUFFER}} = {{(procedure)}} until {{#f = (procedure)}}.
     139; {{input-port}} : like {{procedure}} above but from {{((message-digest-chunk-read-maker) SOURCE)}}.
     140
     141Should none of the above interpretations be available then an error is
     142signaled.
     143
     144==== message-digest
     145
     146<procedure>(message-digest? OBJ) => {{boolean}}</procedure>
     147<procedure>(check-message-digest LOC OBJ [NAM])</procedure>
     148<procedure>(error-message-digest LOC OBJ [NAM])</procedure>
     149<procedure>(message-algorithm DIGEST)</procedure>
     150<procedure>(message-context DIGEST)</procedure>
     151
     152==== initialize-message-digest
     153
     154<procedure>(initialize-message-digest PRIMITIVE) => {{message-digest}}</procedure>
     155
     156Create, initialize and return a {{message-digest}} for the supplied algorithm
     157{{PRIMITIVE}}.
     158
     159==== finalize-message-digest
     160
     161<procedure>(finalize-message-digest DIGEST [RESULT-FORM]) => RESULT</procedure>
     162
     163Finalize the {{DIGEST}} and return the {{RESULT}} in the {{RESULT-FORM}}.
     164
     165{{RESULT-FORM}} default is {{'hex}}.
     166
     167==== message-digest-update-object
     168
     169<procedure>(message-digest-update-object DIGEST SOURCE)</procedure>
     170
     171Update the {{DIGEST}} with some {{SOURCE}}.
     172
     173==== message-digest-update-blob
     174
     175<procedure>(message-digest-update-blob DIGEST BLOB)</procedure>
     176
     177Update the {{DIGEST}} with a {{BLOB}}.
     178
     179==== message-digest-update-string
     180
     181<procedure>(message-digest-update-string DIGEST STRING)</procedure>
     182
     183Update the {{DIGEST}} with a {{STRING}}.
     184
     185==== message-digest-update-substring
     186
     187<procedure>(message-digest-update-substring DIGEST STRING START END)</procedure>
     188
     189Update the {{DIGEST}} with a substring {{STRING START END}}.
     190
     191==== message-digest-update-u8vector
     192
     193<procedure>(message-digest-update-u8vector DIGEST U8VECTOR)</procedure>
     194
     195Update the {{DIGEST}} with a {{U8VECTOR}}.
     196
     197==== message-digest-update-subu8vector
     198
     199<procedure>(message-digest-update-subu8vector DIGEST U8VECTOR START END)</procedure>
     200
     201Update the {{DIGEST}} with a subvector {{U8VECTOR START END}}.
     202
     203==== message-digest-update-char
     204
     205<procedure>(message-digest-update-char DIGEST CHAR)</procedure>
     206
     207Update the {{DIGEST}} with a character {{CHAR}}.
     208
     209==== message-digest-update-u8
     210
     211<procedure>(message-digest-update-u8 DIGEST U8)</procedure>
     212
     213Update the {{DIGEST}} with an 8-bit integer {{U8}}.
     214
     215==== message-digest-update-u16
     216
     217<procedure>(message-digest-update-u16 DIGEST U16 [ENDIAN])</procedure>
     218
     219Update the {{DIGEST}} with a 16-bit integer {{U16}} treated as {{ENDIAN}}.
     220
     221{{ENDIAN}} default is {{(machine-byte-order)}}.
     222
     223==== message-digest-update-u16-be
     224
     225<procedure>(message-digest-update-u16-be DIGEST U16)</procedure>
     226
     227Update the {{DIGEST}} with a 16-bit integer {{U16}} treated as big-endian.
     228
     229==== message-digest-update-u16-le
     230
     231<procedure>(message-digest-update-u16-le DIGEST U16)</procedure>
     232
     233Update the {{DIGEST}} with a 16-bit integer {{U16}} treated as little-endian.
     234
     235==== message-digest-update-u32
     236
     237<procedure>(message-digest-update-u32 DIGEST U32 [ENDIAN])</procedure>
     238
     239Update the {{DIGEST}} with a 32-bit integer {{U32}} treated as {{ENDIAN}}.
     240
     241{{ENDIAN}} default is {{(machine-byte-order)}}.
     242
     243==== message-digest-update-u32-be
     244
     245<procedure>(message-digest-update-u32-be DIGEST U32)</procedure>
     246
     247Update the {{DIGEST}} with a 32-bit integer {{U32}} treated as big-endian.
     248
     249==== message-digest-update-u32-le
     250
     251<procedure>(message-digest-update-u32-le DIGEST U32)</procedure>
     252
     253Update the {{DIGEST}} with a 32-bit integer {{U32}} treated as little-endian.
     254
     255==== message-digest-update-u64
     256
     257<procedure>(message-digest-update-u64 DIGEST U64 [ENDIAN])</procedure>
     258
     259Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as {{ENDIAN}}.
     260
     261{{ENDIAN}} default is {{(machine-byte-order)}}.
     262
     263==== message-digest-update-u64-be
     264
     265<procedure>(message-digest-update-u64-be DIGEST U64)</procedure>
     266
     267Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as big-endian.
     268
     269==== message-digest-update-u64-le
     270
     271<procedure>(message-digest-update-u64-le DIGEST U64)</procedure>
     272
     273Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as little-endian.
     274
     275==== message-digest-update-procedure
     276
     277<procedure>(message-digest-update-procedure DIGEST THUNK)</procedure>
     278
     279Update the {{DIGEST}} with a {{THUNK}} until it returns {{#f}}.
     280
     281{{THUNK}} should return either a {{string}} or a {{blob}} but any object
     282meeting the criteria of {{SOURCE}}, except a {{procedure}} or an
     283{{input-port}}, is acceptable.
     284
     285==== message-digest-update-port
     286
     287<procedure>(message-digest-update-port DIGEST INPUT-PORT)</procedure>
     288
     289Update the {{DIGEST}} with contents from an {{INPUT-PORT}} until EOF.
     290
     291Uses the {{message-digest-chunk-read-maker}} to create a reader for the port.
     292
     293==== message-digest-update-file
     294
     295<procedure>(message-digest-update-file DIGEST FILENAME)</procedure>
     296
     297Update the {{DIGEST}} with the entrire contents of file {{FILENAME}}.
     298
     299==== message-digest-object
     300
     301<procedure>(message-digest-object PRIMITIVE SOURCE [RESULT-FORM]) => RESULT</procedure>
     302
     303Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     304{{SOURCE}} in the {{RESULT-FORM}}.
     305
     306{{RESULT-FORM}} default is {{'hex}}.
     307
     308==== message-digest-string
     309
     310<procedure>(message-digest-string PRIMITIVE STRING [RESULT-FORM]) => RESULT</procedure>
     311
     312Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     313{{STRING}} in the {{RESULT-FORM}}.
     314
     315{{RESULT-FORM}} default is {{'hex}}.
     316
     317==== message-digest-blob
     318
     319<procedure>(message-digest-blob PRIMITIVE BLOB [RESULT-FORM]) => RESULT</procedure>
     320
     321Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     322{{BLOB}} in the {{RESULT-FORM}}.
     323
     324{{RESULT-FORM}} default is {{'hex}}.
     325
     326==== message-digest-u8vector
     327
     328<procedure>(message-digest-u8vector PRIMITIVE U8VECTOR [RESULT-FORM]) => RESULT</procedure>
     329
     330Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     331{{U8VECTOR}} in the {{RESULT-FORM}}.
     332
     333{{RESULT-FORM}} default is {{'hex}}.
     334
     335==== message-digest-file
     336
     337<procedure>(message-digest-file PRIMITIVE FILENAME [RESULT-FORM]) => RESULT</procedure>
     338
     339Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     340the file {{FILENAME}} in the {{RESULT-FORM}}.
     341
     342{{RESULT-FORM}} default is {{'hex}}.
     343
     344==== *message-digest-update
     345
     346<procedure>(*message-digest-update DIGEST SOURCE LENGTH)</procedure>
     347
     348
     349
     350=== Message Digest Port
     351
     352==== Common Argument Definitions
     353
     354{{PORT}} is a {{digest-output-port}}.
     355
     356==== digest-output-port
     357
     358<procedure>(digest-output-port? OBJ) => {{boolean}}</procedure>
     359<procedure>(check-digest-output-port LOC OBJ [NAM])</procedure>
     360<procedure>(error-digest-output-port LOC OBJ [NAM])</procedure>
     361<procedure>(digest-output-port-name PORT) => {{string}}</procedure>
     362
     363==== open-output-digest
     364
     365<procedure>(open-output-digest PRIMITIVE) => {{digest-output-port}}</procedure>
     366
     367Returns a message digest output port for the supplied algorithm {{PRIMITIVE}}.
     368
     369==== close-output-digest
     370
     371<procedure>(close-output-digest PORT [RESULT-FORM]) => RESULT</procedure>
     372
     373Closes the {{PORT}} and returns the {{RESULT}} in the {{RESULT-FORM}}.
     374
     375{{RESULT-FORM}} default is {{'hex}}.
     376
     377==== get-output-digest-string
     378
     379<procedure>(get-output-digest-string PORT)</procedure>
     380<procedure>(get-output-digest-byte-string PORT)</procedure>
     381
     382Closes the {{PORT}} and returns the {{RESULT}} as a {{string}}.
     383
     384==== get-output-digest-hexstring
     385
     386<procedure>(get-output-digest-hexstring PORT)</procedure>
     387
     388Closes the {{PORT}} and returns the {{RESULT}} as a {{string}}.
     389
     390==== get-output-digest-blob
     391
     392<procedure>(get-output-digest-blob PORT)</procedure>
     393
     394Closes the {{PORT}} and returns the {{RESULT}} as a {{blob}}.
     395
     396==== get-output-digest-u8vector
     397
     398<procedure>(get-output-digest-u8vector PORT)</procedure>
     399
     400Closes the {{PORT}} and returns the {{RESULT}} as a {{u8vector}}.
     401
     402==== call-with-output-digest
     403
     404<procedure>(call-with-output-digest PRIMITIVE PROCEDURE/1 [RESULT-FORM])</procedure>
     405
     406Invoke the procedure {{PROCEDURE PORT}} with {{digest-output-port}} and return
     407{{RESULT}} in the {{RESULT-FORM}}.
     408
     409{{RESULT-FORM}} default is {{'hex}}.
     410
     411==== with-output-to-digest
     412
     413<procedure>(with-output-to-digest PRIMITIVE THUNK [RESULT-FORM])</procedure>
     414
     415Invoke the procedure {{THUNK}} with {{(current-output-port)}} bound to a
     416{{digest-output-port}} and return {{RESULT}} in the {{RESULT-FORM}}.
     417
     418{{RESULT-FORM}} default is {{'hex}}.
     419
    126420
    127421=== Auxillary Procedures
    128422
    129 ==== byte-string->substring-list
    130 
    131 <procedure>(byte-string->substring-list STRING CHUNK-SIZE [START [END]]) => LIST</procedure>
    132 
    133 Returns a list of {{CHUNK-SIZE}} substrings of {{STRING}}, on the interval
    134 [{{START}} {{END}}). Defaults are [0 string-length).
    135 
    136 Any 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</procedure>
    141 
    142 Returns a list of {{CHUNK-SIZE}} substrings of {{STRING}}, on the interval
    143 [{{START}} {{END}}). Defaults are [0 byte-string-length).
    144 
    145 Any remaining substring less than {{CHUNK-SIZE}} is appended to the list.
    146 
    147 The substrings can share storage with the {{STRING}}!
    148 
    149423==== byte-string->hexadecimal
    150424
    151 <procedure>(byte-string->hexadecimal STRING [START [END]]) => STRING</procedure>
     425<procedure>(byte-string->hexadecimal STRING [START [END]]) => {{string}}</procedure>
     426<procedure>(string->hex STRING [START [END]]) => {{string}}</procedure>
    152427
    153428Returns a hex-encoded representation of {{STRING}}, on the interval [{{START}}
    154 {{END}}). Defaults are [0 byte-string-length).
    155 
    156 
    157 == Examples
    158 
    159 Here's an example for creating a digest from the output of a procedure
    160 that expects to be called with an output port argument:
     429{{END}}). Defaults are [{{0}} {{string-length}}).
     430
     431
     432=== Old API
     433
     434==== make-binary-message-digest (DEPRECATED)
     435
     436<procedure>(make-binary-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => {{string}}</procedure>
     437
     438Returns the message-digest for {{SOURCE}} as a string of bytes.
     439
     440{{SOURCE}} is a Scheme-object.
     441
     442The meaning of the other fields are as for {{make-message-digest-primitive}}.
     443
     444The optional {{CALLER}} is for identification.
     445
     446See {{message-digest-chunk-size}} to set the number of bytes read from a port.
     447
     448See {{message-digest-chunk-read-maker}} to set the chunk reader procedure creator.
     449
     450See {{message-digest-chunk-converter}} to set the chunk representation translation procedure.
     451
     452==== make-message-digest (DEPRECATED)
     453
     454<procedure>(make-message-digest SOURCE CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [CALLER]) => {{string}}</procedure>
     455
     456Exactly as {{make-binary-message-digest}} but returns the message-digest for
     457{{SOURCE}} using {{byte-string->hexadecimal}}.
     458
     459==== message-digest-primitive-apply (DEPRECATED)
     460
     461<procedure>(message-digest-primitive-apply PRIMITIVE SOURCE [CALLER])</procedure>
     462
     463Returns a binary-message-digest of {{SOURCE}} using {{PRIMITIVE}}.
     464
     465
     466== Usage
    161467
    162468<enscript highlight=scheme>
    163469(use message-digest)
    164 
    165 (define (call-with-output-digest primitive proc)
    166   (let* ((ctx-info (message-digest-primitive-context-info primitive))
    167          (update-digest (message-digest-primitive-update primitive))
    168          ;; Create new context, by allocating manually or calling the procedure
    169          (ctx (if (procedure? ctx-info) (ctx-info) (allocate ctx-info)))
    170          ;; Create a procedure that updates the digest based on a string
    171          (update (lambda (str) (update-digest ctx str (string-length str))))
    172          ;; Make a port that invokes the updater when written to
    173          (outport (make-output-port update void)))
    174     (handle-exceptions exn
    175       ;; If something goes wrong, clean up the context if we allocated it
    176       (begin (unless (procedure? ctx-info) (free ctx)) (signal exn))
    177       (let ((result (make-string
    178                      (message-digest-primitive-digest-length primitive))))
    179         ((message-digest-primitive-init primitive) ctx)
    180         (proc outport)
    181         ((message-digest-primitive-final primitive) ctx result)
    182         ;; Don't forget to free the context if we allocated it
    183         (unless (procedure? ctx-info) (free ctx))
    184         ;; Output is a byte string.  Convert to a hex number:
    185         (byte-string->hexadecimal result)))))
    186 
    187 ;; Usage:
     470</enscript>
     471
     472To access the message-digest port abstraction:
     473
     474<enscript highlight=scheme>
     475(use message-digest-port)
     476</enscript>
     477
     478
     479== Examples
     480
     481Uses the message-digest port abstraction to get an MD5 digest of a string:
     482
     483<enscript highlight=scheme>
     484(use message-digest-port)
    188485(use md5)    ; Or sha1, or sha2, ...
    189486
    190 (call-with-output-digest
    191   (md5-primitive)
    192   (lambda (out)
    193     (display "foo" out)))
     487(call-with-output-digest (md5-primitive) (cut display "foo" <>))
     488;=> "ACBD18DB4CC2F85CEDEF654FCCC4A4D8"
    194489</enscript>
     490
    195491
    196492== Notes
     
    199495{{->blob/shared}} procedures.
    200496
     497
    201498== Requirements
    202499
     
    204501[[check-errors]]
    205502
     503
    206504== Bugs and Limitations
    207505
    208 * Uses the core {{string}} type for a message-digest. Probably should use a {{blob}}.
    209 
    210 * {{byte-string->substring-list/shared}}, {{byte-string->substring-list}}, and
    211 {{byte-string->hexadecimal}} do not really belong here.
     506* Uses a {{string}} for the message-digest result, should use a {{blob}}.
     507
     508* {{byte-string->hexadecimal}} does not really belong here.
    212509
    213510
     
    219516== Version history
    220517
     518; 2.1.0 : Added message digest "phase" and port APIs. Deprecated old API.
    221519; 2.0.1 : Bug fix for {{(message-digest-chunk-converter)}} use by {{make-binary-message-digest}}.
    222520; 2.0.0 : Release for Chicken 4 [From a diff provided by Christian Kellermann]
     
    225523== License
    226524
    227   Copyright (C) 2009 Kon Lovett.  All rights reserved.
    228  
     525  Copyright (C) 2006-2010 Kon Lovett.  All rights reserved.
     526
    229527  Permission is hereby granted, free of charge, to any person obtaining a
    230528  copy of this software and associated documentation files (the Software),
     
    233531  and/or sell copies of the Software, and to permit persons to whom the
    234532  Software is furnished to do so, subject to the following conditions:
    235  
     533
    236534  The above copyright notice and this permission notice shall be included
    237535  in all copies or substantial portions of the Software.
    238  
     536
    239537  THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    240538  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Note: See TracChangeset for help on using the changeset viewer.