diff options
| author | zhibog <zhibog-github@web.de> | 2021-11-09 16:50:13 +0100 |
|---|---|---|
| committer | zhibog <zhibog-github@web.de> | 2021-11-09 16:50:13 +0100 |
| commit | c24454ae70759b77cd6ed8b3f313eb32bc19ab21 (patch) | |
| tree | 92c47e40c054775ed9b753f984700b2f32ed3809 /core/crypto/README.md | |
| parent | eb96f9677ece3c817e755f9f7f24ce0605c06274 (diff) | |
Removed context switching system from the crypto library to simplify the code
Diffstat (limited to 'core/crypto/README.md')
| -rw-r--r-- | core/crypto/README.md | 78 |
1 files changed, 35 insertions, 43 deletions
diff --git a/core/crypto/README.md b/core/crypto/README.md index c21fba44b..5955f9c56 100644 --- a/core/crypto/README.md +++ b/core/crypto/README.md @@ -2,48 +2,43 @@ A crypto library for the Odin language ## Supported -This library offers various algorithms available in either native Odin or via bindings to the [Botan](https://botan.randombit.net/) crypto library. +This library offers various algorithms implemented in Odin. Please see the chart below for the options. -**Note:** All crypto hash algorithms, offered by [Botan\'s FFI](https://botan.randombit.net/handbook/api_ref/hash.html), have been added. ## Hashing algorithms -| Algorithm | Odin | Botan | -|:-------------------------------------------------------------------------------------------------------------|:-----------------|:---------------------| -| [BLAKE](https://web.archive.org/web/20190915215948/https://131002.net/blake) | ✔️ | | -| [BLAKE2B](https://datatracker.ietf.org/doc/html/rfc7693) | ✔️ | ✔️ | -| [BLAKE2S](https://datatracker.ietf.org/doc/html/rfc7693) | ✔️ | | -| [GOST](https://datatracker.ietf.org/doc/html/rfc5831) | ✔️ | ✔️ | -| [Grøstl](http://www.groestl.info/Groestl.zip) | ✔️ | | -| [HAVAL](https://web.archive.org/web/20150111210116/http://labs.calyptix.com/haval.php) | ✔️ | | -| [JH](https://www3.ntu.edu.sg/home/wuhj/research/jh/index.html) | ✔️ | | -| [Keccak](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | ✔️ | ✔️ | -| [MD2](https://datatracker.ietf.org/doc/html/rfc1319) | ✔️ | | -| [MD4](https://datatracker.ietf.org/doc/html/rfc1320) | ✔️ | ✔️ | -| [MD5](https://datatracker.ietf.org/doc/html/rfc1321) | ✔️ | ✔️ | -| [RIPEMD](https://homes.esat.kuleuven.be/~bosselae/ripemd160.html) | ✔️ | ✔️\* | -| [SHA-1](https://datatracker.ietf.org/doc/html/rfc3174) | ✔️ | ✔️ | -| [SHA-2](https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf) | ✔️ | ✔️ | -| [SHA-3](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | ✔️ | ✔️ | -| [SHAKE](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | ✔️ | ✔️ | -| [Skein](https://www.schneier.com/academic/skein/) | | ✔️\*\* | -| [SM3](https://datatracker.ietf.org/doc/html/draft-sca-cfrg-sm3-02) | ✔️ | ✔️ | -| [Streebog](https://datatracker.ietf.org/doc/html/rfc6986) | ✔️ | ✔️ | -| [Tiger](https://www.cs.technion.ac.il/~biham/Reports/Tiger/) | ✔️ | ✔️ | -| [Tiger2](https://www.cs.technion.ac.il/~biham/Reports/Tiger/) | ✔️ | | -| [Whirlpool](https://web.archive.org/web/20171129084214/http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html) | ✔️ | ✔️ | - -\* Only `RIPEMD-160` -\*\* Only `SKEIN-512` +| Algorithm | | +|:-------------------------------------------------------------------------------------------------------------|:-----------------| +| [BLAKE](https://web.archive.org/web/20190915215948/https://131002.net/blake) | ✔️ | +| [BLAKE2B](https://datatracker.ietf.org/doc/html/rfc7693) | ✔️ | +| [BLAKE2S](https://datatracker.ietf.org/doc/html/rfc7693) | ✔️ | +| [GOST](https://datatracker.ietf.org/doc/html/rfc5831) | ✔️ | +| [Grøstl](http://www.groestl.info/Groestl.zip) | ✔️ | +| [HAVAL](https://web.archive.org/web/20150111210116/http://labs.calyptix.com/haval.php) | ✔️ | +| [JH](https://www3.ntu.edu.sg/home/wuhj/research/jh/index.html) | ✔️ | +| [Keccak](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | ✔️ | +| [MD2](https://datatracker.ietf.org/doc/html/rfc1319) | ✔️ | +| [MD4](https://datatracker.ietf.org/doc/html/rfc1320) | ✔️ | +| [MD5](https://datatracker.ietf.org/doc/html/rfc1321) | ✔️ | +| [RIPEMD](https://homes.esat.kuleuven.be/~bosselae/ripemd160.html) | ✔️ | +| [SHA-1](https://datatracker.ietf.org/doc/html/rfc3174) | ✔️ | +| [SHA-2](https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf) | ✔️ | +| [SHA-3](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | ✔️ | +| [SHAKE](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | ✔️ | +| [SM3](https://datatracker.ietf.org/doc/html/draft-sca-cfrg-sm3-02) | ✔️ | +| [Streebog](https://datatracker.ietf.org/doc/html/rfc6986) | ✔️ | +| [Tiger](https://www.cs.technion.ac.il/~biham/Reports/Tiger/) | ✔️ | +| [Tiger2](https://www.cs.technion.ac.il/~biham/Reports/Tiger/) | ✔️ | +| [Whirlpool](https://web.archive.org/web/20171129084214/http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html) | ✔️ | #### High level API -Each hash algorithm contains a procedure group named `hash`, or if the algorithm provides more than one digest size `hash_<size>`\*\*\*. +Each hash algorithm contains a procedure group named `hash`, or if the algorithm provides more than one digest size `hash_<size>`\*. Included in these groups are four procedures. * `hash_string` - Hash a given string and return the computed hash. Just calls `hash_bytes` internally * `hash_bytes` - Hash a given byte slice and return the computed hash * `hash_stream` - Takes a stream from io.Stream and returns the computed hash from it * `hash_file` - Takes a file handle and returns the computed hash from it. A second optional boolean parameter controls if the file is streamed (this is the default) or read at once (set to true) -\*\*\* On some algorithms there is another part to the name, since they might offer control about additional parameters. +\* On some algorithms there is another part to the name, since they might offer control about additional parameters. For instance, `HAVAL` offers different sizes as well as three different round amounts. Computing a 256-bit hash with 3 rounds is therefore achieved by calling `haval.hash_256_3(...)`. @@ -51,13 +46,6 @@ Computing a 256-bit hash with 3 rounds is therefore achieved by calling `haval.h The above mentioned procedures internally call three procedures: `init`, `update` and `final`. You may also directly call them, if you wish. -#### Context system -The library uses a context system internally to be able to switch between Odin / Botan implementations freely. -When an Odin implementation is available, it is the default. -You may change what is used during runtime by calling `foo.use_botan()` or `foo.use_odin()`. -It is also possible to set this during compile time via `USE_BOTAN_LIB=true`. -Internally a vtable is used to set the appropriate procedures when switching. This works for all the procedures mentioned in the APIs above. - #### Example ```odin package crypto_example @@ -67,12 +55,16 @@ import "core:crypto/md4" main :: proc() { input := "foo" - // Compute the hash via Odin implementation + + // Compute the hash, using the high level API computed_hash := md4.hash(input) - // Switch to Botan - md4.use_botan() - // Compute the hash via Botan bindings - computed_hash_botan := md4.hash(input) + + // Compute the hash, using the low level API + ctx: md4.Md4_Context + computed_hash_low: [16]byte + md4.init(&ctx) + md4.update(&ctx, transmute([]byte)input) + md4.final(&ctx, computed_hash_low[:]) } ``` For example uses of all available algorithms, please see the tests within `tests/core/crypto`. |