diff options
| -rw-r--r-- | TODO | 3 | ||||
| -rw-r--r-- | doc/info/libkeccak.texinfo | 236 | ||||
| -rw-r--r-- | doc/man/libkeccak_behex_lower.3 | 2 | ||||
| -rw-r--r-- | doc/man/libkeccak_spec_rawshake.3 | 2 | ||||
| -rw-r--r-- | doc/man/libkeccak_spec_sha3.3 | 4 | ||||
| -rw-r--r-- | doc/man/libkeccak_spec_shake.3 | 2 | ||||
| -rw-r--r-- | doc/man/libkeccak_squeeze.3 | 2 |
7 files changed, 238 insertions, 13 deletions
@@ -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 |