## MD5

MD5 — MD5 hash

## Synopsis

    #include <gnet.h>

                        GMD5;
    #define             GNET_MD5_HASH_LENGTH
    GMD5*               gnet_md5_new                        (const gchar *buffer,
                                                             guint length);
    GMD5*               gnet_md5_new_string                 (const gchar *str);
    GMD5*               gnet_md5_clone                      (const GMD5 *md5);
    void                gnet_md5_delete                     (GMD5 *md5);
    GMD5*               gnet_md5_new_incremental            (void);
    void                gnet_md5_update                     (GMD5 *md5,
                                                             const gchar *buffer,
                                                             guint length);
    void                gnet_md5_final                      (GMD5 *md5);
    gboolean            gnet_md5_equal                      (gconstpointer p1,
                                                             gconstpointer p2);
    guint               gnet_md5_hash                       (gconstpointer p);
    gchar*              gnet_md5_get_digest                 (const GMD5 *md5);
    gchar*              gnet_md5_get_string                 (const GMD5 *md5);
    void                gnet_md5_copy_string                (const GMD5 *md5,
                                                             gchar *buffer);

## Description

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

An MD5 can be calculated at one time or incrementally. To create a MD5 at one time, call `gnet_md5_new()` with the data. To create a MD5 incrementally, call `gnet_md5_new_incremental()` to create the MD5 object, then `gnet_md5_update()` one or more times with data to hash, and finally call `gnet_md5_final()`.

To get the digest, or hash value, call `gnet_md5_get_digest()`. This returns the raw digest as an array of `GNET_MD5_HASH_LENGTH` bytes. To get the digest as a human-readable hexidecimal string, call `gnet_md5_get_string()` or `gnet_md5_copy_string()`.

    gchar buffer[] = "Hello world!";
    gchar buffer2[] = "Second line";
    GMD5*  md5;
    gchar* md5_str;

    /* Compute an MD5 at one time */
    md5 = gnet_md5_new (buffer, strlen(buffer));

    md5_str = gnet_md5_get_string (md5);
    g_print ("The MD5 of %s is %s\n", buffer, md5_str);

    /* Use MD5... */

    g_free (md5_str);
    gnet_md5_delete (md5);

    /* Compute an MD5 incrementally */
    md5 = gnet_md5_new_incremental ();
    gnet_md5_update (md5, buffer, strlen(buffer));
    gnet_md5_update (md5, buffer2, strlen(buffer2));
    gnet_md5_final (md5);

    /* Use MD5... */

    gnet_md5_delete (md5);

## Details

### GMD5

    typedef struct _GMD5 GMD5;

GMD5 is a MD5 hash.

### GNET_MD5_HASH_LENGTH

    #define GNET_MD5_HASH_LENGTH	16

Length of the MD5 hash in bytes.

### gnet_md5_new ()

    GMD5*               gnet_md5_new                        (const gchar *buffer,
                                                             guint length);

Creates a GMD5 from `buffer`.

`buffer` : | buffer to hash
`length` : | length of `buffer`
Returns : | a new GMD5.

### gnet_md5_new_string ()

    GMD5*               gnet_md5_new_string                 (const gchar *str);

Creates a GMD5 from `str`. `str` is a hexidecimal string representing the digest.

`str` : | hexidecimal string
Returns : | a new GMD5.

### gnet_md5_clone ()

    GMD5*               gnet_md5_clone                      (const GMD5 *md5);

Copies a GMD5.

`md5` : | a GMD5
Returns : | a copy of `md5`.

### gnet_md5_delete ()

    void                gnet_md5_delete                     (GMD5 *md5);

Deletes a GMD5.

`md5` : | a GMD5

### gnet_md5_new_incremental ()

    GMD5*               gnet_md5_new_incremental            (void);

Creates a GMD5 incrementally. After creating a GMD5, call `gnet_md5_update()` one or more times to hash data. Finally, call `gnet_md5_final()` to compute the final hash value.

Returns : | a new GMD5.

### gnet_md5_update ()

    void                gnet_md5_update                     (GMD5 *md5,
                                                             const gchar *buffer,
                                                             guint length);

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

`md5` : | a GMD5
`buffer` : | buffer to add
`length` : | length of `buffer`

### gnet_md5_final ()

    void                gnet_md5_final                      (GMD5 *md5);

Calcuates the final hash value of a GMD5. This should only be called on an GMD5 created by `gnet_md5_new_incremental()`.

`md5` : | a GMD5

### gnet_md5_equal ()

    gboolean            gnet_md5_equal                      (gconstpointer p1,
                                                             gconstpointer p2);

Compares two GMD5's for equality.

`p1` : | first GMD5.
`p2` : | second GMD5.
Returns : | TRUE if they are equal; FALSE otherwise.

### gnet_md5_hash ()

    guint               gnet_md5_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 GMD5
Returns : | the hash code for `p`.

### gnet_md5_get_digest ()

    gchar*              gnet_md5_get_digest                 (const GMD5 *md5);

Gets the raw MD5 digest.

`md5` : | a GMD5
Returns : | a callee-owned buffer containing the MD5 hash digest. The buffer is `GNET_MD5_HASH_LENGTH` bytes long.

### gnet_md5_get_string ()

    gchar*              gnet_md5_get_string                 (const GMD5 *md5);

Gets the digest represented a human-readable string.

`md5` : | a GMD5
Returns : | a hexadecimal string representing the digest. The string is 2 * `GNET_MD5_HASH_LENGTH` bytes long and NULL terminated. The string is caller owned.

### gnet_md5_copy_string ()

    void                gnet_md5_copy_string                (const GMD5 *md5,
                                                             gchar *buffer);

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

`md5` : | a GMD5
`buffer` : | buffer at least 2 * `GNET_MD5_HASH_LENGTH` bytes long