Various doc fixes.

README.rst

@@ -94,11 +94,11 @@ This is a simple usage example::
   # header X-Msg. Assign the hex-encoded encrypted message to the
   # response header X-Cipher, and the hex-encoded counter vector to
   # the response header X-Ctr; and remove X-Msg from the response.
-  sub vcl_recv {
-      # Use the blobcode VMOD to decode to convert the contents of
-      # X-Msg to a BLOB, and to encode the encrypted ciphertext in
-      # hex with lower-case digits. Use the random() function to
-      # generate a counter vector as a 128 bit nonce.
+  sub vcl_deliver {
+      # Use the blobcode VMOD to convert the contents of X-Msg to a
+      # BLOB, and to encode the encrypted ciphertext in hex with
+      # lower-case digits. Use the random() function to generate a
+      # counter vector as a 128 bit nonce.
       set resp.http.X-Cipher
           = blobcode.encode(HEXLC,
               aes.encrypt(blobcode.decode(encoded=req.http.X-Msg),
@@ -133,11 +133,11 @@ Varnish:
   are lowered when secure memory is initialized. This applies to the
   varnishd child process.
 
-The use of secure memory is disabled by default. With the VMOD, you
-can specify the use of secure memory by setting the ``secure`` flag to
-``true`` in a constructor for symmetric encryption, and configure the
-size of the pool, or disable secure memory, using the ``init()``
-function, as described below.
+The use of secure memory is turned off by default for the creation of
+new objects. With the VMOD, you can specify the use of secure memory
+by setting the ``secure`` flag to ``true`` in a constructor for
+symmetric encryption, and configure the size of the pool, or disable
+secure memory, using the ``init()`` function, as described below.
 
 libgcrypt logging
 -----------------
@@ -340,7 +340,8 @@ of the VCL load with an error message, under these conditions:
   disabled.
 
 * Any failure of the libgcrypt library to initialize internal
-  structures to be used for this object.
+  structures to be used for this object. This happens, for example, if
+  the key length is to short for the chosen cipher.
 
 Examples::
 
@@ -579,12 +580,12 @@ Example::
 
   sub vcl_resp {
       # The length of the IV MUST match the block size of the
-      # cipher in use -- 64 bits (8 bytes) for AES. For CBC, the IV
+      # cipher in use -- 128 bits (16 bytes) for AES. For CBC, the IV
       # MUST be unpredictable, so we use quality level STRONG.
       set resp.http.X-Encrypted
           = blobcode.encode(BASE64,
               aes192.encrypt(blobcode.decode(encoded=resp.http.X-Msg),
-                             iv=gcrypt.random(STRONG, 8B)));
+                             iv=gcrypt.random(STRONG, 16B)));
 
       # Now call random() with no arguments to retrive the IV that
       # was generated, to be sent in the base64-encoded response
@@ -792,9 +793,16 @@ the following points, but this list is by no means exhaustive:
   never be re-used with the same encryption key. For CBC mode, the IV
   must also be unpredictable; for example, the ``STRONG`` quality
   level should be used if the ``random()`` function is used to
-  generate IVs for CFB. For the other modes, unpredictability is not
+  generate IVs for CBC. For the other modes, unpredictability is not
   required, and the ``NONCE`` level is sufficient.
 
+* libgcrypt permits certain operations that are poor practice, such as
+  setting an init vector whose length is not equal to the block length
+  of a symmetric cipher, but emits a warning message. The VMOD follows
+  the library in allowing these operations to proceed, but you should
+  check the Varnish log for the warnings, and correct any such
+  problems.
+
 * Make sure that you have a secure procedure in place for generating
   and storing cryptographic keys, and for changing the keys
   periodically.

src/vmod_gcrypt.vcc

@@ -77,11 +77,11 @@ This is a simple usage example::
   # header X-Msg. Assign the hex-encoded encrypted message to the
   # response header X-Cipher, and the hex-encoded counter vector to
   # the response header X-Ctr; and remove X-Msg from the response.
-  sub vcl_recv {
-      # Use the blobcode VMOD to decode to convert the contents of
-      # X-Msg to a BLOB, and to encode the encrypted ciphertext in
-      # hex with lower-case digits. Use the random() function to
-      # generate a counter vector as a 128 bit nonce.
+  sub vcl_deliver {
+      # Use the blobcode VMOD to convert the contents of X-Msg to a
+      # BLOB, and to encode the encrypted ciphertext in hex with
+      # lower-case digits. Use the random() function to generate a
+      # counter vector as a 128 bit nonce.
       set resp.http.X-Cipher
           = blobcode.encode(HEXLC,
               aes.encrypt(blobcode.decode(encoded=req.http.X-Msg),
@@ -116,11 +116,11 @@ Varnish:
   are lowered when secure memory is initialized. This applies to the
   varnishd child process.
 
-The use of secure memory is disabled by default. With the VMOD, you
-can specify the use of secure memory by setting the ``secure`` flag to
-``true`` in a constructor for symmetric encryption, and configure the
-size of the pool, or disable secure memory, using the ``init()``
-function, as described below.
+The use of secure memory is turned off by default for the creation of
+new objects. With the VMOD, you can specify the use of secure memory
+by setting the ``secure`` flag to ``true`` in a constructor for
+symmetric encryption, and configure the size of the pool, or disable
+secure memory, using the ``init()`` function, as described below.
 
 libgcrypt logging
 -----------------
@@ -303,7 +303,8 @@ of the VCL load with an error message, under these conditions:
   disabled.
 
 * Any failure of the libgcrypt library to initialize internal
-  structures to be used for this object.
+  structures to be used for this object. This happens, for example, if
+  the key length is to short for the chosen cipher.
 
 Examples::
 
@@ -522,12 +523,12 @@ Example::
 
   sub vcl_resp {
       # The length of the IV MUST match the block size of the
-      # cipher in use -- 64 bits (8 bytes) for AES. For CBC, the IV
+      # cipher in use -- 128 bits (16 bytes) for AES. For CBC, the IV
       # MUST be unpredictable, so we use quality level STRONG.
       set resp.http.X-Encrypted
           = blobcode.encode(BASE64,
               aes192.encrypt(blobcode.decode(encoded=resp.http.X-Msg),
-                             iv=gcrypt.random(STRONG, 8B)));
+                             iv=gcrypt.random(STRONG, 16B)));
 
       # Now call random() with no arguments to retrive the IV that
       # was generated, to be sent in the base64-encoded response
@@ -721,9 +722,16 @@ the following points, but this list is by no means exhaustive:
   never be re-used with the same encryption key. For CBC mode, the IV
   must also be unpredictable; for example, the ``STRONG`` quality
   level should be used if the ``random()`` function is used to
-  generate IVs for CFB. For the other modes, unpredictability is not
+  generate IVs for CBC. For the other modes, unpredictability is not
   required, and the ``NONCE`` level is sufficient.
 
+* libgcrypt permits certain operations that are poor practice, such as
+  setting an init vector whose length is not equal to the block length
+  of a symmetric cipher, but emits a warning message. The VMOD follows
+  the library in allowing these operations to proceed, but you should
+  check the Varnish log for the warnings, and correct any such
+  problems.
+
 * Make sure that you have a secure procedure in place for generating
   and storing cryptographic keys, and for changing the keys
   periodically.