diff --git a/md5.lisp b/md5.lisp index d1a47c9..af23638 100644 --- a/md5.lisp +++ b/md5.lisp @@ -348,7 +348,7 @@ accordingly." (declaim (inline fill-block fill-block-ub8 fill-block-char)) (defun fill-block-ub8 (block buffer offset) "Convert a complete 64 (unsigned-byte 8) input vector segment -starting from offset into the given 16 word MD5 block." +starting from `offset' into the given 16 word MD5 block." (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset) (type md5-block block) (type (simple-array (unsigned-byte 8) (*)) buffer) @@ -373,8 +373,8 @@ starting from offset into the given 16 word MD5 block." (aref buffer (+ j 3)))))) (defun fill-block-char (block buffer offset) - "Convert a complete 64 character input string segment starting from -offset into the given 16 word MD5 block." + "DEPRECATED: Convert a complete 64 character input string segment +starting from `offset' into the given 16 word MD5 block." (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset) (type md5-block block) (type simple-string buffer) @@ -402,7 +402,8 @@ offset into the given 16 word MD5 block." "Convert a complete 64 byte input vector segment into the given 16 word MD5 block. This currently works on (unsigned-byte 8) and character simple-arrays, via the functions `fill-block-ub8' and -`fill-block-char' respectively." +`fill-block-char' respectively. Note that it will not work correctly +on character simple-arrays if `char-code-limit' is greater than 256." (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset) (type md5-block block) (type (simple-array * (*)) buffer) @@ -419,7 +420,7 @@ character simple-arrays, via the functions `fill-block-ub8' and (declaim (inline md5regs-digest)) (defun md5regs-digest (regs) "Create the final 16 byte message-digest from the MD5 working state -in regs. Returns a (simple-array (unsigned-byte 8) (16))." +in `regs'. Returns a (simple-array (unsigned-byte 8) (16))." (declare (optimize (speed 3) (safety 0) (space 0) (debug 0) #+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0)) (type md5-regs regs)) @@ -458,9 +459,9 @@ in regs. Returns a (simple-array (unsigned-byte 8) (16))." (declaim (inline copy-to-buffer)) (defun copy-to-buffer (from from-offset count buffer buffer-offset) - "Copy a partial segment from input vector from starting at -from-offset and copying count elements into the 64 byte buffer -starting at buffer-offset." + "Copy a partial segment from input vector `from' starting at +`from-offset' and copying `count' elements into the 64 byte buffer +starting at `buffer-offset'." (declare (optimize (speed 3) (safety 0) (space 0) (debug 0) #+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0)) (type (unsigned-byte 29) from-offset) @@ -494,9 +495,13 @@ starting at buffer-offset." from-index)))))) (defun update-md5-state (state sequence &key (start 0) (end (length sequence))) - "Update the given md5-state from sequence, which is either a + "Update the given md5-state from `sequence', which is either a simple-string or a simple-array with element-type (unsigned-byte 8), -bounded by start and end, which must be numeric bounding-indices." +bounded by `start' and `end', which must be numeric bounding-indices. +Note that usage on simple-strings is DEPRECATED, since this will not +work correctly if `char-code-limit' is more than 256. String input +should be converted to (unsigned-byte 8) simple-arrays with +external-format conversion routines beforehand." (declare (type md5-state state) (type (simple-array * (*)) sequence) (type fixnum start end) @@ -613,10 +618,13 @@ The resulting MD5 message-digest is returned as an array of sixteen ;;; High-Level Drivers (defun md5sum-sequence (sequence &key (start 0) end) - "Calculate the MD5 message-digest of data in sequence. On CMU CL -this works for all sequences whose element-type is supported by the -underlying MD5 routines, on other implementations it only works for 1d -simple-arrays with such element types." + "Calculate the MD5 message-digest of data in `sequence', which should +be a 1d simple-array with element type (unsigned-byte 8). On CMU CL +and SBCL non-simple and non-1d arrays with this element-type are also +supported. Use with strings is DEPRECATED, since this will not work +correctly on implementations with `char-code-limit' > 256 and ignores +character-coding issues. Use md5sum-string instead, or convert to the +required (unsigned-byte 8) format through other means before-hand." (declare (optimize (speed 3) (safety 3) (space 0) (debug 1)) (type vector sequence) (type fixnum start)) (locally @@ -645,10 +653,12 @@ simple-arrays with such element types." (finalize-md5-state state)))) (defun md5sum-string (string &key (external-format :default) (start 0) end) - "Calculate the MD5 message-digest of the binary representation -of STRING (as octets) in EXTERNAL-FORMAT. The boundaries START -and END refer to character positions in the string, not to octets -in the resulting binary representation." + "Calculate the MD5 message-digest of the binary representation of +`string' (as octets) in the external format specified by +`external-format'. The boundaries `start' and `end' refer to character +positions in the string, not to octets in the resulting binary +representation. The permissible external format specifiers are +determined by the underlying implementation." (declare (optimize (speed 3) (safety 3) (space 0) (debug 1)) (type string string) (type fixnum start)) (locally @@ -688,14 +698,16 @@ in the resulting binary representation." (eval-when (:compile-toplevel :load-toplevel :execute) (defconstant +buffer-size+ (* 128 1024) - "Size of internal buffer to use for md5sum-stream and md5sum-file + "Size of internal buffer to use for `md5sum-stream' and `md5sum-file' operations. This should be a multiple of 64, the MD5 block size.")) (deftype buffer-index () `(integer 0 ,+buffer-size+)) (defun md5sum-stream (stream) - "Calculate an MD5 message-digest of the contents of stream. Its -element-type has to be either (unsigned-byte 8) or character." + "Calculate an MD5 message-digest of the contents of `stream'. Its +element-type has to be (unsigned-byte 8). Use on character streams is +DEPRECATED, as this will not work correctly on implementations with +`char-code-limit' > 256 and ignores character coding issues." (declare (optimize (speed 3) (safety 3) (space 0) (debug 1))) (locally (declare (optimize (safety 1) (debug 0))) @@ -725,7 +737,7 @@ element-type has to be either (unsigned-byte 8) or character." (stream-element-type stream) stream)))))) (defun md5sum-file (pathname) - "Calculate the MD5 message-digest of the file specified by pathname." + "Calculate the MD5 message-digest of the file specified by `pathname'." (declare (optimize (speed 3) (safety 3) (space 0) (debug 1))) (with-open-file (stream pathname :element-type '(unsigned-byte 8)) (md5sum-stream stream)))