| ~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. |
| ~khash_max_length~ | /algo/, /input_len/, /output_len/ | Calculate the max possible size for the given algorithm (expected to be one of the =KHASH_ALGO_= macros) and input length, and store this result in /output_len/ (expected to be a valid non-~NULL~ pointer.) /input_len/ is not required unless the algorithm is dynamically sized (all currently implemented ones are not.) |
** Node FFI bindings
NPM package in [[file:./node/index.js][./node]]
@ -157,31 +158,31 @@
**** Create a context
Create the context by specifying an algorithm identifier, and an optional salt.
If provided, the salt must be of type `Salt`.
If provided, the salt must be of type ~Salt~.
#+BEGIN_SRC javascript
const ctx = new hash.Kana(hash.Kana.ALGO_DEFAULT, new hash.Salt("optional salt~"));
#+END_SRC
**** Create a hash
The `once()` function consumes the context and outputs a hash string.
The ~once()~ function consumes the context and outputs a hash string.
#+BEGIN_SRC javascript
const output = ctx.once("input string");
#+END_SRC
***** Creating a hash without consuming
If you want to reuse the context, use the `hash()` function.
If you want to reuse the context, use the ~hash()~ function.
#+BEGIN_SRC javascript
const output = ctx.hash("input string");
#+END_SRC
***** Freeing the context
The context must be release after use if you have not called `once()`.
The context must be release after use if you have not called ~once()~.
#+BEGIN_SRC javascript
ctx.finish();
#+END_SRC
***** Cloning an existing context
The new context must also be freed with either `once()` or `finish()`.
The new context must also be freed with either ~once()~ or ~finish()~.
#+BEGIN_SRC javascript
const new_ctx = ctx.clone();
#+END_SRC
@ -209,7 +210,26 @@
** 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.
*** TODO Digest algorithm
*** Digest algorithm
The kana algorithm is a 16-bit block digest that works as follows:
- The most and least significant 8 bits are each seperated into /Stage 0/ and /Stage 1/ each operating on the first and second byte respectively.
- Stage 0:
1. The byte is sign tested (bitwise ~AND~=0x80=), store this as a boolean in /sign0/.
2. The valid first character range is looked up using the result of the sign test (either 0 or 1), store the range in /range/, and the slice ~KANA~ taken from the range in /kana/.
3. The first index is calculated as the unsigned first byte modulo the size (exclusive) of /range/. Store this as /index0/.
4. The swap table is checked to see if /index0/ has an entry. Then each following step is checked in order:
+ If the swap entry exists and the first byte bitwise ~AND~=0x2= is not 0, set the first character of the output to the value found in the swap table.
+ If the swap entry exists and the first byte bitwise ~AND~=0x8= is not 0 and the index has an entry in the 2nd swap table, set the first character of the output to the value found in the 2nd swap table.
+ In any other case, set the first character of the output to the value found in the /kana/ slice at the /index/.
- Stage 1:
1. Compute a sub table for /index/ plus the start of /range/ using the ranges defined in ~KANA_SUB_VALID_FOR~ and store it in /sub/. If there is no sub table possible, skip to step 3.
2. If there is an entry in /sub/ for the index of the 2nd byte modulo the size of ~KANA_SUB~, set the second output character to be that character.
3. If there was no value set from the sub table, the 2nd output character becomes the first output character from inputting the 2nd byte back through /Stage 0/ as the first byte.
- Concatenate both characters and move to the next 16-bit block.
Notes:
- It is valid for a single iterator to produce between 0 and 2 characters but no more.
- If an input given to the algorithm that cannot be divided exactly into 16-bit blocks (i.e. one byte is left over), a padding byte of 0 is added as the 2nd byte to make it fit.
For more information see [[file:./src/mnemonic.rs][mnemonic.rs]].
/// Find the maximum possible digest output size for the given algorithm and input length, and set that to `digest_length`. If the algorithm's output is not dynamically sized `input_length` does not need to be provided.
/// Create a new context with the specified algorithm (one of the `KHASH_ALGO_*` macro constants), salt type (one of the `KHASH_SALT_TYPE_*` constants), optional salt `data` and salt length `size`, and output pointer `output`.
/// `data` may be `NULL` if the corresponding `salt_type` does not require an input.
@ -80,6 +75,14 @@ extern "C" {
/// This function takes ownership of and frees `context` after it has been called.
