{"id":13409971,"url":"https://github.com/damaki/libkeccak","last_synced_at":"2025-03-14T15:31:42.863Z","repository":{"id":19044529,"uuid":"41259757","full_name":"damaki/libkeccak","owner":"damaki","description":"SHA-3 and other Keccak related algorithms in SPARK/Ada.","archived":false,"fork":false,"pushed_at":"2023-10-19T15:57:47.000Z","size":18758,"stargazers_count":33,"open_issues_count":1,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-06T21:12:52.774Z","etag":null,"topics":["ada","ascon","cshake","gimli","hash-functions","kangarootwelve","keccak","ketje","kmac","marsupilamifourteen","parallelhash","sha-3","shake128","shake256","spark-ada","sponge-construction","tuplehash"],"latest_commit_sha":null,"homepage":"","language":"Ada","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/damaki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-23T17:33:15.000Z","updated_at":"2024-02-13T16:49:12.000Z","dependencies_parsed_at":"2024-05-03T01:52:53.812Z","dependency_job_id":"abfb1f49-c1d7-4dab-83a6-61449e7df0e9","html_url":"https://github.com/damaki/libkeccak","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damaki%2Flibkeccak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damaki%2Flibkeccak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damaki%2Flibkeccak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damaki%2Flibkeccak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/damaki","download_url":"https://codeload.github.com/damaki/libkeccak/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243600642,"owners_count":20317311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ada","ascon","cshake","gimli","hash-functions","kangarootwelve","keccak","ketje","kmac","marsupilamifourteen","parallelhash","sha-3","shake128","shake256","spark-ada","sponge-construction","tuplehash"],"created_at":"2024-07-30T20:01:04.289Z","updated_at":"2025-03-14T15:31:40.161Z","avatar_url":"https://github.com/damaki.png","language":"Ada","funding_links":[],"categories":["Libraries"],"sub_categories":["Cryptography"],"readme":"[![Alire](https://img.shields.io/endpoint?url=https://alire.ada.dev/badges/libkeccak.json)](https://alire.ada.dev/crates/libkeccak.html)\n\n# Libkeccak\n\nThis project implements the Keccak family of sponge functions and related\nconstructions using the SPARK 2014 programming language, with static proof\nof type safety and good performance.\n\nlibkeccak supports the following cryptographic permutations:\n* The Keccak-p permutation for state sizes of 25, 50, 100, 200, 400, 800, and 1600 bits (see [1] and [2]).\n* The Gimli permutation [7]\n* The Ascon permutation [8]\n\nlibkeccak implements the following generic constructions which can\nbe instantiated using the above permutations and with various parameters:\n* The Sponge construction\n* The Duplex construction\n* The MonkeyDuplex construction\n* The MonkeyWrap construction\n* Hash functions based on the Sponge construction\n* eXtendable Output Functions (XOF) based on the Sponge construction\n* cSHAKE, KMAC, TupleHash, and ParallelHash as specified in NIST SP 800-185 [4]\n* KangarooTwelve as specified by the Keccak team [5]\n\nlibkeccak also provides concrete implementations of the above constructions,\nas specified in [1,4,5,6,7]:\n\n* Hash functions:\n  * SHA-3 (224, 256, 384, and 512 bits)\n  * Keccak (224, 256, 384, and 512 bits)\n  * Gimli-Hash\n  * Ascon-Hash\n* XOFs:\n  * SHAKE128 and SHAKE256\n  * RawSHAKE128 and RawSHAKE256\n  * Ascon-XOF\n* cSHAKE:\n  * cSHAKE128 and cSHAKE256\n* KMAC:\n  * KMAC128 and KMAC256\n* TupleHash:\n  * TupleHash128 and TupleHash256\n* Parallel Hashes:\n  * KangarooTwelve\n  * MarsupilamiFourteen (256-bit security variant of KangarooTwelve)\n  * ParallelHash128 and ParallelHash256\n* Authenticated encryption:\n  * Ketje (Jr, Sr, Minor, and Major variants)\n\nNote that the difference between a hash function an a XOF function is that a\nhash function has a fixed output length (for example, 256 bits), whereas the\nXOFs have arbitrary output length.\n\nThe library's algorithms are implemented using Ada's powerful generics. This\nallows for extensive customization and re-use of the various algorithms. The\ngeneric Sponge, XOF, and Hash packages can be instantiated for other permutation\nfunctions (other than just the Keccak permutation). This also permits use of\nthis library based on platforms with hardware accelerated implementations of\nthe Keccak permutation.\n\n# Example\n\nHere's an example of calculating the SHA3-256 hash of a byte array (array of\ntype ``Interfaces.Unsigned_8``):\n\n```Ada\nwith Keccak.Types;\nwith SHA3;\n\nfunction Compute_Hash(Data : in Keccak.Types.Byte_Array)\n   return SHA3.SHA3_256.Digest_Type\nis\n   Ctx    : SHA3.SHA3_256.Context;\n   Digest : SHA3.SHA3_256.Digest_Type;\n\nbegin\n   SHA3.SHA3_256.Init(Ctx);\n   SHA3.SHA3_256.Update(Ctx, Data);\n   SHA3.SHA3_256.Final(Ctx, Digest);\n\n   return Digest;\nend Compute_Hash;\n```\n\n# License\n\nLibkeccak is licensed under the 3-clause BSD license.\n\n# Building\n\nLibkeccak requires a GNAT compiler that supports the `Relaxed_Initialization`\naspect, such as GNAT FSF 11 or newer.\n\nAssuming you've cloned this repository and have Alire installed, libkeccak\ncan be built with the command:\n\n```sh\nalr build\n```\n\nlibkeccak can be built to use SIMD instructions, if your platform supports them,\nby setting the following GPR variables:\n\n| Variable | Values | Default |\n| -------- | ------ | ------- |\n| LIBKECCAK_ARCH | `generic`, `x86_64` | `generic` |\n| LIBKECCAK_SIMD | `none`, `SSE2`, `AVX2` | `none` |\n\n\u003e:warning: `SSE2` and `AVX2` are only available on `x86_64` architectures.\n\nEnabling `SSE2` will use SSE2 instructions to speed up parallel algorithms\nsuch as KangarooTwelve and ParallelHash. Using `LIBKECCAK_SIMD=AVX2` will enable the\nAVX2 instruction set in addition to SSE2.\nTo disable SSE2 and AVX2 on x86_64, set `LIBKECCAK_SIMD=none`.\n\n\u003e:warning: `AVX2` is not guaranteed to work on Windows since GCC does not ensure 32-byte\nstack alignment. See [GCC Bug #54412](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=54412)\n\nExample:\n```sh\nalr build -- -XLIBKECCAK_ARCH=x86_64 -XLIBKECCAK_SIMD=SSE2\n```\n\n# Benchmarks\n\nThe following performance measurements were taken on an AMD Ryzen 7 5800X on Windows 10.\nThe code was compiled using gnat 11.2.0-4 with the following configuration:\n* `LIBKECCAK_ARCH=x86_64`\n* `LIBKECCAK_SIMD=AVX2`\n* All other settings at their default values.\n\nThe measurements shown are the output of the benchmark program.\n\n```\nMessage size: 524288 bytes\nPerforming 200 measurements for each test\n\nGimli: 379 cycles\nGimli Hash: 24.2 cycles/byte\nAscon (12 rounds): 113 cycles\nAscon (8 rounds): 75 cycles\nAscon (6 rounds): 74 cycles\nAscon-Hash: 17.3 cycles/byte\nKangarooTwelve (Absorbing): 1.7 cycles/byte\nKangarooTwelve (Squeezing): 2.9 cycles/byte\nMarsupilamiFourteen (Absorbing): 2.1 cycles/byte\nMarsupilamiFourteen (Squeezing): 3.8 cycles/byte\nParallelHash128 (Absorbing): 2.4 cycles/byte\nParallelHash128 (Squeezing): 4.9 cycles/byte\nParallelHash256 (Absorbing): 2.9 cycles/byte\nParallelHash256 (Squeezing): 6.0 cycles/byte\nSHA3-224: 6.0 cycles/byte\nSHA3-256: 6.3 cycles/byte\nSHA3-384: 8.1 cycles/byte\nSHA3-512: 11.5 cycles/byte\nKeccak-224: 6.0 cycles/byte\nKeccak-256: 6.3 cycles/byte\nKeccak-384: 8.2 cycles/byte\nKeccak-512: 11.5 cycles/byte\nSHAKE128 (Absorbing): 5.2 cycles/byte\nSHAKE128 (Squeezing): 4.9 cycles/byte\nSHAKE256 (Absorbing): 6.3 cycles/byte\nSHAKE256 (Squeezing): 6.0 cycles/byte\nRawSHAKE128 (Absorbing): 5.2 cycles/byte\nRawSHAKE128 (Squeezing): 4.9 cycles/byte\nRawSHAKE256 (Absorbing): 6.3 cycles/byte\nRawSHAKE256 (Squeezing): 6.0 cycles/byte\nDuplex r1152c448: 949 cycles\nDuplex r1088c512: 949 cycles\nDuplex r832c768: 911 cycles\nDuplex r576c1024: 911 cycles\nKeccak-p[1600,24]: 759 cycles\nKeccak-p[1600,24]×2: 1063 cycles\nKeccak-p[1600,24]×4: 1063 cycles\nKeccak-p[1600,24]×8: 2165 cycles\nKeccak-p[1600,12]: 379 cycles\nKeccak-p[1600,12]×2: 531 cycles\nKeccak-p[1600,12]×4: 531 cycles\nKeccak-p[1600,12]×8: 1139 cycles\nKeccak-p[800,22]: 683 cycles\nKeccak-p[400,20]: 683 cycles\nKeccak-p[200,18]: 644 cycles\nKeccak-p[100,16]: 799 cycles\nKeccak-p[50,14]: 759 cycles\nKeccak-p[25,12]: 416 cycles\nKetje Jr (AAD): 38.3 cycles/byte\nKetje Jr (Encrypt): 44.3 cycles/byte\nKetje Jr (Decrypt): 44.3 cycles/byte\nKetje Jr (Tag): 44.1 cycles/byte\nKetje Sr (AAD): 21.7 cycles/byte\nKetje Sr (Encrypt): 26.9 cycles/byte\nKetje Sr (Decrypt): 26.9 cycles/byte\nKetje Sr (Tag): 23.2 cycles/byte\nKetje Minor (AAD): 4.9 cycles/byte\nKetje Minor (Encrypt): 8.3 cycles/byte\nKetje Minor (Decrypt): 8.3 cycles/byte\nKetje Minor (Tag): 6.5 cycles/byte\nKetje Major (AAD): 2.7 cycles/byte\nKetje Major (Encrypt): 4.0 cycles/byte\nKetje Major (Decrypt): 4.0 cycles/byte\nKetje Major (Tag): 3.2 cycles/byte\n```\n\n# Proofs and Testing\n\nLibkeccak takes a \"hybrid verification\" approach by combining proof and testing.\n\nThe library has an auto-active proof of type safety i.e. that the code\nis free of various run-time errors such as:\n * use of uninitialised variables;\n * integer overflows;\n * division by zero;\n * value out-of-range;\n * out-of-bounds array accesses;\n * non-terminating loops.\n\nThis achieves the silver level of assurance (absence of run-time errors)\ndescribed in [9].\n\nAll checks are fully proved, except for a few initialisation checks\nwhich GNATprove's flow analysis cannot automatically verify due to the use of\nloops to perform the initialisation.\nThese checks are manually reviewed and suppressed using `pragma Annotate`.\nIt is planned to replace these instances with `Relaxed_Initialization` in the\nfuture to achieve a fully automatic proof.\n\nThe proofs do not extend to functional correctness, i.e. the proofs do not\nshow that the SHA-3 implementation produces the correct results.\nConventional testing is used to provide assurance of the correctness of the\nalgorithms. The tests consist of Known Answer Tests (KAT) and unit tests.\n\nThe KATs comprise the bulk of the tests and provide the assurance that the\nalgorithms are implemented correctly.\n\nThe unit tests aim to cover the cases that are not covered by the KATs, such\nas boundary conditions and testing multi-part hashing operations in various\ncombinations of lengths.\n\n## Reproducing the results\n\nAssuming you have Alire \u003e= 1.2.0 installed, then:\n\n### Proofs\n\n```sh\ncd prove\nalr exec -- gnatprove -P../libkeccak -XLIBKECCAK_ARCH=generic -XLIBKECCAK_SIMD=none\n```\n\n\u003e:bulb: Change `-XLIBKECCAK_ARCH` and `-XLIBKECCAK_SIMD` to run the proofs using\ndifferent SIMD instruction sets.\n\nA summary of the proof results is stored in `obj/\u003carch\u003e_\u003csimd\u003e/gnatprove.out`.\n\nThe project file configures the prover limits so that they should give the same\nresults on all machines.\n\nTo see only failed proofs, pass `--report=fail` to gnatprove.\n\n### Tests\n\nTo run the Known Answer Tests using test vectors:\n\n```sh\ncd tests/kat\nalr build -- -XLIBKECCAK_ARCH=generic -XLIBKECCAK_SIMD=none\n./run-all-tests.sh\n```\n\nThe test vectors are located in the `tests/kat/testvectors/` directory.\n\nTo run the unit tests:\n```sh\ncd tests/unit_tests\nalr build -- -XLIBKECCAK_ARCH=generic -XLIBKECCAK_SIMD=none\nalr run\n```\n\n\u003e:bulb: Change `-XLIBKECCAK_ARCH` and `-XLIBKECCAK_SIMD` to run the tests using\ndifferent SIMD instruction sets.\n\n# References\n\n* [1] NIST FIPS PUB 202 - SHA-3 Standard: Permutation-Based Hash and Extendable\noutput Functions. August 2015 http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf\n* [2] The Keccak Reference Version 3.0. January 2011\nhttp://keccak.noekeon.org/Keccak-reference-3.0.pdf\n* [3] Cryptographic Sponge Functions Version 0.1. January 2011\nhttp://sponge.noekeon.org/CSF-0.1.pdf\n* [4] NIST SP 800-185 - SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash. December 2016\nhttp://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf\n* [5] KangarooTwelve: fast hashing based on Keccak-p\nhttp://keccak.noekeon.org/kangarootwelve.html\n* [6] CAESAR submission: Ketje v2\nhttps://keccak.team/files/Ketjev2-doc2.0.pdf\n* [7] Gimli: a cross-platform permutation\nhttps://gimli.cr.yp.to/index.html\n* [8] Ascon\nhttps://ascon.iaik.tugraz.at/index.html\n* [9] Implementation Guidance for the Adoption of SPARK\nhttps://www.adacore.com/books/implementation-guidance-spark","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamaki%2Flibkeccak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdamaki%2Flibkeccak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamaki%2Flibkeccak/lists"}