add more documentation (WIP)

README.rst

@@ -24,6 +24,45 @@ SYNOPSIS
 import blobdigest [from "path"] ;
 
 
+::
+
+  BLOB blobdigest.hash(ENUM hash, BLOB msg)
+
+  new OBJECT = blobdigest.hmac(ENUM hash, BLOB key)
+  BLOB <obj>.hmac(BLOB msg)
+
+DESCRIPTION
+===========
+
+This Varnish Module (VMOD) generates message digests and keyed-hash
+message authentication codes (HMACs) using the VCL data type BLOB,
+which may contain arbitrary data of any length.
+
+Currently (in Varnish versions through 5.0), BLOBs may only be used in
+VCL as arguments of VMOD functions, so this VMOD must be used in
+combination with other VMODs. For example, the blobcode VMOD (see `SEE
+ALSO`_) may be used to convert BLOBs using binary-to-text encodings,
+to initialize data for this VMOD and to save its results. The
+advantage of using BLOBs is that operations on the data are separated
+from issues such as encoding.
+
+HASH ALGORITHMS
+===============
+
+The ``hash`` enum in the following can have one of the following
+values:
+
+* ``MD5``
+* ``SHA1``
+* ``SHA224``
+* ``SHA256``
+* ``SHA384``
+* ``SHA512``
+* ``SHA3_224``
+* ``SHA3_256``
+* ``SHA3_384``
+* ``SHA3_512``
+
 CONTENTS
 ========
 
@@ -32,6 +71,28 @@ CONTENTS
 * BLOB hmac.hmac(BLOB)
 * STRING version()
 
+.. _func_hash:
+
+BLOB hash(ENUM, BLOB)
+---------------------
+
+Prototype
+	BLOB hash(ENUM hash, BLOB msg)
+
+Returns the message digest for ``msg`` as specified by ``hash``.
+
+Example::
+
+	import blobdigest;
+	import blobcode;
+
+	# Decode the base64-encoded string, generate its SHA256 hash,
+	# and save the hex-encoded result in a header.
+	set req.http.SHA256
+	    = blobcode.encode(HEXUC,
+	                      blobdigest.hash(SHA256,
+			                      blobcode.decode(BASE64, "Zm9v"));
+
 .. _obj_hmac:
 
 Object hmac
@@ -41,13 +102,20 @@ Object hmac
 Prototype
 	new OBJ = blobdigest.hmac(ENUM hash, BLOB key)
 
-Description
-	Creates an object that generates HMACs based on the
-	digest algorithm ``hash`` and the given ``key``.
+Creates an object that generates HMACs based on the digest algorithm
+``hash`` and the given ``key``.
+
+Example::
 
-Example
-	``new key = blobcode.blob(BASE64, "a2V5");``
-	``new hmac = blobdigest.hmac(SHA256, key.get());``
+	import blobdigest;
+	import blobcode;
+
+	# Create a key from the base64-encoded string, and use
+	# the result to initialize an hmac object.
+	sub vcl_init {
+		new key = blobcode.blob(BASE64, "a2V5");
+		new hmac = blobdigest.hmac(SHA256, key.get());
+	}
 
 .. _func_hmac.hmac:
 
@@ -57,20 +125,22 @@ BLOB hmac.hmac(BLOB)
 Prototype
 	BLOB hmac.hmac(BLOB msg)
 
-Description
-	Returns the HMAC for ``msg`` based on the key and
-	hash algorithm provided in the constructor.
+Returns the HMAC for ``msg`` based on the key and hash algorithm
+provided in the constructor.
 
-Example
-	``set req.http.hmac = hmac.hmac(blobcode.decode(BASE64, "Zm9v"));``
+Example::
 
-.. _func_hash:
+	# Import a VMOD that tests BLOBs for equality
+	import blob;
 
-BLOB hash(ENUM, BLOB)
----------------------
-
-Prototype
-	BLOB hash(ENUM hash, BLOB msg)
+	# Check if request header HMAC matches the HMAC for
+	# the hex-encoded data in request header Msg.
+	# Respond with 401 Not Authorized if the HMAC doesn't check.
+	sub vcl_recv {
+	    if (!blob.equal(blobcode.decode(SHA256, req.http.HMAC),
+	                    hmac.hmac(blobcode.decode(HEX, req.http.Msg)))) {
+		return(synth(401));
+	}
 
 .. _func_version:
 
@@ -80,8 +150,24 @@ STRING version()
 Prototype
 	STRING version()
 
-Description
-	Returns the version string for this VMOD.
+Returns the version string for this VMOD.
+
+Example::
+
+	std.log("Using VMOD blobdigest version " + blobdigest.version());
+
+REQUIREMENTS
+============
+
+This VMOD requires at least Varnish version 4.1, and has been tested
+against versions through 5.0.0.
+
+Perl 5 is required for the build.
+
+SEE ALSO
+========
 
-Example
-	``std.log("Using VMOD blobdigest version " + blobdigest.version());``
+* varnishd(1)
+* vcl(7)
+* VMOD blobcode: https://code.uplex.de/uplex-varnish/libvmod-blobcode
+* VMOD blob: https://code.uplex.de/uplex-varnish/libvmod-blob

src/vmod_blobdigest.vcc

@@ -9,36 +9,122 @@
 
 $Module blobdigest 3 digests and hmacs for the VCL blob type
 
+::
+
+  BLOB blobdigest.hash(ENUM hash, BLOB msg)
+
+  new OBJECT = blobdigest.hmac(ENUM hash, BLOB key)
+  BLOB <obj>.hmac(BLOB msg)
+
+DESCRIPTION
+===========
+
+This Varnish Module (VMOD) generates message digests and keyed-hash
+message authentication codes (HMACs) using the VCL data type BLOB,
+which may contain arbitrary data of any length.
+
+Currently (in Varnish versions through 5.0), BLOBs may only be used in
+VCL as arguments of VMOD functions, so this VMOD must be used in
+combination with other VMODs. For example, the blobcode VMOD (see `SEE
+ALSO`_) may be used to convert BLOBs using binary-to-text encodings,
+to initialize data for this VMOD and to save its results. The
+advantage of using BLOBs is that operations on the data are separated
+from issues such as encoding.
+
+HASH ALGORITHMS
+===============
+
+The ``hash`` enum in the following can have one of the following
+values:
+
+* ``MD5``
+* ``SHA1``
+* ``SHA224``
+* ``SHA256``
+* ``SHA384``
+* ``SHA512``
+* ``SHA3_224``
+* ``SHA3_256``
+* ``SHA3_384``
+* ``SHA3_512``
+
+$Function BLOB hash(ENUM {MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3_224,
+                          SHA3_256, SHA3_384, SHA3_512} hash, BLOB msg)
+
+Returns the message digest for ``msg`` as specified by ``hash``.
+
+Example::
+
+	import blobdigest;
+	import blobcode;
+
+	# Decode the base64-encoded string, generate its SHA256 hash,
+	# and save the hex-encoded result in a header.
+	set req.http.SHA256
+	    = blobcode.encode(HEXUC,
+	                      blobdigest.hash(SHA256,
+			                      blobcode.decode(BASE64, "Zm9v"));
+
 $Object hmac(ENUM {MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3_224,
                    SHA3_256, SHA3_384, SHA3_512} hash, BLOB key)
 
 Prototype
 	new OBJ = blobdigest.hmac(ENUM hash, BLOB key)
 
-Description
-	Creates an object that generates HMACs based on the
-	digest algorithm ``hash`` and the given ``key``.
+Creates an object that generates HMACs based on the digest algorithm
+``hash`` and the given ``key``.
+
+Example::
+
+	import blobdigest;
+	import blobcode;
 
-Example
-	``new key = blobcode.blob(BASE64, "a2V5");``
-	``new hmac = blobdigest.hmac(SHA256, key.get());``
+	# Create a key from the base64-encoded string, and use
+	# the result to initialize an hmac object.
+	sub vcl_init {
+		new key = blobcode.blob(BASE64, "a2V5");
+		new hmac = blobdigest.hmac(SHA256, key.get());
+	}
 
 $Method BLOB .hmac(BLOB msg)
 
-Description
-	Returns the HMAC for ``msg`` based on the key and
-	hash algorithm provided in the constructor.
+Returns the HMAC for ``msg`` based on the key and hash algorithm
+provided in the constructor.
 
-Example
-	``set req.http.hmac = hmac.hmac(blobcode.decode(BASE64, "Zm9v"));``
+Example::
 
-$Function BLOB hash(ENUM {MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3_224,
-                          SHA3_256, SHA3_384, SHA3_512} hash, BLOB msg)
+	# Import a VMOD that tests BLOBs for equality
+	import blob;
+
+	# Check if request header HMAC matches the HMAC for
+	# the hex-encoded data in request header Msg.
+	# Respond with 401 Not Authorized if the HMAC doesn't check.
+	sub vcl_recv {
+	    if (!blob.equal(blobcode.decode(SHA256, req.http.HMAC),
+	                    hmac.hmac(blobcode.decode(HEX, req.http.Msg)))) {
+		return(synth(401));
+	}
 
 $Function STRING version()
 
-Description
-	Returns the version string for this VMOD.
+Returns the version string for this VMOD.
+
+Example::
+
+	std.log("Using VMOD blobdigest version " + blobdigest.version());
+
+REQUIREMENTS
+============
+
+This VMOD requires at least Varnish version 4.1, and has been tested
+against versions through 5.0.0.
+
+Perl 5 is required for the build.
+
+SEE ALSO
+========
 
-Example
-	``std.log("Using VMOD blobdigest version " + blobdigest.version());``
+* varnishd(1)
+* vcl(7)
+* VMOD blobcode: https://code.uplex.de/uplex-varnish/libvmod-blobcode
+* VMOD blob: https://code.uplex.de/uplex-varnish/libvmod-blob