SHA

SHA — SHA hash

Synopsis


#include <gnet.h>


                    GSHA;
#define             GNET_SHA_HASH_LENGTH
GSHA*               gnet_sha_new                        (const gchar *buffer,
                                                         guint length);
GSHA*               gnet_sha_new_string                 (const gchar *str);
GSHA*               gnet_sha_clone                      (const GSHA *sha);
void                gnet_sha_delete                     (GSHA *sha);
GSHA*               gnet_sha_new_incremental            (void);
void                gnet_sha_update                     (GSHA *sha,
                                                         const gchar *buffer,
                                                         guint length);
void                gnet_sha_final                      (GSHA *sha);
gboolean            gnet_sha_equal                      (gconstpointer p1,
                                                         gconstpointer p2);
guint               gnet_sha_hash                       (gconstpointer p);
gchar*              gnet_sha_get_digest                 (const GSHA *sha);
gchar*              gnet_sha_get_string                 (const GSHA *sha);
void                gnet_sha_copy_string                (const GSHA *sha,
                                                         gchar *buffer);

Description

The SHA module provide support for computing and manipulating SHA hashes. SHA is a hash function with a very low probability of collision. SHA is considered stronger than MD5.

A SHA can be calculated at one time or incrementally. To create a SHA at one time, call gnet_sha_new() with the data. To create a SHA incrementally, call gnet_sha_new_incremental() to create the SHA object, then gnet_sha_update() one or more times with data to hash, and finally call gnet_sha_final().

To get the digest, or hash value, call gnet_sha_get_digest(). This returns the raw digest as an array of GNET_SHA_HASH_LENGTH bytes. To get the digest as a human-readable string, call gnet_sha_get_string() or gnet_sha_copy_string(). 

gchar buffer[] = "Hello world!";
gchar buffer2[] = "Second line";
GSHA*  sha;
gchar* sha_str;

/* Compute an SHA at one time */
sha = gnet_sha_new (buffer, strlen(buffer));

sha_str = gnet_sha_get_string (sha);
g_print ("The SHA of %s is %s\n", buffer, sha_str);

/* Use SHA... */

g_free (sha_str);
gnet_sha_delete (sha);

/* Compute an SHA incrementally */
sha = gnet_sha_new_incremental ();
gnet_sha_update (sha, buffer, strlen(buffer));
gnet_sha_update (sha, buffer2, strlen(buffer2));
gnet_sha_final (sha);

/* Use SHA... */

gnet_sha_delete (sha);

Details

GSHA

typedef struct _GSHA GSHA;

GSHA is a SHA hash.

GNET_SHA_HASH_LENGTH

#define GNET_SHA_HASH_LENGTH	20

Length of the SHA hash in bytes.

gnet_sha_new ()

GSHA*               gnet_sha_new                        (const gchar *buffer,
                                                         guint length);

Creates a GSHA from buffer.

buffer : buffer to hash
length : length of buffer
Returns : a new GSHA.

gnet_sha_new_string ()

GSHA*               gnet_sha_new_string                 (const gchar *str);

Createss a GSHA from str. str is a hexidecimal string representing the digest.

str : hexidecimal string
Returns : a new GSHA.

gnet_sha_clone ()

GSHA*               gnet_sha_clone                      (const GSHA *sha);

Copies a GSHA.

sha : a GSHA
Returns : a copy of sha.

gnet_sha_delete ()

void                gnet_sha_delete                     (GSHA *sha);

Deletes a GSHA.

sha : a GSHA

gnet_sha_new_incremental ()

GSHA*               gnet_sha_new_incremental            (void);

Creates a GSHA incrementally. After creating a GSHA, call gnet_sha_update() one or more times to hash data. Finally, call gnet_sha_final() to compute the final hash value.

Returns : a new GSHA.

gnet_sha_update ()

void                gnet_sha_update                     (GSHA *sha,
                                                         const gchar *buffer,
                                                         guint length);

Updates the hash with buffer. This may be called several times on a hash created by gnet_sha_new_incremental() before being finalized by calling gnet_sha_final().

sha : a GSHA
buffer : buffer to add
length : length of buffer

gnet_sha_final ()

void                gnet_sha_final                      (GSHA *sha);

Calcuates the final hash value of a GSHA. This should only be called on a GSHA created by gnet_sha_new_incremental().

sha : a GSHA

gnet_sha_equal ()

gboolean            gnet_sha_equal                      (gconstpointer p1,
                                                         gconstpointer p2);

Compares two GSHA's for equality.

p1 : a GSHA.
p2 : another GSHA.
Returns : TRUE if they are equal; FALSE otherwise.

gnet_sha_hash ()

guint               gnet_sha_hash                       (gconstpointer p);

Creates a hash code for a GMD5 for use with GHashTable. This hash value is not the same as the MD5 digest.

p : a GSHA
Returns : the hash code for p.

gnet_sha_get_digest ()

gchar*              gnet_sha_get_digest                 (const GSHA *sha);

Gets the raw SHA digest.

sha : a GSHA
Returns : a callee-owned buffer containing the SHA hash digest. The buffer is GNET_SHA_HASH_LENGTH bytes long.

gnet_sha_get_string ()

gchar*              gnet_sha_get_string                 (const GSHA *sha);

Get the digest represented a human-readable string.

sha : a GSHA
Returns : a hexadecimal string representing the digest. The string is 2 * GNET_SHA_HASH_LENGTH bytes long and NULL terminated. The string is caller owned.

gnet_sha_copy_string ()

void                gnet_sha_copy_string                (const GSHA *sha,
                                                         gchar *buffer);

Copies the digest, represented as a string, into buffer. The string is not NULL terminated.

sha : a GSHA
buffer : buffer at least 2 * GNET_SHA_HASH_LENGTH bytes long