Guardtime KSI c SDK
Data Structures | Macros | Typedefs | Enumerations | Functions
Data Hashing

Data Structures

struct  KSI_DataHash_list_st
 

Macros

#define KSI_MAX_IMPRINT_LEN   65 /* Algorithm ID (1 byte) + longest digest */
 
#define KSI_DataHashList_append(lst, o)   KSI_APPLY_TO_NOT_NULL((lst), append, ((lst), (o)))
 
#define KSI_DataHashList_remove(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), removeElement, ((lst), (pos), (o)))
 
#define KSI_DataHashList_indexOf(lst, o, i)   KSI_APPLY_TO_NOT_NULL((lst), indexOf, ((lst), (o), (i)))
 
#define KSI_DataHashList_insertAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), insertAt, ((lst), (pos), (o)))
 
#define KSI_DataHashList_replaceAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), replaceAt, ((lst), (pos), (o)))
 
#define KSI_DataHashList_elementAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), elementAt, ((lst), (pos), (o)))
 
#define KSI_DataHashList_length(lst)   (((lst) != NULL && (lst)->length != NULL) ? (lst)->length((lst)) : 0)
 
#define KSI_DataHashList_sort(lst, cmp)   KSI_APPLY_TO_NOT_NULL((lst), sort, ((lst), (cmp)))
 
#define KSI_DataHashList_foldl(lst, foldCtx, foldFn)   (((lst) != NULL) ? (((lst)->foldl != NULL) ? ((lst)->foldl((lst), (foldCtx), (foldFn))) : KSI_INVALID_STATE) : KSI_OK)
 

Typedefs

typedef struct KSI_DataHasher_st KSI_DataHasher
 
typedef struct KSI_DataHash_st KSI_DataHash
 
typedef enum KSI_HashAlgorithm_en KSI_HashAlgorithm
 
typedef struct KSI_DataHash_list_st KSI_DataHashList
 

Enumerations

enum  KSI_HashAlgorithm_en {
  KSI_HASHALG_INVALID = -1, KSI_HASHALG_SHA1 = 0x00, KSI_HASHALG_SHA2_256 = 0x01, KSI_HASHALG_RIPEMD160 = 0x02,
  KSI_HASHALG_SHA2_384 = 0x04, KSI_HASHALG_SHA2_512 = 0x05, KSI_HASHALG_SHA3_244 = 0x07, KSI_HASHALG_SHA3_256 = 0x08,
  KSI_HASHALG_SHA3_384 = 0x09, KSI_HASHALG_SHA3_512 = 0x0a, KSI_HASHALG_SM3 = 0x0b, KSI_NUMBER_OF_KNOWN_HASHALGS
}
 

Functions

int KSI_DataHasher_open (KSI_CTX *ctx, KSI_HashAlgorithm algo_id, KSI_DataHasher **hasher)
 
int KSI_DataHasher_reset (KSI_DataHasher *hasher)
 
int KSI_DataHasher_add (KSI_DataHasher *hasher, const void *data, size_t data_length)
 
int KSI_DataHasher_addImprint (KSI_DataHasher *hasher, const KSI_DataHash *hsh)
 
int KSI_DataHasher_addOctetString (KSI_DataHasher *hasher, const KSI_OctetString *data)
 
int KSI_DataHasher_close (KSI_DataHasher *hasher, KSI_DataHash **hash)
 
void KSI_DataHasher_free (KSI_DataHasher *hasher)
 
void KSI_DataHash_free (KSI_DataHash *hash)
 
int KSI_DataHash_create (KSI_CTX *ctx, const void *data, size_t data_length, KSI_HashAlgorithm algo_id, KSI_DataHash **hash)
 
int KSI_DataHash_clone (KSI_DataHash *from, KSI_DataHash **to)
 
int KSI_DataHash_extract (const KSI_DataHash *hash, KSI_HashAlgorithm *algo_id, const unsigned char **digest, size_t *digest_length)
 
int KSI_DataHash_fromDigest (KSI_CTX *ctx, KSI_HashAlgorithm algo_id, const unsigned char *digest, size_t digest_length, KSI_DataHash **hash)
 
int KSI_DataHash_getImprint (const KSI_DataHash *hash, const unsigned char **imprint, size_t *imprint_length)
 
int KSI_DataHash_fromImprint (KSI_CTX *ctx, const unsigned char *imprint, size_t imprint_length, KSI_DataHash **hash)
 
KSI_HashAlgorithm KSI_getHashAlgorithmByName (const char *name)
 
unsigned int KSI_getHashLength (KSI_HashAlgorithm algo_id)
 
unsigned int KSI_HashAlgorithm_getBlockSize (KSI_HashAlgorithm algo_id)
 
int KSI_isHashAlgorithmTrusted (KSI_HashAlgorithm algo_id)
 
int KSI_isHashAlgorithmSupported (KSI_HashAlgorithm algo_id)
 
const char * KSI_getHashAlgorithmName (KSI_HashAlgorithm algo_id)
 
int KSI_DataHash_equals (const KSI_DataHash *left, const KSI_DataHash *right)
 
int KSI_DataHash_fromTlv (KSI_TLV *tlv, KSI_DataHash **o)
 
int KSI_DataHash_toTlv (KSI_CTX *ctx, const KSI_DataHash *o, unsigned tag, int isNonCritical, int isForward, KSI_TLV **tlv)
 
int KSI_DataHash_getHashAlg (const KSI_DataHash *hash, KSI_HashAlgorithm *algo_id)
 
char * KSI_DataHash_toString (const KSI_DataHash *hsh, char *buf, size_t buf_len)
 
int KSI_DataHash_createZero (KSI_CTX *ctx, KSI_HashAlgorithm algo_id, KSI_DataHash **hsh)
 
KSI_DataHashKSI_DataHash_ref (KSI_DataHash *o)
 
int KSI_DataHashList_new (KSI_DataHashList **list)
 
void KSI_DataHashList_free (KSI_DataHashList *list)
 

Detailed Description

This module consists of two main objects:

Macro Definition Documentation

◆ KSI_DataHashList_append

#define KSI_DataHashList_append (   lst,
 
)    KSI_APPLY_TO_NOT_NULL((lst), append, ((lst), (o)))

◆ KSI_DataHashList_elementAt

#define KSI_DataHashList_elementAt (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), elementAt, ((lst), (pos), (o)))

◆ KSI_DataHashList_foldl

#define KSI_DataHashList_foldl (   lst,
  foldCtx,
  foldFn 
)    (((lst) != NULL) ? (((lst)->foldl != NULL) ? ((lst)->foldl((lst), (foldCtx), (foldFn))) : KSI_INVALID_STATE) : KSI_OK)

◆ KSI_DataHashList_indexOf

#define KSI_DataHashList_indexOf (   lst,
  o,
 
)    KSI_APPLY_TO_NOT_NULL((lst), indexOf, ((lst), (o), (i)))

◆ KSI_DataHashList_insertAt

#define KSI_DataHashList_insertAt (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), insertAt, ((lst), (pos), (o)))

◆ KSI_DataHashList_length

#define KSI_DataHashList_length (   lst)    (((lst) != NULL && (lst)->length != NULL) ? (lst)->length((lst)) : 0)

◆ KSI_DataHashList_remove

#define KSI_DataHashList_remove (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), removeElement, ((lst), (pos), (o)))

◆ KSI_DataHashList_replaceAt

#define KSI_DataHashList_replaceAt (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), replaceAt, ((lst), (pos), (o)))

◆ KSI_DataHashList_sort

#define KSI_DataHashList_sort (   lst,
  cmp 
)    KSI_APPLY_TO_NOT_NULL((lst), sort, ((lst), (cmp)))

◆ KSI_MAX_IMPRINT_LEN

#define KSI_MAX_IMPRINT_LEN   65 /* Algorithm ID (1 byte) + longest digest */

The maximum length of an imprint.

Typedef Documentation

◆ KSI_DataHash

typedef struct KSI_DataHash_st KSI_DataHash

This structure represents hashed data.

See also
KSI_DataHasher, KSI_DataHasher_close, KSI_DataHash_free

◆ KSI_DataHasher

typedef struct KSI_DataHasher_st KSI_DataHasher

This structure is used for calculating the hash values.

See also
KSI_DataHash, KSI_DataHasher_open, KSI_DataHasher_reset, KSI_DataHasher_close, KSI_DataHasher_free

◆ KSI_DataHashList

◆ KSI_HashAlgorithm

The Guardtime representation of hash algorithms, necessary to calculate instances of KSI_DataHasher and KSI_DataHash.

Enumeration Type Documentation

◆ KSI_HashAlgorithm_en

The Guardtime representation of hash algorithms, necessary to calculate instances of KSI_DataHasher and KSI_DataHash.

Enumerator
KSI_HASHALG_INVALID 

An invalid hash algorithm. This is returned from KSI_getHashAlgorithmByName,

KSI_HASHALG_SHA1 

The SHA-1 algorithm.

KSI_HASHALG_SHA2_256 

The SHA-256 algorithm.

KSI_HASHALG_RIPEMD160 

The RIPEMD-160 algorithm.

KSI_HASHALG_SHA2_384 

The SHA-384 algorithm.

KSI_HASHALG_SHA2_512 

The SHA-512 algorithm.

KSI_HASHALG_SHA3_244 

The SHA3-244 algorithm.

KSI_HASHALG_SHA3_256 

The SHA3-256 algorithm.

KSI_HASHALG_SHA3_384 

The SHA3-384 algorithm.

KSI_HASHALG_SHA3_512 

The SHA3-512 algorithm

KSI_HASHALG_SM3 

The SM3 algorithm.

KSI_NUMBER_OF_KNOWN_HASHALGS 

Function Documentation

◆ KSI_DataHash_clone()

int KSI_DataHash_clone ( KSI_DataHash from,
KSI_DataHash **  to 
)

Creates a clone of the data hash.

Parameters
[in]fromData hash to be cloned.
[out]toPointer to the receiving pointer to the cloned object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Deprecated:
Use KSI_DataHash_ref instead.

◆ KSI_DataHash_create()

int KSI_DataHash_create ( KSI_CTX ctx,
const void *  data,
size_t  data_length,
KSI_HashAlgorithm  algo_id,
KSI_DataHash **  hash 
)

Calculates the data hash object from the input data.

Parameters
[in]ctxKSI context.
[in]dataPointer to the input data.
[in]data_lengthLength of the imput data.
[in]algo_idHash algorithm id.
[out]hashPointer to the pointer receiving the data hash object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHash_free

◆ KSI_DataHash_createZero()

int KSI_DataHash_createZero ( KSI_CTX ctx,
KSI_HashAlgorithm  algo_id,
KSI_DataHash **  hsh 
)

Creates a hash value where all the bits in the digest are set to zero.

Parameters
[in]ctxKSI context.
[in]algo_idThe hash algorithm id.
[out]hshPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_DataHash_equals()

int KSI_DataHash_equals ( const KSI_DataHash left,
const KSI_DataHash right 
)

Returns 1 if the two given data hash objects are both not NULL and the hash values equal to each other.

Parameters
[in]leftOne data hash object.
[in]rightAn other data hash object.
Returns
Returns 0 if the hash object are NULL or are not equal, otherwise non-zero value is returned.

◆ KSI_DataHash_extract()

int KSI_DataHash_extract ( const KSI_DataHash hash,
KSI_HashAlgorithm algo_id,
const unsigned char **  digest,
size_t *  digest_length 
)

Extracts the hashing algorithm, digest and its length from the KSI_DataHash. If any of the output pointers is NULL, it is ignored. The digest is a pointer to an internal field of the KSI_DataHash thus extracting the digest does not make a copy of the buffer. This means the digest pointer is valid until KSI_DataHash_free is called on the object.

Parameters
[in]hashData hash object.
[out]algo_idAlgorithm used to compute the hash.
[out]digestBinary digest value.
[out]digest_lengthLength of the digest value.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
If an output variable is set to NULL the value will be ignored.
See also
KSI_DataHash_free, KSI_DataHash_create, KSI_DataHash_fromDigest

◆ KSI_DataHash_free()

void KSI_DataHash_free ( KSI_DataHash hash)

Frees the data hash object..

Parameters
[in]hashKSI_DataHash object that is to be freed.
See also
KSI_DataHasher_close, KSI_DataHash_fromImprint, KSI_DataHash_fromDigest

◆ KSI_DataHash_fromDigest()

int KSI_DataHash_fromDigest ( KSI_CTX ctx,
KSI_HashAlgorithm  algo_id,
const unsigned char *  digest,
size_t  digest_length,
KSI_DataHash **  hash 
)

Constructor for KSI_DataHash object from existing hash value.

Parameters
[in]ctxKSI context.
[in]algo_idAlgorithm used to compute the digest value.
[in]digestBinary digest value.
[in]digest_lengthLength of the binary digest value.
[in]hashPointer that will receive pointer to the hash object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHash_free, KSI_DataHash_extract, KSI_DataHash_fromImprint, KSI_DataHash_create, KSI_DataHasher_close

◆ KSI_DataHash_fromImprint()

int KSI_DataHash_fromImprint ( KSI_CTX ctx,
const unsigned char *  imprint,
size_t  imprint_length,
KSI_DataHash **  hash 
)

Constructor for KSI_DataHash object from existing imprint.

Parameters
[in]ctxKSI context.
[in]imprintPointer to the imprint.
[in]imprint_lengthLength of the imprint.
[out]hashPointer that will receive pointer to the data hash objet.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHash_free, KSI_DataHash_getImprint, KSI_DataHash_fromDigest

◆ KSI_DataHash_fromTlv()

int KSI_DataHash_fromTlv ( KSI_TLV tlv,
KSI_DataHash **  o 
)

Function to convert a plain KSI_TLV to a KSI_DataHash . The TLV meta data (i.e. tag, length and flags) are not preserved.

Parameters
[in]tlvPointer to KSI_TLV.
[out]oPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHash_fromTlv

◆ KSI_DataHash_getHashAlg()

int KSI_DataHash_getHashAlg ( const KSI_DataHash hash,
KSI_HashAlgorithm algo_id 
)

Accessor method for extracting the hash algorithm from the KSI_DataHash.

Parameters
hashData hash object.
algo_idPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_DataHash_getImprint()

int KSI_DataHash_getImprint ( const KSI_DataHash hash,
const unsigned char **  imprint,
size_t *  imprint_length 
)

Encodes the data hash object as an imprint.

Parameters
[in]hashData hash object.
[out]imprintPointer that will receive pointer to the imprint.
[out]imprint_lengthPointer that will receive the length of the imprint.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_DataHash_ref()

KSI_DataHash* KSI_DataHash_ref ( KSI_DataHash o)
  • Increases the inner reference count of that object. *
    Parameters
    [in]oPointer to KSI_DataHash *
    Returns
    Returns the input pointer on success or NULL on error. *
    See also
    KSI_DataHash_free

◆ KSI_DataHash_toString()

char* KSI_DataHash_toString ( const KSI_DataHash hsh,
char *  buf,
size_t  buf_len 
)

Creates a string representation of the datahash.

Parameters
[in]hshInput hash object.
[in,out]bufPointer to the receiving buffer.
[in]buf_lenLength of the receiving buffer.
Returns
Returns the pointer to the buffer or NULL on error.

◆ KSI_DataHash_toTlv()

int KSI_DataHash_toTlv ( KSI_CTX ctx,
const KSI_DataHash o,
unsigned  tag,
int  isNonCritical,
int  isForward,
KSI_TLV **  tlv 
)

Function to convert a KSI_DataHash to a plain KSI_TLV object.

Parameters
[in]ctxKSI context.
[in]oPointer to KSI_DataHash
[in]tagTag value of the KSI_TLV
[in]isNonCriticalFlag is-non-critical.
[in]isForwardFlag is-forward.
[out]tlvPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHash_fromTlv, KSI_TLV_free

◆ KSI_DataHasher_add()

int KSI_DataHasher_add ( KSI_DataHasher hasher,
const void *  data,
size_t  data_length 
)

Adds data to an open hash computation.

Parameters
[in]hasherHasher object.
[in]dataPointer to the data to be hashed.
[in]data_lengthLength of the hashed data.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHasher_open, KSI_DataHasher_close

◆ KSI_DataHasher_addImprint()

int KSI_DataHasher_addImprint ( KSI_DataHasher hasher,
const KSI_DataHash hsh 
)

Adds the imprint value to the hash computation.

Parameters
[in]hasherHasher object.
[in]hshDatahash object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_DataHasher_addOctetString()

int KSI_DataHasher_addOctetString ( KSI_DataHasher hasher,
const KSI_OctetString data 
)

Adds the value of the octet string to the hash computation.

Parameters
[in]hasherHasher object.
[in]dataOctet string object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_DataHasher_close()

int KSI_DataHasher_close ( KSI_DataHasher hasher,
KSI_DataHash **  hash 
)

Finalizes a hash computation.

Parameters
[in]hasherHasher object.
[out]hashPointer that will receive pointer to the hash object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHasher_open, KSI_DataHasher_add, KSI_DataHasher_free

◆ KSI_DataHasher_free()

void KSI_DataHasher_free ( KSI_DataHasher hasher)

Frees the data hasher object.

Parameters
[in]hasherHasher object.
See also
KSI_DataHasher_open

◆ KSI_DataHasher_open()

int KSI_DataHasher_open ( KSI_CTX ctx,
KSI_HashAlgorithm  algo_id,
KSI_DataHasher **  hasher 
)

Starts a hash computation.

Parameters
[in]ctxKSI context.
[in]algo_idIdentifier of the hash algorithm. See KSI_HashAlgorithm_en for possible values.
[out]hasherPointer that will receive pointer to the hasher object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHasher_add, KSI_DataHasher_close

◆ KSI_DataHasher_reset()

int KSI_DataHasher_reset ( KSI_DataHasher hasher)

Resets the state of the hash computation.

Parameters
[in]hasherThe hasher.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHasher_open, KSI_DataHasher_close

◆ KSI_DataHashList_free()

void KSI_DataHashList_free ( KSI_DataHashList list)

◆ KSI_DataHashList_new()

int KSI_DataHashList_new ( KSI_DataHashList **  list)

◆ KSI_getHashAlgorithmByName()

KSI_HashAlgorithm KSI_getHashAlgorithmByName ( const char *  name)

Returns the hash algorithm specified by the case insensitive string parameter name . If the algorithm name is not recognized the value of KSI_HASHALG_INVALID, witch is not a correct hashing algorithm, is returned. To verify the correctness of the returned value KSI_isHashAlgorithmSupported or KSI_isHashAlgorithmTrusted function must be used. The valid inputs are "default" for the configured default hash algorithm or one of the following: "sha-1", "sha1", "sha-256", "sha2-256", "sha-2", "sha2", "sha256", "ripemd-160", "ripemd160", "sha-384", "sha384", "sha2-384", "sha-512", "sha512", "sha2-512", "sha3-224", "sha3-256", "sha3-384", "sha3-512", "sm-3", "sm3".

Note
The SHA-2 family names do not require the infix "2" as opposed to the SHA-3 family where the infix "3" is mandatory. This means "sha-256" is unambiguously the 256 bit version of SHA-2.
Parameters
[in]nameName of the hash function.
Returns
The hash algorithm id or -1 if it was not found.
See also
KSI_getHashAlgorithmName

◆ KSI_getHashAlgorithmName()

const char* KSI_getHashAlgorithmName ( KSI_HashAlgorithm  algo_id)

Returns a pointer to constant string containing the name of the hash algorithm. Returns NULL if the algorithm is unknown.

Parameters
[in]algo_idThe hash algorithm id.
Returns
Name of the algorithm or NULL on error.
See also
KSI_getHashAlgorithmByName

◆ KSI_getHashLength()

unsigned int KSI_getHashLength ( KSI_HashAlgorithm  algo_id)

Returns the hash length in bytes for the given hash algorithm id or -1 if the hash algorithm is not recognized or supported.

Parameters
[in]algo_idHash algorithm id
Returns
Length of the hash value calculated by the given hash algorithm. Returns value 0 on error.

◆ KSI_HashAlgorithm_getBlockSize()

unsigned int KSI_HashAlgorithm_getBlockSize ( KSI_HashAlgorithm  algo_id)

Returns the size of the data block the underlying hash algorithm operates upon in bytes.

Parameters
[in]algo_idHash algorithm id.
Returns
Returns the size of the data block the underlying hash algorithm or 0 on errir.

◆ KSI_isHashAlgorithmSupported()

int KSI_isHashAlgorithmSupported ( KSI_HashAlgorithm  algo_id)

Is the given hash algorithm hash_id supported, meaning the hash value can be calculated using the API.

Parameters
[in]algo_idHash algorithm id.
Returns
Returns 0 if algorithm is not supported, otherwise non-zero.
See also
KSI_isHashAlgorithmTrusted

◆ KSI_isHashAlgorithmTrusted()

int KSI_isHashAlgorithmTrusted ( KSI_HashAlgorithm  algo_id)

This function is used to check if the given hash algorithm is trusted. If the hash algorithm is trusted it returns 1, in all other cases 0.

Parameters
[in]algo_idHash algorithm id.
Returns
Returns 1 if algorithm is trusted, otherwise return 0.
See also
KSI_isHashAlgorithmSupported