plibsys 0.0.5
Typedefs | Enumerations | Functions
pcryptohash.h File Reference

Cryptographic hash function. More...

#include <pmacros.h>
#include <ptypes.h>

Go to the source code of this file.

Typedefs

typedef struct PCryptoHash_ PCryptoHash
 Opaque data structure for handling a cryptographic hash context.
 
typedef enum PCryptoHashType_ PCryptoHashType
 Cryptographic hash function types for PCryptoHash.
 

Enumerations

enum  PCryptoHashType_ {
  P_CRYPTO_HASH_TYPE_MD5 = 0 , P_CRYPTO_HASH_TYPE_SHA1 = 1 , P_CRYPTO_HASH_TYPE_SHA2_224 = 2 , P_CRYPTO_HASH_TYPE_SHA2_256 = 3 ,
  P_CRYPTO_HASH_TYPE_SHA2_384 = 4 , P_CRYPTO_HASH_TYPE_SHA2_512 = 5 , P_CRYPTO_HASH_TYPE_SHA3_224 = 6 , P_CRYPTO_HASH_TYPE_SHA3_256 = 7 ,
  P_CRYPTO_HASH_TYPE_SHA3_384 = 8 , P_CRYPTO_HASH_TYPE_SHA3_512 = 9 , P_CRYPTO_HASH_TYPE_GOST = 10
}
 Cryptographic hash function types for PCryptoHash. More...
 

Functions

P_LIB_API PCryptoHash * p_crypto_hash_new (PCryptoHashType type)
 Initializes a new PCryptoHash context.
 
P_LIB_API void p_crypto_hash_update (PCryptoHash *hash, const puchar *data, psize len)
 Adds a new chunk of data for hashing.
 
P_LIB_API void p_crypto_hash_reset (PCryptoHash *hash)
 Resets a hash state.
 
P_LIB_API pchar * p_crypto_hash_get_string (PCryptoHash *hash)
 Gets a hash in a hexidemical representation.
 
P_LIB_API void p_crypto_hash_get_digest (PCryptoHash *hash, puchar *buf, psize *len)
 Gets a hash in a raw representation.
 
P_LIB_API pssize p_crypto_hash_get_length (const PCryptoHash *hash)
 Gets a hash digest length depending on its type.
 
P_LIB_API PCryptoHashType p_crypto_hash_get_type (const PCryptoHash *hash)
 Gets a hash function type.
 
P_LIB_API void p_crypto_hash_free (PCryptoHash *hash)
 Frees a previously initialized hash context.
 

Detailed Description

Cryptographic hash function.

Author
Alexander Saprykin

A cryptographic hash function is an algorithm which performs a transformation of the income data to a hash value.

One of the main requirements to all of the cryptographic hashing algorithms is that any (even a considerably small) change in the input data must lead to notable changes in the result hash value. It is the so called avalanche effect. It helps to avoid collisions (the same hash value for different input arrays).

The cryptographic hash function is designed to be a one-way so you couldn't revert the output hash value to the input data back. The length of the resulting hash is a constant value depending on the algorithm being used.

A cryptographic hash works with the incoming data using fixed length blocks so it is possible to feed as many data as required.

The cryptographic hash module supports the following hash functions:

  • MD5;
  • SHA-1;
  • SHA-2/224;
  • SHA-2/256;
  • SHA-2/384;
  • SHA-2/512;
  • SHA-3/224;
  • SHA-3/256;
  • SHA-3/384;
  • SHA-3/512;
  • GOST (R 34.11-94).

Use p_crypto_hash_new() to initialize a new hash context with one of the mentioned above types. Data for hashing can be added in several chunks using the p_crypto_hash_update() routine. You can add more chunks as long as the hash context is open.

The hash context becomes close in two cases: p_crypto_hash_get_string() or p_crypto_hash_get_digest() was called. After that you can only get a hash in a hexidemical string or in a raw representation.

A hashing algorithm couldn't be changed after the context initialization.

Definition in file pcryptohash.h.

Typedef Documentation

◆ PCryptoHash

typedef struct PCryptoHash_ PCryptoHash

Opaque data structure for handling a cryptographic hash context.

Definition at line 85 of file pcryptohash.h.

Enumeration Type Documentation

◆ PCryptoHashType_

enum PCryptoHashType_

Cryptographic hash function types for PCryptoHash.

Enumerator
P_CRYPTO_HASH_TYPE_MD5 

MD5 hash function.

Since
0.0.1
P_CRYPTO_HASH_TYPE_SHA1 

SHA-1 hash function.

Since
0.0.1
P_CRYPTO_HASH_TYPE_SHA2_224 

SHA-2/224 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA2_256 

SHA-2/256 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA2_384 

SHA-2/384 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA2_512 

SHA-2/512 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA3_224 

SHA-2/224 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA3_256 

SHA-2/256 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA3_384 

SHA-2/384 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_SHA3_512 

SHA-3/512 hash function.

Since
0.0.2
P_CRYPTO_HASH_TYPE_GOST 

GOST (R 34.11-94) hash function.

Since
0.0.1

Definition at line 88 of file pcryptohash.h.

Function Documentation

◆ p_crypto_hash_free()

P_LIB_API void p_crypto_hash_free ( PCryptoHash * hash)

Frees a previously initialized hash context.

Parameters
hashPCryptoHash context to free.
Since
0.0.1

◆ p_crypto_hash_get_digest()

P_LIB_API void p_crypto_hash_get_digest ( PCryptoHash * hash,
puchar * buf,
psize * len )

Gets a hash in a raw representation.

Parameters
hashPCryptoHash context to get a digest from.
bufBuffer to store the digest with the hash raw representation.
[in,out]lenSize of buf when calling, count of written bytes after.
Note
Before getting the raw digest the hash context will be closed for further updates.
Since
0.0.1

◆ p_crypto_hash_get_length()

P_LIB_API pssize p_crypto_hash_get_length ( const PCryptoHash * hash)

Gets a hash digest length depending on its type.

Parameters
hashPCryptoHash context to get the length for.
Returns
Length (in bytes) of the given hash depending on its type in case of success, -1 otherwise.
Note
This length doesn't match a string hash representation.
Since
0.0.1

◆ p_crypto_hash_get_string()

P_LIB_API pchar * p_crypto_hash_get_string ( PCryptoHash * hash)

Gets a hash in a hexidemical representation.

Parameters
hashPCryptoHash context to get a string from.
Returns
NULL-terminated string with the hexidemical representation of a hash state in case of success, NULL otherwise. The string should be freed with p_free() after using it.
Note
Before returning the string the hash context will be closed for further updates.
Since
0.0.1

◆ p_crypto_hash_get_type()

P_LIB_API PCryptoHashType p_crypto_hash_get_type ( const PCryptoHash * hash)

Gets a hash function type.

Parameters
hashPCryptoHash context to get the type for.
Returns
Hash function type used in the given context.
Since
0.0.1

◆ p_crypto_hash_new()

P_LIB_API PCryptoHash * p_crypto_hash_new ( PCryptoHashType type)

Initializes a new PCryptoHash context.

Parameters
typeHash function type to use, can't be changed later.
Returns
Newly initialized PCryptoHash context in case of success, NULL otherwise.
Since
0.0.1

◆ p_crypto_hash_reset()

P_LIB_API void p_crypto_hash_reset ( PCryptoHash * hash)

Resets a hash state.

Parameters
hashPCryptoHash context to reset.
Since
0.0.1

After a reset the hash context becomes open for updating, but all previously added data will be lost. A hash function type couldn't be changed during or after the resets.

◆ p_crypto_hash_update()

P_LIB_API void p_crypto_hash_update ( PCryptoHash * hash,
const puchar * data,
psize len )

Adds a new chunk of data for hashing.

Parameters
hashPCryptoHash context to add data to.
dataData to add for hashing.
lenData length, in bytes.
Note
After calling p_crypto_hash_get_string() or p_crypto_hash_get_digest() the hash couldn't be updated anymore as it becomes close.
Since
0.0.1
Generated by doxygen 1.12.0