[glib/glib-2-30] GHashTable: Add a note about hash collisions

[Matthias Clasen <matthiasc src gnome org>]

commit 1b7050d6a3e47bebaec005b1960ca7cae07b4122
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jan 24 21:11:13 2012 -0500

    GHashTable: Add a note about hash collisions

 glib/ghash.c |   25 +++++++++++++++++++------
 1 files changed, 19 insertions(+), 6 deletions(-)
---
diff --git a/glib/ghash.c b/glib/ghash.c
index 02c0d7b..0ea372e 100644
--- a/glib/ghash.c
+++ b/glib/ghash.c
@@ -145,12 +145,25 @@
  * hash functions which can be used when the key is a #gpointer, #gint,
  * and #gchar* respectively.
  *
- * <!-- FIXME: Need more here. --> The hash values should be evenly
- * distributed over a fairly large range? The modulus is taken with the
- * hash table size (a prime number) to find the 'bucket' to place each
- * key into. The function should also be very fast, since it is called
- * for each key lookup.
- **/
+ * g_direct_hash() is also the appropriate hash function for keys
+ * of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros).
+ *
+ * <!-- FIXME: Need more here. --> A good hash functions should produce
+ * hash values that are evenly distributed over a fairly large range.
+ * The modulus is taken with the hash table size (a prime number) to
+ * find the 'bucket' to place each key into. The function should also
+ * be very fast, since it is called for each key lookup.
+ *
+ * Note that the hash functions provided by GLib have these qualities,
+ * but are not particularly robust against manufactured keys that
+ * cause hash collisions. Therefore, you should consider choosing
+ * a more secure hash function when using a GHashTable with keys
+ * that originate in untrusted data (such as HTTP requests).
+ * Using g_str_hash() in that situation might make your application
+ * vulerable to <ulink url="https://lwn.net/Articles/474912/";>Algorithmic Complexity Attacks</ulink>.
+ *
+ * Returns: the hash value corresponding to the key
+ */
 
 /**
  * GHFunc: