## 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