Update docs for crypto providers

ChangeLog

@@ -1,3 +1,36 @@
+2019-11-05  Jay Berkenbilt  <[email protected]>
+
+	* Add support for pluggable crypto providers, enabling multiple
+	implementations of the cryptographic functions needed by qpdf.
+	This feature was added by request of Red Hat, which recognized the
+	use of qpdf's native crypto implementations as a potential
+	security liability, preferring instead to get all crypto
+	functionality from a third-party library that receives a lot of
+	scrutiny. However it was also important to me to not impose any
+	unnecessary third party depdendencies on my users or packagers,
+	some of which build qpdf for lots of environments, some of which
+	may not easily support gnutls. Starting in qpdf 9.1.0, it is be
+	possible to build qpdf with both the native and gnutls crypto
+	providers or with either in isolation. In support of this feature,
+	new classes QPDFCryptoProvider and QPDFCryptoImpl have been added
+	to the public interface. See QPDFCryptoImpl.hh for details about
+	adding your own crypto provider and QPDFCryptoProvider.hh for
+	details about choosing which one is used. Note that selection of
+	crypto providers is invisible to anyone who doesn't explicitly
+	care. Neither end users nor developers have to be concerned about
+	it.
+
+	* The environment variable QPDF_CRYPTO_PROVIDER can be used to
+	override qpdf's default choice of crypto provider. The
+	--show-crypto flag to the qpdf CLI can be used to present a list
+	of supported crypto providers with the default provider always
+	listed first.
+
+	* Add gnutls crypto provider. Thanks to Zdenek Dohnal for
+	contributing the code that I ultimately used in the gnutls crypto
+	provider and for engaging in an extended discussion about this
+	feature. Fixes #218.
+
 2019-10-22  Jay Berkenbilt  <[email protected]>
 
 	* Incorporate changes from Masamichi Hosoda <[email protected]>

README.md

@@ -31,12 +31,33 @@ QPDF requires a C++ compiler that supports C++-11.
 
 QPDF depends on the external libraries [zlib](http://www.zlib.net/) and [jpeg](http://www.ijg.org/files/). The [libjpeg-turbo](https://libjpeg-turbo.org/) library is also known to work since it is compatible with the regular jpeg library, and QPDF doesn't use any interfaces that aren't present in the straight jpeg8 API. These are part of every Linux distribution and are readily available. Download information appears in the documentation. For Windows, you can download pre-built binary versions of these libraries for some compilers; see [README-windows.md](README-windows.md) for additional details.
 
+If the optional gnutls crypto provider is enabled, then gnutls is also required. This is discussed more in `Crypto providers` below.
+
 # Licensing terms of embedded software
 
-QPDF makes use of zlib and jpeg libraries for its functionality. These packages can be downloaded separately from their own download locations, or they can be downloaded in the external-libs area of the qpdf download site.
+QPDF makes use of zlib and jpeg libraries for its functionality. These packages can be downloaded separately from their own download locations, or they can be downloaded in the external-libs area of the qpdf download site. If the optional gnutls crypto provider is enabled, then gnutls is also required.
 
 Please see the [NOTICE](NOTICE.md) file for information on licenses of embedded software.
 
+# Crypto providers
+
+As of version 9.1.0, qpdf can use different crypto implementations. These can be selected at compile time or at runtime. The native crypto implementations that were used in all versions prior to 9.1.0 are still present and enabled by default.
+
+Initially, the following providers are available:
+* `native`: a native implementation where all the source is embedded in qpdf and no external dependencies are required
+* `gnutls`: an implementation that uses the gnutls library to provide cyrpto; causes libqpdf to link with the gnutls library
+
+The default behavior is for ./configure to discover which other crypto providers can be supported based on available external libraries, to build all available crypto providers, and to use an external provider as the default over the native one. This behavior can be changed with the following flags to ./configure:
+
+* `--enable-crypto-x` -- (where `x` is a supported crypto provider): enable the `x` crypto provider, requiring any external dependencies it needs
+* `--disable-crypto-x` -- disable the `x` provider, and do not link against its dependencies even if they are available
+* `--with-default-crypto=x` -- make `x` the default provider even if a higher priority one is available
+* `--disable-implicit-crypto` -- only build crypto providers that are explicitly requested with an `--enable-crypto-x` option
+
+For example, if you want to guarantee that the gnutls crypto provider is used, you could run ./configure with `--enable-crypto-gnutls --disable-implicit-crypto`.
+
+Please see the section on cyrpto providers in the manual for more details.
+
 # Building from a pristine checkout
 
 When building qpdf from a pristine checkout from version control, generated documentation files are not present. You may either generate them (by passing `--enable-doc-maintenance` to `./configure` and satisfying the extra build-time dependencies) or obtain them from a released source package, which includes them. If you want to grab just the files that are in the source distribution but not in the repository, extract a source distribution in a temporary directory, and run `make CLEAN=1 distfiles.zip`. This will create a file called `distfiles.zip`, which can you can extract in a checkout of the source repository. This step is optional unless you are running make install and want the html and PDF versions of the documentation to be installed.
@@ -59,7 +80,7 @@ QPDF is known to build and pass its test suite with mingw (latest version tested
 
 # Additional Notes on Build
 
-QPDF's build system, inspired by [abuild](http://www.abuild.org), can optionally use its own built-in rules rather than using libtool and obeying the compiler specified with configure.  This can be enabled by passing `--with-buildrules=buildrules` where buildrules corresponds to one of the `.mk` files (other than `rules.mk`) in the make directory. This should never be necessary on a UNIX system, but may be necessary on a Windows system.  See [README-windows.md](README-windows.md) for details.
+QPDF's build system, inspired by [abuild](http://www.qbilt.org/abuild), can optionally use its own built-in rules rather than using libtool and obeying the compiler specified with configure.  This can be enabled by passing `--with-buildrules=buildrules` where buildrules corresponds to one of the `.mk` files (other than `rules.mk`) in the make directory. This should never be necessary on a UNIX system, but may be necessary on a Windows system.  See [README-windows.md](README-windows.md) for details.
 
 The QPDF package provides some executables and a software library.  A user manual can be found in the "doc" directory.  The docbook sources to the user manual can be found in the `manual` directory.
 

TODO

@@ -272,10 +272,13 @@ I find it useful to make reference to them in this list
    to add any dependencies on threading libraries.
 
  * Study what's required to support savable forms that can be saved by
-   Adobe Reader.  Does this require actually signing the document with
-   an Adobe private key?  Search for "Digital signatures" in the PDF
+   Adobe Reader. Does this require actually signing the document with
+   an Adobe private key? Search for "Digital signatures" in the PDF
    spec, and look at ~/Q/pdf-collection/form-with-full-save.pdf, which
-   came from Adobe's example site.
+   came from Adobe's example site. See also
+   ../misc/digital-sign-from-trueroad/. If digital signatures are
+   implemented, update the docs on crytpo providers, which mention
+   that this may happen in the future.
 
  * See if we can avoid preserving unreferenced objects in object
    streams even when preserving the object streams.