The dynamic library is built with ~Cargo~ and ~Rust~, and the cli example program is built with ~gcc~.
*** Build and install
The default build configuration builds both the dynamic library and the cli example program, and copies them to =/usr/lib/libkhash.so= and =/usr/bin/kana-hash= respectively.
#+BEGIN_SRC shell
$ make && sudo make install
#+END_SRC
The install path can be changed by editing the ~INSTALL~ and ~INSTALL-BIN~ paths in the [[file:./Makefile][Makefile]].
*** Uninstall
To remove installed binaries, run:
#+BEGIN_SRC shell
$ sudo make uninstall
#+END_SRC
*** Other build configurations
The Makefile contains some other build directives.
**** Native code optimisations
By default =libkhash= builds the shared library with native architecture optimisations enabled.
If you are intending to move the binary to another architecture, this might not be desireable.
To build without such optimisations, run:
#+BEGIN_SRC shell
$ make khash-nonative
#+END_SRC
**** Tests
To build and run all tests, run:
#+BEGIN_SRC shell
$ make test
#+END_SRC
**** Building the CLI
The default =make= directive builds both the library and the CLI example program.
| ~khash_salt~ | | A salt allocated into a context by ~khash_new_context()~ and released by ~khash_free_context()~. You shouldn't mess with its field directly. |
| | /salt_type/ | The type of the salt. |
| | /size/ | The size of the salt. |
| | /body/ | A pointer to the body of the salt. (The memory allocated here is not guaranteed to be of the provided /size/.) |
| ~khash_new_context~ | /algo/, /salt_type/, /data/, /size/, /output/ | Creates a new context for use with other =libkhash= functions. /algo/ is expected to be one of the =KHASH_ALGO_= macros listed [[Macros][above.]] Likewise /salt_type/ is expected to be one of the =KHASH_SALT_TYPE_= macros. /data/ can be ~NULL~ unless /salt_type/ is set to ~KHASH_SALT_TYPE_SPECIFIC~, in which exactly /size/ bytes are read from /data/. /output/ is expected to be a valid pointer to a currently unused `khash_context` structure. |
| ~khash_free_context~ | /ctx/ | Free a context allocated with ~khash_new_context()~. /ctx/ is expected to be a valid pointer to a currently allocated context. |
| ~khash_clone_context~ | /src/, /dst/ | Clone a context allocated with ~khash_new_context()~ into another. The newly allocated /dst/ must be properly released (with ~khash_free_context()~ or ~khash_do()~) as well as the source. /src/ is expected to be a valid pointer to an allocated context, and /dst/ is expected to be a valid pointer to an unallocated context. |
| ~khash_length~ | /ctx/, /data/, /size/, /length/ | Compute the length required to hold the output string for ~khash_do()~ for a given input. Will read exactly /size/ bytes from /data/ and compute the value into what is pointed to by /length/ (which is expected to be a valid pointer to a type of ~size_t~.) The resulting length does not include a =NUL= terminator for the string. |
| ~khash_do~ | /ctx/, /data/, /size/, /output/, /output_size/ | Compute the kana-hash of /size/ bytes from /data/ and store no more than /output_size/ of the the result into the string pointed to by /output/. Each pointer is expected to be valid. This function frees the supplied /ctx/ after the hash has been computed, and thus /ctx/ is no longer valid afterwards. |
| ~Salt.Random~ | Salt | A cryptographically secure random salt |
| ~Salt.Default~ | Salt | The library's default static salt |
** Notes
The strings generated by this library are meant to be pretty, not secure. It is not a secure way of representing a hash as many collisions are possible.