TCryptoHash · BlitzMax

Transforms an arbitrary-long input into a fixed length fingerprint

This API requires a context. Similar to a type, a context is a 8 characters string describing what the function is going to be used for.

Its purpose is to mitigate accidental bugs by separating domains. The same function used with the same key but in two distinct contexts is likely to generate two different outputs.

Therefore, a key designed to encrypt data used in a specific context will not be able to decrypt data if accidentally used in another context.

Contexts don't have to be secret and can have a low entropy. Examples of contexts include UserName, __auth__, pictures and userdata.

If more convenient, it is also fine to use a single global context for a whole application. This will still prevent the same key from being mistakenly used by another application.

Methods

`Method Create:TCryptoHash(context:String, key:TCryptoHashKey)`

Initializes a state state with a key key (that can be NULL), in order to eventually produce output.

`Method Update:Int(in:Byte Ptr, inLen:Size_T)`

Sequentially processes a chunk in of inLen bytes in length.

`Method Update:Int(in:Byte[])`

Sequentially processes a chunk in.

`Method Finish(out:Byte Ptr, outLen:Size_T)`

Completes the operation and puts the final fingerprint into out as outlen bytes.

`Method Finish(out:Byte[])`

Completes the operation and puts the final fingerprint into out.

Functions

`Function KeyGen:TCryptoHashKey()`

Creates a secret key suitable for use with the TCryptoHash functions.

Example

SuperStrict

Framework brl.standardio
Import Crypto.Crypto

Local key:TCryptoHashKey = TCryptoHash.KeyGen()

Print key.ToString()

`Function Hash:Int(out:Byte Ptr, outLen:Size_T, in:Byte Ptr, inLen:Size_T, context:String, key:TCryptoHashKey)`

Puts a fingerprint of the message in whose length is inLen bytes into out.

The output size can be chosen by the application. The minimum recommended output size is CRYPTO_HASH_BYTES. This size makes it practically impossible for two messages to produce the same fingerprint.

But for specific use cases, the size can be any value between CRYPTO_HASH_BYTES_MIN (included) and CRYPTO_HASH_BYTES_MAX (included).

key can be NULL. In this case, a message will always have the same fingerprint, similar to the MD5 or SHA-1 functions for which Hash() is a faster and more secure alternative.

But a key can also be specified. A message will always have the same fingerprint for a given key, but different keys used to hash the same message are very likely to produce distinct fingerprints.

In particular, the key can be used to make sure that different applications generate different fingerprints even if they process the same data.

The key size is CRYPTO_HASH_KEYBYTES bytes.

`Function Hash:Int(out:Byte[], in:Byte[], context:String, key:TCryptoHashKey)`

Puts a fingerprint of the message in into out.