aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--TODO3
-rw-r--r--doc/info/libkeccak.texinfo236
-rw-r--r--doc/man/libkeccak_behex_lower.32
-rw-r--r--doc/man/libkeccak_spec_rawshake.32
-rw-r--r--doc/man/libkeccak_spec_sha3.34
-rw-r--r--doc/man/libkeccak_spec_shake.32
-rw-r--r--doc/man/libkeccak_squeeze.32
7 files changed, 238 insertions, 13 deletions
diff --git a/TODO b/TODO
index 59e86b7..fa32b26 100644
--- a/TODO
+++ b/TODO
@@ -9,6 +9,3 @@ Just for fun:
Test parallelisation and acceleration.
Measure cycles per byte.
-
-Fix todos in the texinfo file.
-
diff --git a/doc/info/libkeccak.texinfo b/doc/info/libkeccak.texinfo
index 089f06f..3ac6a53 100644
--- a/doc/info/libkeccak.texinfo
+++ b/doc/info/libkeccak.texinfo
@@ -4,7 +4,7 @@
@include macros.texinfo
@copying
@c --------------------------------------------------------------------------------
-Copyright @copyright{} 2015 @w{Mattias Andrée @e{maandree@@kth.se}}
+Copyright @copyright{} 2015, 2017 @w{Mattias Andrée @e{maandree@@kth.se}}
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -75,6 +75,7 @@ with support for bit-oriented data.
* Hexadecimal hashes:: Converting between binary and hexadecimal.
* Hashing files:: Functions used to hash entire files.
* Message authentication:: Functions used for message authentication codes.
+* Examples:: Examples of how to use libkeccak.
* GNU Affero General Public License:: Copying and sharing libkeccak.
* GNU Free Documentation License:: Copying and sharing this manual.
@@ -844,6 +845,236 @@ sponge, and the second argument must not be @code{NULL}.
+@node Examples
+@chapter Examples
+@cpindex Example
+
+@cartouche
+@cpindex Configure state
+@tpindex libkeccak_spec_t
+@tpindex libkeccak_generalised_spec_t
+@fnindex libkeccak_generalised_spec_initialise
+@fnindex libkeccak_degeneralise_spec
+@fnindex libkeccak_spec_check
+This examples configure a @code{libkeccak_spec_t} to specify settings for Keccak[c = 512].
+@example
+int r;
+libkeccak_spec_t spec;
+libkeccak_generalised_spec_t gspec;
+libkeccak_generalised_spec_initialise(&gspec);
+gspec.capacity = 512;
+if ((r = libkeccak_degeneralise_spec(&gspec, &spec)))
+ goto fail_degeneralise_spec;
+if ((r = libkeccak_spec_check(&spec)));
+ goto fail_spec_check;
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Calculate hash
+@cpindex Hash, calculate
+@cpindex Configure state
+@cpindex Hexadecimal hash
+@tpindex libkeccak_state_t
+@tpindex libkeccak_spec_t
+@fnindex libkeccak_state_initialise
+@fnindex libkeccak_update
+@fnindex libkeccak_digest
+@fnindex libkeccak_behex_lower
+@fnindex libkeccak_state_destroy
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in
+hexadecimal form, to stdout.
+@example
+libkeccak_state_t state;
+libkeccak_spec_t spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+char chunk[4 << 10];
+ssize_t len;
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+if (libkeccak_state_initialise(&state, &spec) < 0)
+ goto fail;
+
+for (;;) @{
+ len = read(STDIN_FILENO, chunk, sizeof(chunk));
+
+ if ((len < 0) && (errno == EINTR))
+ continue;
+ if (len < 0)
+ goto fail;
+ if (len == 0)
+ break;
+
+ if (libkeccak_update(&state, chunk, (size_t)len) < 0)
+ goto fail;
+@}
+if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0)
+ goto fail;
+
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf("%s\n", hexhash);
+libkeccak_state_destroy(&state);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Configure state, RawSHAKE
+@cpindex RawSHAKE, configure state
+@tpindex libkeccak_spec_t
+@fnindex libkeccak_spec_rawshake
+This example configure a @code{libkeccak_spec_t} to specify
+the Keccak parameters used for RawSHAKE256(, 512).
+@example
+libkeccak_spec_t spec;
+libkeccak_spec_rawshake(&spec, 256, 512);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Configure state, SHA-3
+@cpindex SHA-3, configure state
+@tpindex libkeccak_spec_t
+@fnindex libkeccak_spec_sha3
+This example configure a @code{libkeccak_spec_t} to specify
+the Keccak parameters used for SHA3-256.
+@example
+libkeccak_spec_t spec;
+libkeccak_spec_sha3(&spec, 256);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Configure state, SHAKE
+@cpindex SHAKE, configure state
+@tpindex libkeccak_spec_t
+@fnindex libkeccak_spec_shake
+This example configure a @code{libkeccak_spec_t} to specify
+the Keccak parameters used for SHAKE256(, 512).
+@example
+libkeccak_spec_t spec;
+libkeccak_spec_shake(&spec, 256, 512);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Calculate hash, SHA-3, from file
+@cpindex Hash, calculate, SHA-3, from file
+@cpindex SHA-3, calculate hash, from file
+@cpindex File, calculate hash, SHA-3
+@fnindex libkeccak_sha3sum_fd
+This example calculates the SHA3-256 hash of the input from
+stdin, and prints the hash, in hexadecimal form, to stdout.
+@example
+libkeccak_state_t state;
+if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0)
+ goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf("%s\n", hexhash);
+libkeccak_state_destroy(&state);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Calculate hash, RawSHAKE, from file
+@cpindex Hash, calculate, RawSHAKE, from file
+@cpindex RawSHAKE, calculate hash, from file
+@cpindex File, calculate hash, RawSHAKE
+@fnindex libkeccak_rawshakesum_fd
+This example calculates the RawSHAKE256(, 512) hash of the input
+from stdin, and prints the hash, in hexadecimal form, to stdout.
+@example
+libkeccak_state_t state;
+if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0)
+ goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf("%s\n", hexhash);
+libkeccak_state_destroy(&state);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Calculate hash, SHAKE, from file
+@cpindex Hash, calculate, SHAKE, from file
+@cpindex SHAKE, calculate hash, from file
+@cpindex File, calculate hash, SHAKE
+@fnindex libkeccak_shakesum_fd
+This example calculates the SHAKE256(, 512) hash of the input
+from stdin, and prints the hash, in hexadecimal form, to stdout.
+@example
+libkeccak_state_t state;
+if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0)
+ goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf("%s\n", hexhash);
+libkeccak_state_destroy(&state);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Calculate hash, Keccak, from file
+@cpindex Hash, calculate, Keccak, from file
+@cpindex Keccak, calculate hash, from file
+@cpindex File, calculate hash, Keccak
+@tpindex libkeccak_spec_t
+@fnindex libkeccak_keccaksum_fd
+@fnindex libkeccak_behex_lower
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+@example
+libkeccak_state_t state;
+libkeccak_spec_t spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+
+if (libkeccak_keccaksum_fd(STDIN_FILENO, &state, &spec, binhash) < 0)
+ goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf("%s\n", hexhash);
+libkeccak_state_destroy(&state);
+@end example
+@end cartouche
+
+@cartouche
+@cpindex Calculate hash, from file
+@cpindex Hash, calculate, from file
+@cpindex Calculate hash, from file
+@cpindex File, calculate hash
+@tpindex libkeccak_spec_t
+@fnindex libkeccak_generalised_sum_fd
+@fnindex libkeccak_behex_lower
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+@example
+libkeccak_state_t state;
+libkeccak_spec_t spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+
+if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state,
+ &spec, NULL, binhash) < 0)
+ goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf("%s\n", hexhash);
+libkeccak_state_destroy(&state);
+@end example
+@end cartouche
+
+
+
@node GNU Affero General Public License
@appendix GNU Affero General Public License
@include agpl-3.0.texinfo
@@ -866,6 +1097,3 @@ sponge, and the second argument must not be @code{NULL}.
@bye
-
-TODO examples
-
diff --git a/doc/man/libkeccak_behex_lower.3 b/doc/man/libkeccak_behex_lower.3
index 6c06af9..85bc843 100644
--- a/doc/man/libkeccak_behex_lower.3
+++ b/doc/man/libkeccak_behex_lower.3
@@ -27,7 +27,7 @@ hexadecimal representation in
will be terminated by a NUL-character.
.PP
The
-.I In
+.I n
parameter specifies the number of bytes
the binary hashsum is comprised.
.I output
diff --git a/doc/man/libkeccak_spec_rawshake.3 b/doc/man/libkeccak_spec_rawshake.3
index a7c7fce..6f60c36 100644
--- a/doc/man/libkeccak_spec_rawshake.3
+++ b/doc/man/libkeccak_spec_rawshake.3
@@ -33,7 +33,7 @@ The
.BR libkeccak_spec_rawshake ()
function cannot fail.
.SH EXAMPLE
-This examples configure a
+This example configure a
.B libkeccak_spec_t
to specify the Keccak parameters used for RawSHAKE256(, 512):
.LP
diff --git a/doc/man/libkeccak_spec_sha3.3 b/doc/man/libkeccak_spec_sha3.3
index 7978e6e..8e07a7d 100644
--- a/doc/man/libkeccak_spec_sha3.3
+++ b/doc/man/libkeccak_spec_sha3.3
@@ -31,8 +31,8 @@ The
.BR libkeccak_spec_sha3 ()
function cannot fail.
.SH EXAMPLE
-This examples configure a
-.B Blibkeccak_spec_t
+This example configure a
+.B libkeccak_spec_t
to specify the Keccak parameters used for SHA3-256:
.LP
.nf
diff --git a/doc/man/libkeccak_spec_shake.3 b/doc/man/libkeccak_spec_shake.3
index 692897f..9e2d763 100644
--- a/doc/man/libkeccak_spec_shake.3
+++ b/doc/man/libkeccak_spec_shake.3
@@ -32,7 +32,7 @@ The
.BR libkeccak_spec_shake ()
function cannot fail.
.SH EXAMPLE
-This examples configure a
+This example configure a
.B libkeccak_spec_t
to specify the Keccak parameters used for SHAKE256(, 512):
.LP
diff --git a/doc/man/libkeccak_squeeze.3 b/doc/man/libkeccak_squeeze.3
index eafbc65..c6c8d01 100644
--- a/doc/man/libkeccak_squeeze.3
+++ b/doc/man/libkeccak_squeeze.3
@@ -27,7 +27,7 @@ has the same requirement as for the
and
.BR libkeccak_fast_digest (3)
functions: it must have an allocation size of at least
-.RI (( Istate->n
+.RI (( state->n
+ 7) / 8) bytes. However, it may not be
.IR NULL .
.SH RETURN VALUES