aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2023-10-14 23:53:33 -0400
committerPaul Duncan <pabs@pablotron.org>2023-10-14 23:53:33 -0400
commitf3eb62a8bc993b6f3fa12123a284a7d2c0aae719 (patch)
tree33764b60da9b46453b50f57c0f936c571e6811bd
parentbbf3cfd0ca41ea63269fadac2cdd5bbe2445e53a (diff)
downloadsha3-f3eb62a8bc993b6f3fa12123a284a7d2c0aae719.tar.bz2
sha3-f3eb62a8bc993b6f3fa12123a284a7d2c0aae719.zip
README.md: improve introduction, minor fixes to algo list, add "Documentation" section, document "doc" targetv0.4
-rw-r--r--README.md61
1 files changed, 38 insertions, 23 deletions
diff --git a/README.md b/README.md
index c10dbf5..10f5a12 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,13 @@
# sha3
-[C11][] implementation of the [SHA-3][] [cryptographic hash
-functions][hash], [eXtendable Output Functions (XOF)][xof], and
-[Hash-based Message Authentication Code functions (HMAC)][hmac] defined
-in [FIPS 202][], [SP 800-185][800-185], and the [draft KangarooTwelve
-and TurboSHAKE specification][turboshake-ietf].
-
-Includes [AVX-512][] acceleration and a full test suite with test
+Embeddable, dependency-free [C11][] implementation of the [SHA-3][]
+[cryptographic hash functions][hash], [eXtendable Output Functions
+(XOF)][xof], and [Hash-based Message Authentication Code functions
+(HMAC)][hmac] defined in [FIPS 202][], [SP 800-185][800-185], and the
+[draft KangarooTwelve and TurboSHAKE specification][turboshake-ietf].
+
+Includes [AVX-512][] acceleration, [Doxygen][]-friendly [API][]
+documentation, and a full test suite with sanitizers enabled and test
vectors from the [NIST CSRC "Examples With Intermediate Values"
site][csrc-examples] and the [Test Vectors section of the draft
KangarooTwelve and TurboSHAKE specification][turboshake-ietf-test-vectors].
@@ -14,34 +15,36 @@ KangarooTwelve and TurboSHAKE specification][turboshake-ietf-test-vectors].
The following algorithms are implemented:
* SHA3-224, SHA3-256, SHA3-384, and SHA3-512: [SHA-3][] [cryptographic
- hash functions][hash] with fixed-length output defined in section 6.1
- of [FIPS 202][].
+ hash functions][hash] with fixed-length output, as defined in section
+ 6.1 of [FIPS 202][].
* HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512:
[HMAC][hmac] instantiated with [SHA-3][] hash functions, as specified
- in [RFC 2104][] and [FIPS 198-1][].
+ in section 7 of [FIPS 202][], [RFC 2104][], and [FIPS 198-1][].
* SHAKE128, SHAKE128-XOF, SHAKE256, and SHAKE256-XOF: [SHA-3][]
- [XOFs][xof] defined in section 6.2 of [FIPS 202][].
+ [XOFs][xof] with both fixed-length output and arbitrary-length output,
+ as defined in section 6.2 of [FIPS 202][].
* cSHAKE128, cSHAKE128-XOF, cSHAKE256, and cSHAKE256-XOF: Fixed-length
- and [XOF][] variants of the customizable-SHAKE primitive defined in
- section 3 of [SP 800-185][800-185].
+ and [XOF][] variants of the customizable-SHAKE primitive, as defined
+ in section 3 of [SP 800-185][800-185].
* KMAC128, KMAC128-XOF, KMAC256 and KMAC256-XOF: Keccak [Message
- Authentication Code (MAC)][mac] defined in section 4 of [SP
+ Authentication Code (MAC)][mac], as defined in section 4 of [SP
800-185][800-185].
* TupleHash128, TupleHash128-XOF, TupleHash256, and TupleHash256-XOF:
Misuse-resistant hash function and [XOF][] for hashing a [tuple][] of
- byte strings, defined in section 5 of [SP 800-185][800-185].
+ byte strings, as defined in section 5 of [SP 800-185][800-185].
* ParallelHash128, ParallelHash128-XOF, ParallelHash256, and
- ParallelHash256-XOF: Hash function and [XOF][] defined in section 6
- of [SP 800-185][800-185].
-* TurboSHAKE128 and TurboSHAKE256: Faster, reduced-round [XOFs][xof]
- defined in the [draft KangarooTwelve and TurboSHAKE
+ ParallelHash256-XOF: Hash function and [XOF][], as defined in section
+ 6 of [SP 800-185][800-185].
+* TurboSHAKE128 and TurboSHAKE256: Faster, reduced-round [XOFs][xof],
+ as defined in the [draft KangarooTwelve and TurboSHAKE
specification][turboshake-ietf].
-* KangarooTwelve: Faster, reduced-round [XOF][] with customzation string
- defined in the [draft KangarooTwelve and TurboSHAKE
+* KangarooTwelve: Faster, reduced-round [XOF][] with a customzation
+ string, as defined in the [draft KangarooTwelve and TurboSHAKE
specification][turboshake-ietf].
-Use `make` to build a minimal sample application, and `make test` to run
-the test suite.
+Use `make` to build a shared library and minimal sample application,
+`make doc` to generate [HTML][]-formatted [API][] documentation, and
+`make test` to run the test suite.
## Examples
@@ -165,6 +168,12 @@ int main() {
See the `examples/` directory for more examples.
+## Documentation
+
+Full [API][] documentation is available in the comments of `sha3.h`. If
+you have [Doxygen][] installed, you can generate [HTML][]-formatted
+[API][] documentation by typeing `make doc`.
+
## References
* [FIPS 202 - SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions][FIPS 202]
@@ -208,3 +217,9 @@ See the `examples/` directory for more examples.
"KangarooTwelve and TurboSHAKE test vectors"
[avx-512]: https://en.wikipedia.org/wiki/AVX-512
"Advanced Vector Extensions 512 (AVX-512): 512-bit SIMD vector instruction set"
+[doxygen]: https://en.wikipedia.org/wiki/Doxygen
+ "API documentation generator."
+[api]: https://en.wikipedia.org/wiki/API
+ "Application Programming Interface (API)"
+[html]: https://en.wikipedia.org/wiki/HTML
+ "HyperText Markup Language (HTML)"