Commit e237e453 authored by Geoff Simmons's avatar Geoff Simmons

Doc fixes.

parent 0883a37d
Pipeline #233 skipped
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment