The sha3 Reference Manual

This is the sha3 Reference Manual, version 1.1.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 07:41:12 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 sha3

Secure Hash Algorithm 3 (Keccak) Implementation

Maintainer

Pierre R. Mai <>

Author

Pierre R. Mai <>

License

MIT/X11

Version

1.1.2

Dependency

sb-rotate-byte (system).

Source

sha3.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 sha3/sha3.asd

Source

sha3.asd.

Parent Component

sha3 (system).

ASDF Systems

sha3.


3.1.2 sha3/pkgdef.lisp

Source

sha3.asd.

Parent Component

sha3 (system).

Packages

sha3.


3.1.3 sha3/common.lisp

Dependency

pkgdef.lisp (file).

Source

sha3.asd.

Parent Component

sha3 (system).

Internals

3.1.4 sha3/keccak-64bit.lisp

Dependencies
Source

sha3.asd.

Parent Component

sha3 (system).

Internals

3.1.5 sha3/sha3.lisp

Dependencies
Source

sha3.asd.

Parent Component

sha3 (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 sha3

Source

pkgdef.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Ordinary functions

Function: sha3-copy (state)

Return an independent copy of the SHA-3 state ‘state’.

Package

sha3.

Source

sha3.lisp.

Function: sha3-digest-file (pathname &key output-bit-length raw-keccak-p)

Calculate an SHA-3 message-digest of the file specified by ‘pathname’. The bit length of the message digest produced is controlled by ‘output-bit-length’, which can take on the values 224, 256, 288, 384 and 512, which is the default value. Using the optional ‘raw-keccak-p’ keyword argument the SHA-3 mandated 01 suffix that is appended to the actual message prior to padding can be elided to yield message digests that match the original Keccak submission instead of the actual SHA-3 standard. Use this option only for compatibility with historical implementations.

Package

sha3.

Source

sha3.lisp.

Function: sha3-digest-stream (stream &key output-bit-length raw-keccak-p)

Calculate an SHA-3 message-digest of data read from ‘stream’, which should be a stream with element type (unsigned-byte 8). The bit length of the message digest produced is controlled by ‘output-bit-length’, which can take on the values 224, 256, 288, 384 and 512, which is the default value. Using the optional ‘raw-keccak-p’ keyword argument the SHA-3 mandated 01 suffix that is appended to the actual message prior to padding can be elided to yield message digests that match the original Keccak submission instead of the actual SHA-3 standard. Use this option only for compatibility with historical implementations.

Package

sha3.

Source

sha3.lisp.

Function: sha3-digest-vector (vector &key start end output-bit-length raw-keccak-p)

Calculate an SHA-3 message-digest of data in ‘vector’, which should be a 1d simple-array with element type (unsigned-byte 8), bounded by ‘start’ and ‘end’. The bit length of the message digest produced is controlled by ‘output-bit-length’, which can take on the values 224, 256, 288, 384 and 512, which is the default value. Using the optional ‘raw-keccak-p’ keyword argument the SHA-3 mandated 01 suffix that is appended to the actual message prior to padding can be elided to yield message digests that match the original Keccak submission instead of the actual SHA-3 standard. Use this option only for compatibility with historical implementations.

Package

sha3.

Source

sha3.lisp.

Function: sha3-final (state &key output-bit-length raw-keccak-p)

If the given SHA-3 state ‘state’ has not already been finalized, finalize it by processing any remaining input in its buffer, with the specified suffix of 01 and suitable padding as specified by the SHA-3 standard (the specified SHA-3 suffix can be elided with the optional keyword argument ‘raw-keccak-p’ to generate digests as the initial Keccak submission would have generated). Returns the message digest as a simple-array of (unsigned-byte 8). The length of the returned digest is determined either by the output bit length or bit rate specified on state creation, or for the special case of default parameters being used, by the optional keyword argument ‘output-bit-length’. If the state has previously been finalized, the function will return the digest again.

Package

sha3.

Source

sha3.lisp.

Function: sha3-init (&key output-bit-length bit-rate)

Create and return a new SHA-3 state. If ‘output-bit-length’ is specified then the state will run at the bit rate specified for the given output bit length. If ‘output-bit-length’ is unspecified, ‘bit-rate’ can be specified to select a suitable bit rate. If both are left unspecified then a default bit rate of 1024 bits is selected, which is suitable for arbitrary output bit lengths of up to 288 bits.

Package

sha3.

Source

sha3.lisp.

Function: sha3-state-p (object)
Package

sha3.

Source

sha3.lisp.

Function: sha3-update (state vector &key start end)

Update the given SHA-3 state ‘state’ from ‘vector’, which must be a simple-array with element-type (unsigned-byte 8), bounded by ‘start’ and ‘end’, which must be numeric bounding-indices.

Package

sha3.

Source

sha3.lisp.


5.1.2 Structures

Structure: sha3-state
Package

sha3.

Source

sha3.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: state
Type

sha3::keccak-1600-state

Initform

(sha3::make-keccak-1600-state)

Readers

sha3-state-state.

Writers

This slot is read-only.

Slot: bit-rate
Type

(integer 0 1600)

Initform

1024

Readers

sha3-state-bit-rate.

Writers

This slot is read-only.

Slot: buffer
Type

(simple-array (unsigned-byte 8) (200))

Initform

(make-array 200 :element-type (quote (unsigned-byte 8)))

Readers

sha3-state-buffer.

Writers

This slot is read-only.

Slot: buffer-index
Type

(integer 0 199)

Initform

0

Readers

sha3-state-buffer-index.

Writers

(setf sha3-state-buffer-index).

Slot: finalized-p
Readers

sha3-state-finalized-p.

Writers

(setf sha3-state-finalized-p).


5.2 Internals


5.2.1 Constants

Constant: +buffer-size+

Size of internal buffer to use for ‘sha3-digest-stream’ and ‘sha3-digest-file’ operations.

Package

sha3.

Source

sha3.lisp.

Constant: +keccak-1600-lane-byte-width+

Lane width in bytes for Keccak-1600.

Package

sha3.

Source

common.lisp.

Constant: +keccak-1600-lane-width+

Lane width for Keccak-1600.

Package

sha3.

Source

common.lisp.

Constant: +keccak-state-columns+

Width of Keccak state in the x axis

Package

sha3.

Source

common.lisp.

Constant: +keccak-state-lanes+

Total number of lanes in Keccak state

Package

sha3.

Source

common.lisp.

Constant: +keccak-state-rows+

Width of Keccak state in the y axis

Package

sha3.

Source

common.lisp.


5.2.2 Special variables

Special Variable: *keccak-f-rotate-offsets*

Keccak Rotate Offsets

Package

sha3.

Source

common.lisp.

Special Variable: *keccak-f-round-constants*

Keccak Round Constants

Package

sha3.

Source

common.lisp.

Special Variable: *optimize-declaration*

Global optimize declaration used for performance critical functions. This can be changed prior to compiling the package for debugging/testing purposes.

Package

sha3.

Source

common.lisp.


5.2.3 Macros

Macro: dotimes-unrolled ((var limit) &body body)

Unroll the loop body at compile-time.

Package

sha3.

Source

common.lisp.

Macro: get-rotate-offset (x y)
Package

sha3.

Source

common.lisp.

Macro: with-state-accessors ((&rest states) &body body)

Bind the contents of the state(s) array(s) to local variables, and save the content on normal form exit.

Package

sha3.

Source

keccak-64bit.lisp.

Macro: with-temp-rows ((&rest rows) &body body)

Bind local variables for each temporary row.

Package

sha3.

Source

keccak-64bit.lisp.

Macro: with-temp-state ((&rest temps) &body body)

Bind local variables for each temporary state.

Package

sha3.

Source

keccak-64bit.lisp.


5.2.4 Ordinary functions

Function: copy-sha3-state (instance)
Package

sha3.

Source

sha3.lisp.

Function: keccak-f (a)
Package

sha3.

Source

keccak-64bit.lisp.

Function: keccak-f-rot (value offset)
Package

sha3.

Source

keccak-64bit.lisp.

Function: keccak-f-round-constant (i)
Package

sha3.

Source

keccak-64bit.lisp.

Function: keccak-state-extract-output (state output-bits)
Package

sha3.

Source

keccak-64bit.lisp.

Function: keccak-state-merge-input (state bit-rate input start)
Package

sha3.

Source

keccak-64bit.lisp.

Function: make-keccak-1600-state ()
Package

sha3.

Source

keccak-64bit.lisp.

Function: make-sha3-state (bit-rate)
Package

sha3.

Source

sha3.lisp.

Function: pad-message-to-width (message bit-width add-fips-202-suffix-p)

Destructively pad the given message to the given bit-width according to the Keccak 10*1 padding rules, optionally appending the FIPS 202/SHA-3 mandated 01 suffix first, and return the padded message.

Package

sha3.

Source

common.lisp.

Reader: sha3-state-bit-rate (instance)
Package

sha3.

Source

sha3.lisp.

Target Slot

bit-rate.

Reader: sha3-state-buffer (instance)
Package

sha3.

Source

sha3.lisp.

Target Slot

buffer.

Reader: sha3-state-buffer-index (instance)
Writer: (setf sha3-state-buffer-index) (instance)
Package

sha3.

Source

sha3.lisp.

Target Slot

buffer-index.

Reader: sha3-state-finalized-p (instance)
Writer: (setf sha3-state-finalized-p) (instance)
Package

sha3.

Source

sha3.lisp.

Target Slot

finalized-p.

Reader: sha3-state-state (instance)
Package

sha3.

Source

sha3.lisp.

Target Slot

state.

Function: trivial-macroexpand-all (form env)

Trivial and very restricted code-walker used in partial evaluation macros. Only supports atoms and function forms, no special forms.

Package

sha3.

Source

common.lisp.


5.2.5 Types

Type: buffer-index ()
Package

sha3.

Source

sha3.lisp.

Type: keccak-1600-lane ()

Type of a keccak lane for Keccak-1600.

Package

sha3.

Source

common.lisp.

Type: keccak-1600-state ()

Type of a keccak working state object for Keccak-1600.

Package

sha3.

Source

keccak-64bit.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   F   G   K   M   P   S   T   W  
Index Entry  Section

(
(setf sha3-state-buffer-index): Private ordinary functions
(setf sha3-state-finalized-p): Private ordinary functions

C
copy-sha3-state: Private ordinary functions

D
dotimes-unrolled: Private macros

F
Function, (setf sha3-state-buffer-index): Private ordinary functions
Function, (setf sha3-state-finalized-p): Private ordinary functions
Function, copy-sha3-state: Private ordinary functions
Function, keccak-f: Private ordinary functions
Function, keccak-f-rot: Private ordinary functions
Function, keccak-f-round-constant: Private ordinary functions
Function, keccak-state-extract-output: Private ordinary functions
Function, keccak-state-merge-input: Private ordinary functions
Function, make-keccak-1600-state: Private ordinary functions
Function, make-sha3-state: Private ordinary functions
Function, pad-message-to-width: Private ordinary functions
Function, sha3-copy: Public ordinary functions
Function, sha3-digest-file: Public ordinary functions
Function, sha3-digest-stream: Public ordinary functions
Function, sha3-digest-vector: Public ordinary functions
Function, sha3-final: Public ordinary functions
Function, sha3-init: Public ordinary functions
Function, sha3-state-bit-rate: Private ordinary functions
Function, sha3-state-buffer: Private ordinary functions
Function, sha3-state-buffer-index: Private ordinary functions
Function, sha3-state-finalized-p: Private ordinary functions
Function, sha3-state-p: Public ordinary functions
Function, sha3-state-state: Private ordinary functions
Function, sha3-update: Public ordinary functions
Function, trivial-macroexpand-all: Private ordinary functions

G
get-rotate-offset: Private macros

K
keccak-f: Private ordinary functions
keccak-f-rot: Private ordinary functions
keccak-f-round-constant: Private ordinary functions
keccak-state-extract-output: Private ordinary functions
keccak-state-merge-input: Private ordinary functions

M
Macro, dotimes-unrolled: Private macros
Macro, get-rotate-offset: Private macros
Macro, with-state-accessors: Private macros
Macro, with-temp-rows: Private macros
Macro, with-temp-state: Private macros
make-keccak-1600-state: Private ordinary functions
make-sha3-state: Private ordinary functions

P
pad-message-to-width: Private ordinary functions

S
sha3-copy: Public ordinary functions
sha3-digest-file: Public ordinary functions
sha3-digest-stream: Public ordinary functions
sha3-digest-vector: Public ordinary functions
sha3-final: Public ordinary functions
sha3-init: Public ordinary functions
sha3-state-bit-rate: Private ordinary functions
sha3-state-buffer: Private ordinary functions
sha3-state-buffer-index: Private ordinary functions
sha3-state-finalized-p: Private ordinary functions
sha3-state-p: Public ordinary functions
sha3-state-state: Private ordinary functions
sha3-update: Public ordinary functions

T
trivial-macroexpand-all: Private ordinary functions

W
with-state-accessors: Private macros
with-temp-rows: Private macros
with-temp-state: Private macros