odin-lang.Odin/core/crypto/README.md

crypto

A crypto library for the Odin language

Supported

This library offers various algorithms available in either native Odin or via bindings to the Botan crypto library. Please see the chart below for the options.
Note: All crypto hash algorithms, offered by Botan\'s FFI, have been added.

Hashing algorithms

Algorithm	Odin	Botan
BLAKE	✔️
BLAKE2B	✔️	✔️
BLAKE2S	✔️
GOST	✔️	✔️
Grøstl	✔️
HAVAL	✔️
JH	✔️
Keccak	✔️	✔️
MD2	✔️
MD4	✔️	✔️
MD5	✔️	✔️
RIPEMD	✔️	✔️*
SHA-1	✔️	✔️
SHA-2	✔️	✔️
SHA-3	✔️	✔️
SHAKE	✔️	✔️
Skein		✔️**
SM3	✔️	✔️
Streebog	✔️	✔️
Tiger	✔️	✔️
Tiger2	✔️
Whirlpool	✔️	✔️

* Only RIPEMD-160
** Only SKEIN-512

High level API

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.
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(...).

Low level API

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

package crypto_example

// Import the desired package
import "core:crypto/md4"

main :: proc() {
    input := "foo"
    // Compute the hash via Odin implementation
    computed_hash := md4.hash(input)
    // Switch to Botan
    md4.use_botan()
    // Compute the hash via Botan bindings
    computed_hash_botan := md4.hash(input)
}

For example uses of all available algorithms, please see the tests within tests/core/crypto.

Thread safety

The crypto package is not thread-safe at the moment. This may change in the future.

Disclaimer

The algorithms were ported out of curiosity and due to interest in the field. We have not had any of the code verified by a third party or tested/fuzzed by any automatic means. Whereever we were able to find official test vectors, those were used to verify the implementation. We do not recommend using them in a production environment, without any additional testing and/or verification.

ToDo

• Ciphers (Symmetric, Asymmetric)
• MACs (Message Authentication Code)
• CSPRNGs (Cryptographically Secure PseudoRandom Number Generator)
• KDFs (Key Derivation Function)
• KEAs (Key Exchange Algorithm)

License

This library is made available under the BSD-3 license.