From 67d00dc4ce131d5cc46f4041dbf40391697e281d Mon Sep 17 00:00:00 2001 From: Piotr Szarmanski Date: Sun, 25 Sep 2022 00:55:55 +0200 Subject: Clean up docstrings and type declarations. --- src/eris.lisp | 65 ++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 21 deletions(-) (limited to 'src/eris.lisp') diff --git a/src/eris.lisp b/src/eris.lisp index b30c6a4..5e3ed2a 100644 --- a/src/eris.lisp +++ b/src/eris.lisp @@ -15,15 +15,6 @@ (in-package :eris) -(defun pad (input block-size) - (declare (type (simple-array (unsigned-byte 8)) input) - (type integer block-size)) - (let* ((pad-size (- block-size (mod (length input) block-size))) - (padded-input (adjust-array input (+ pad-size (length input)) :initial-element 0))) - (replace padded-input input) - (setf (aref padded-input (length input)) #x80) - padded-input)) - (deftype block-size () `(member 1024 32768)) @@ -36,14 +27,22 @@ ((reference :initarg :reference :accessor reference :type (simple-array (unsigned-byte 8) 32)) (key :initarg :key :accessor key :type (simple-array (unsigned-byte 8) 32))))) -(define-constant null-secret (make-array 32 :element-type '(unsigned-byte 8) :initial-element 0) :test #'equalp) +(define-constant null-secret (make-array 32 :element-type '(unsigned-byte 8) :initial-element 0) + :test #'equalp + :documentation + "32-byte null vector.") (defun reference-pair-to-octets (pair buf &optional (start 0)) - (replace buf (reference pair) :start1 start) + "Convert a reference-pair object PAIR into the standard binary representation by +filling the buffer BUF from the START keyword argument. " + (declare (type vector buf)) + (replace buf (reference pair) :start1 start) (replace buf (key pair) :start1 (+ 32 start))) (defun octets-to-reference-pair (octets &optional (start 0)) - (declare (type (simple-array (unsigned-byte 8)) octets)) + "Convert the standard reference-pair binary representation into a reference-pair +object, using the bytes from the OCTETS vector from at START." + (declare (type vector octets)) (make-instance 'reference-pair :key (subseq octets (+ 32 start) (+ 64 start)) :reference (subseq octets start (+ 32 start)))) @@ -54,8 +53,6 @@ (ironclad:digest-sequence :blake2/256 block :digest reference) reference)) -(declaim (inline make-nonce)) - (defun make-nonce (level) (let ((nonce (make-array 12 :element-type '(unsigned-byte 8) :initial-element 0))) (setf (aref nonce 0) level) @@ -98,20 +95,31 @@ :type block-size :documentation "A value of either 1024 or 1kb blocks.") (level :initarg :level :accessor level :type (unsigned-byte 8)) - (root-reference-pair :initarg :reference-pair :accessor reference-pair))) - + (root-reference-pair :initarg :reference-pair :accessor reference-pair)) + (:documentation "Class representing the concept of an ERIS read capability.")) +(declaim + (ftype (function (read-capability) (values (simple-array (unsigned-byte 8) (66)) &optional)) read-capability-to-octets) + (ftype (function ((simple-array (unsigned-byte 8) (66))) read-capability) octets-to-read-capability) + (ftype (function (read-capability) string) read-capability-to-urn) + (ftype (function (string) read-capability) urn-to-read-capability) + (ftype (function ((simple-array (unsigned-byte 8) (32))) string) reference-to-block-urn) + (ftype (function (string) (values (simple-array (unsigned-byte 8) (32)) &optional)) block-urn-to-reference)) (defun read-capability-to-octets (read-capability) + "Convert a read-capability object to its standard binary representation. Returns +a (simple-array (unsigned-byte 8)) object." (declare (type read-capability read-capability)) (let ((cap (make-array 66 :element-type '(unsigned-byte 8)))) (case (block-size read-capability) ;; This depends on the version of the standard - (1024 (setf (aref cap 0) #x0a)) - (32768 (setf (aref cap 0) #x0f))) + (1024 (setf (aref cap 0) #x0a)) + (32768 (setf (aref cap 0) #x0f))) (setf (aref cap 1) (level read-capability)) (reference-pair-to-octets (reference-pair read-capability) cap 2))) (defun octets-to-read-capability (octets) + "Convert the standard binary representation for ERIS read capabilities into a +read-capability object. Returns the read-capability." (declare (type (simple-array (unsigned-byte 8) (66)) octets)) (let ((capability (make-instance 'read-capability))) (setf (block-size capability) @@ -126,21 +134,36 @@ capability)) (defun read-capability-to-urn (capability) + "Convert a read-capability object into a URN string." + (declare (type read-capability capability)) (concatenate 'string "urn:eris:" (bytes-to-base32-unpadded (read-capability-to-octets capability)))) (defun urn-to-read-capability (urn) + "Convert a urn:eris URN string into a read-capability object." + (declare (type string urn)) (octets-to-read-capability (base32-to-bytes-unpadded (subseq urn (1+ (position #\: urn :from-end t)))))) (defun reference-to-block-urn (reference) + "Convert a 32-byte block reference into a URN string." (declare (type (simple-array (unsigned-byte 8) (32)) reference)) (concatenate 'string "urn:blake2b:" (bytes-to-base32-unpadded reference))) (defun block-urn-to-reference (urn) + "Convert a urn:blake2b URN string into a 32-byte block reference vector." (declare (type string urn)) (base32-to-bytes-unpadded (subseq urn (1+ (position #\: urn :from-end t))))) +(defun pad (input block-size) + (declare (type (simple-array (unsigned-byte 8)) input) + (type integer block-size)) + (let* ((pad-size (- block-size (mod (length input) block-size))) + (padded-input (adjust-array input (+ pad-size (length input)) :initial-element 0))) + (replace padded-input input) + (setf (aref padded-input (length input)) #x80) + padded-input)) + (defvar *output-hashmap* nil) (defmacro output-block (ref-vector &rest expr) @@ -230,9 +253,9 @@ An optional 32-byte secret can be passed for additional encryption using the for rk across reference-vector with i = 0 when (eql i block-keys) - do (output-internal-block reference-vector-l nonce - (setf block (make-array block-size :element-type '(unsigned-byte 8) :initial-element 0) - i 0)) + do (output-internal-block reference-vector-l nonce + (setf block (make-array block-size :element-type '(unsigned-byte 8) :initial-element 0) + i 0)) do (progn (reference-pair-to-octets rk block (* 64 i)) (incf i)) finally (unless (zerop i) -- cgit v1.2.3