Doc fixes.

README.rst

@@ -35,6 +35,8 @@ import gcrypt [from "path"] ;
   BLOB <OBJ>.encrypt(BLOB plaintext [, BLOB iv] [, BLOB ctr])
   BLOB <OBJ>.decrypt(BLOB ciphertext [, BLOB iv] [, BLOB ctr])
 
+  BLOB gcrypt.fileread(STRING path)
+
   BLOB gcrypt.random([ENUM quality] [, BYTES n])
   INT gcrypt.random_int(ENUM quality [, INT bound])
 
@@ -77,24 +79,11 @@ This is a simple usage example::
       # child process, as explained below.
       gcrypt.init(FINISH);
 
-      # Use the blobcode VMOD to create an object that stores a BLOB
-      # derived from this hex encoding, to be used as the cryptographic
-      # key. You must ensure that keys and other cryptographic
-      # elements have the right sizes -- in this case, a 128 bit key
-      # for the AES-128 cipher.
-      # NOTE: The keys used in this manual's examples are chosen to
-      # make the key lengths easy to recognize. DO NOT copy them
-      # into production VCL!
-      new k = blobcode.blob(HEX, "000102030405060708090a0b0c0d0e0f");
-
       # Create an object for AES-128 in CTR mode using the key just
       # created, and with libgcrypt internal structures in secure memory.
-      new aes = gcrypt.symmetric(AES, CTR, key=k.get(), secure=true);
-
-      # Wipe the BLOB from which the key was read (overwrite the
-      # memory region with all zeroes), so that it is not stored in
-      # any non-secure memory.
-      gcrypt.wipe(key.get());
+      # The key is read from the given file.
+      new aes = gcrypt.symmetric(AES, CTR, secure=true,
+                                 key=gcrypt.fileread("/path/to/key"));
   }
 
   # Assume that a plaintext to be encrypted is in the response
@@ -361,11 +350,12 @@ Examples::
   # Assume in the following that initialization has been finalized.
 
   sub vcl_init {
-      # Create some BLOBs for the cryptographic keys, whose lengths
-      # are 16, 24 and 32 bytes for AES-128, -192 and -256,
-      # respectively.
-      # As emphasized above, DON'T copy these keys into production
-      # VCL!
+      # Use the blobcode VMOD to create some BLOBs for the cryptographic
+      # keys, whose lengths are 16, 24 and 32 bytes for AES-128, -192
+      # and -256, respectively.
+      # NOTE: The keys used in this manual's examples are chosen to
+      # make the key lengths easy to recognize. DO NOT copy them
+      # into production VCL!
       new k128 = blobcode.blob(HEX, "000102030405060708090a0b0c0d0e0f");
       new k192 = blobcode.blob(HEX,
                     "000102030405060708090a0b0c0d0e0f1011121314151617");
@@ -916,7 +906,7 @@ Therefore, if you are working with sensitive data, consider the
 following measures:
 
 * Test your Varnish deployment thoroughly with test data, until you
-  are confident that it does not to swap or dump core.
+  are confident that it does not swap or dump core.
 
 * Then in production, use the means of your operating system to ensure
   that the Varnish child process does not swap or write core files.
@@ -924,7 +914,10 @@ following measures:
 * Examine any other VMODs that you use to ensure that they do not leak
   data from workspaces.
 
-* Ensure that VCL sources are only readable by the Varnish child
+* Consider using the ``fileread()`` function to read sensitive data
+  such as cryptographic keys from files that are only readable by the
+  Varnish worker process. If you must expose sensitive data in VCL
+  sources, ensure that those sources are only readable by the worker
   process.
 
 * If you are using file storage for the cache, ensure that the cache
@@ -979,6 +972,7 @@ SEE ALSO
 * varnishd(1)
 * vcl(7)
 * varnishlog(1)
+* vmod_std(3)
 * mlock(2)
 * pthread_key_create(3)
 * libgcrypt: https://gnupg.org/software/libgcrypt/index.html

src/vmod_gcrypt.vcc

@@ -18,6 +18,8 @@ $Module gcrypt 3 access the libgcrypt cryptographic library
   BLOB <OBJ>.encrypt(BLOB plaintext [, BLOB iv] [, BLOB ctr])
   BLOB <OBJ>.decrypt(BLOB ciphertext [, BLOB iv] [, BLOB ctr])
 
+  BLOB gcrypt.fileread(STRING path)
+
   BLOB gcrypt.random([ENUM quality] [, BYTES n])
   INT gcrypt.random_int(ENUM quality [, INT bound])
 
@@ -60,24 +62,11 @@ This is a simple usage example::
       # child process, as explained below.
       gcrypt.init(FINISH);
 
-      # Use the blobcode VMOD to create an object that stores a BLOB
-      # derived from this hex encoding, to be used as the cryptographic
-      # key. You must ensure that keys and other cryptographic
-      # elements have the right sizes -- in this case, a 128 bit key
-      # for the AES-128 cipher.
-      # NOTE: The keys used in this manual's examples are chosen to
-      # make the key lengths easy to recognize. DO NOT copy them
-      # into production VCL!
-      new k = blobcode.blob(HEX, "000102030405060708090a0b0c0d0e0f");
-
       # Create an object for AES-128 in CTR mode using the key just
       # created, and with libgcrypt internal structures in secure memory.
-      new aes = gcrypt.symmetric(AES, CTR, key=k.get(), secure=true);
-
-      # Wipe the BLOB from which the key was read (overwrite the
-      # memory region with all zeroes), so that it is not stored in
-      # any non-secure memory.
-      gcrypt.wipe(key.get());
+      # The key is read from the given file.
+      new aes = gcrypt.symmetric(AES, CTR, secure=true,
+                                 key=gcrypt.fileread("/path/to/key"));
   }
 
   # Assume that a plaintext to be encrypted is in the response
@@ -321,11 +310,12 @@ Examples::
   # Assume in the following that initialization has been finalized.
 
   sub vcl_init {
-      # Create some BLOBs for the cryptographic keys, whose lengths
-      # are 16, 24 and 32 bytes for AES-128, -192 and -256,
-      # respectively.
-      # As emphasized above, DON'T copy these keys into production
-      # VCL!
+      # Use the blobcode VMOD to create some BLOBs for the cryptographic
+      # keys, whose lengths are 16, 24 and 32 bytes for AES-128, -192
+      # and -256, respectively.
+      # NOTE: The keys used in this manual's examples are chosen to
+      # make the key lengths easy to recognize. DO NOT copy them
+      # into production VCL!
       new k128 = blobcode.blob(HEX, "000102030405060708090a0b0c0d0e0f");
       new k192 = blobcode.blob(HEX,
                     "000102030405060708090a0b0c0d0e0f1011121314151617");
@@ -821,7 +811,7 @@ Therefore, if you are working with sensitive data, consider the
 following measures:
 
 * Test your Varnish deployment thoroughly with test data, until you
-  are confident that it does not to swap or dump core.
+  are confident that it does not swap or dump core.
 
 * Then in production, use the means of your operating system to ensure
   that the Varnish child process does not swap or write core files.
@@ -829,7 +819,10 @@ following measures:
 * Examine any other VMODs that you use to ensure that they do not leak
   data from workspaces.
 
-* Ensure that VCL sources are only readable by the Varnish child
+* Consider using the ``fileread()`` function to read sensitive data
+  such as cryptographic keys from files that are only readable by the
+  Varnish worker process. If you must expose sensitive data in VCL
+  sources, ensure that those sources are only readable by the worker
   process.
 
 * If you are using file storage for the cache, ensure that the cache
@@ -884,6 +877,7 @@ SEE ALSO
 * varnishd(1)
 * vcl(7)
 * varnishlog(1)
+* vmod_std(3)
 * mlock(2)
 * pthread_key_create(3)
 * libgcrypt: https://gnupg.org/software/libgcrypt/index.html