Guardtime KSI c SDK
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
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)
 
#define KSI_DataHashList_find(lst, o, f, i)   KSI_APPLY_TO_NOT_NULL((lst), find, ((lst), (o), (f), (i)))
 

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_DO_NOT_USE = -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_224 = 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,
  KSI_HASHALG_INVALID_VALUE = 0x100
}
 

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)
 
time_t KSI_HashAlgorithm_getDeprecatedFrom (KSI_HashAlgorithm algo_id)
 
time_t KSI_HashAlgorithm_getObsoleteFrom (KSI_HashAlgorithm algo_id)
 
int KSI_isHashAlgorithmTrusted (KSI_HashAlgorithm algo_id)
 
int KSI_checkHashAlgorithmAt (KSI_HashAlgorithm algo_id, time_t used_at)
 
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)
 

Variables

const int KSI_HASHALG_INVALID
 
const int KSI_HASHALG_SHA3_244
 

Detailed Description

This module consists of two main objects:

Macro Definition Documentation

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

The maximum length of an imprint.

Typedef Documentation

typedef struct KSI_DataHash_st KSI_DataHash

This structure represents hashed data.

See also
KSI_DataHasher, KSI_DataHasher_close, KSI_DataHash_free
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

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

Enumeration Type Documentation

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

Enumerator
__KSI_HASHALG_DO_NOT_USE 
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_224 

The SHA3-224 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 
KSI_HASHALG_INVALID_VALUE 

An invalid hash algorithm.

Function Documentation

int KSI_checkHashAlgorithmAt ( KSI_HashAlgorithm  algo_id,
time_t  used_at 
)

This function will check the status of the hash algorithm at a given time.

Parameters
[in]algo_idHash algorithm id.
[in]used_atUTC time when the algorithm was/is used.
Returns
KSI_UNKNOWN_HASH_ALGORITHM_ID if the hash algorithm ID is invalid, or
KSI_HASH_ALGORITHM_DEPRECATED if the hash algorithm was deprecated at used_at, or
KSI_HASH_ALGORITHM_OBSOLETE if the hash algorithm was obsolete at used_at, and
KSI_OK otherwise.
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.
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).
Note
The KSI context can be NULL, but this will make debugging more difficult and will reduce performance.
See also
KSI_DataHash_free
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).
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.
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
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
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.
Note
The KSI context can be NULL, but this will make debugging more difficult and will reduce performance.
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
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.
Note
The KSI context can be NULL, but this will make debugging more difficult and will reduce performance.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_DataHash_free, KSI_DataHash_getImprint, KSI_DataHash_fromDigest
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
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).
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* 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
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.
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
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
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).
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).
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
void KSI_DataHasher_free ( KSI_DataHasher hasher)

Frees the data hasher object.

Parameters
[in]hasherHasher object.
See also
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).
Note
The KSI context can be NULL, but this will make debugging more difficult and will reduce performance.
See also
KSI_DataHasher_add, KSI_DataHasher_close
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
void KSI_DataHashList_free ( KSI_DataHashList list)
int KSI_DataHashList_new ( KSI_DataHashList **  list)
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 invalid 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 invalid algorithm if it was not found.
See also
KSI_getHashAlgorithmName
KSI_isHashAlgorithmSupported
KSI_isHashAlgorithmTrusted
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
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.
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 error.
time_t KSI_HashAlgorithm_getDeprecatedFrom ( KSI_HashAlgorithm  algo_id)

The time the function has been marked as deprecated.

Parameters
[in]algo_idHash algorithm id.
Returns
Hash algorithm deprecate time or 0 if not set.
In case of an error a negative value is returned.
time_t KSI_HashAlgorithm_getObsoleteFrom ( KSI_HashAlgorithm  algo_id)

The time the function has been marked as obsolete.

Parameters
[in]algo_idHash algorithm id.
Returns
Hash algorithm obsolete time or 0 if not set.
In case of an error a negative value is returned.
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_checkHashAlgorithmAt
int KSI_isHashAlgorithmTrusted ( KSI_HashAlgorithm  algo_id)

This function is used to check if the given hash algorithm is trusted. If the algorithm has been marked as deprecated or obsolete, it will return 0 or otherwise 1 is returned.

Note
It is not checked if the deprecated and/or obsolete dates have passed but operation is impossible as soon as one of the dates is set. The intention is to make the change apparent right after upgrading the library rather than wait and possibly break normal operations in an apparently arbitrary moment.
Parameters
[in]algo_idHash algorithm id.
Returns
Returns 1 if algorithm is trusted, otherwise return 0.
See also
KSI_isHashAlgorithmSupported, KSI_checkHashAlgorithmAt

Variable Documentation

const int KSI_HASHALG_INVALID
const int KSI_HASHALG_SHA3_244
Deprecated:
This is a typo - use KSI_HASHALG_SHA3_224 instead!