cryptmount usage of the OpenSSL cryptographic library

			RW Penney, July 2007

Introduction
============

Since the earliest versions of cryptmount, the package has benefited enormously from the availability of the OpenSSL cryptographic library. This library has provided a secure means of storing filesystem access keys. Moreover, this has provided compatibility with the 'openssl' command-line tool, allowing cryptmount keys to be manipulated outside cryptmount.

Since mid-2006, cryptmount has added support for access-keys protected via the GNU/libgcrypt library, and more recently has directly incorporated implementations of the Blowfish & SHA1 cryptographic algorithms.

Despite the power offered by the OpenSSL library, the licencing position of cryptmount is made more complicated by using the OpenSSL library within an application released under the GNU General Public License (GPL2). Although the advice published at http://www.openssl.org/support/faq.html#LEGAL2 recognizes this as accepted "on many systems including the major Linux and BSD distributions", this position is open to disagreement.

In order to clarify the licencing position of cryptmount, a decision has been taken to REMOVE SUPPORT FOR USING THE OpenSSL LIBRARY from cryptmount-3.0 and subsequent releases. Naturally, this decision has been taken with regret, while greatly respecting the considerable role the OpenSSL library has played in cryptmount's evolution.


Migration plans
===============

In order to minimize the impact of removing support for the OpenSSL library, additional functionality is being added elsewhere within cryptmount starting with release 2.1:

  * Support for OpenSSL file-formats via the libgcrypt library

  * A new '--reuse-key' option for translating between key-formats

It is expected that the OpenSSL compatibility layer provided via the libgcrypt library will allow the majority of cryptmount users who are already using OpenSSL key-files to migrate transparently to using libgcrypt in place of the OpenSSL library. There are, however, some differences between the functionality offered by these two libraries that may cause difficulties for a small minority of users who have chosen certain cipher/digest options within OpenSSL.

In cases where it is necessary to change from an existing OpenSSL key-file to another key-format supported by cryptmount without recreating the associated encrypted filesystem, the '--reuse-key' option can be used by the system-administrator to preserve the same access key, but within a different file-format.
In outline, for an existing crypmount target called 'OLD_TARGET', this will involve the following steps:
  - Ensuring you have available a version of cryptmount (e.g. 2.1, 2.2)
    which supports all the keyformats used by your existing
    encrypted filesystems
  - Creating a new cryptmount target in the cmtab, using the same parameters
    as OLD_TARGET, but with a different target-name ('NEW_TARGET'),
    a new key-filename & different keyformat (e.g. 'libgcrypt')
  - Using 'cryptmount --reuse-key OLD_TARGET NEW_TARGET'
    to migrate the key from OLD_TARGET to NEW_TARGET
  - Confirming that 'cryptmount NEW_TARGET' allows the old filesystem
    to be mounted correctly
  - Removing the OLD_TARGET entry within the cmtab

A third option involves using the command-line 'openssl' program to extract an existing access-key and then re-encrypt it, again using 'openssl', to use a cipher & message-digest (e.g. aes-256-cbc & sha1) that are suppored by cryptmount's libgcrypt compatibility layer.


OpenSSL key-format support via libgcrypt
========================================

If cryptmount is configured with the '--with-libgcrypt' option, a compatibility layer is provided for reading keys stored within files created by the OpenSSL library and 'openssl' command-line application. This compatibility-layer can be associated with any cryptmount filesystem by using 'keyformat=openssl-compat' as part of the filesystem's entry within the cmtab (see 'man 5 cmtab').

The following cipher & digest algorithm options within OpenSSL are known to work transparently with this compatibility layer:
    aes128, aes-128-cbc, aes192, aes192-cbc, aes-192-ecb, aes256, aes-256-cbc
    bf, bf-cbc, blowfish
    cast, cast5
    des
    md4, md5, sha1, rmd160

The following cipher & digest algorithm options within OpenSSL are known to cause problems with the compatibility layer:
    *-cfb			(Ciphers operated in cipher-feedback mode
    				do not appear to operate consistently.)
    rc2 rc2-* rc4 rc4-*		(These ciphers are not supported by libgcrypt)
    md2				(This digest is not supported by libgcrypt)
    sha				(This digest is not supported by libgcrypt)