CYPHERTITE(1)

NAME
cyphertite - remote encrypting archiving client

SYNOPSIS
cyphertite -ctxV [-0PRXpr] [-B ctfile] [-C tmpdir] [-D debugstring] [-E excludefile] [-F conffile] [-I includefile] [-f ctfile] [file ...]

cyphertite -m -cetx [-r] [-C tmpdir] [-D debugstring] [-F conffile] [-f metadata-tag] [pattern]

DESCRIPTION
The cyphertite command creates, lists, or extracts files using an archive metadata file commonly known as a ctfile and remotely stored blocks of data, called “chunks”. A “chunk” is defined as a portion of a file on disk that is up to 256 KB in size. (A file that is larger than 256 KB would be split into several 256 KB chunks and one chunk that might be less than 256 KB.)

The interface is designed to be familiar to users of tar while providing a number of additional features:

DEDUPLICATION

Through the process of DEDUPLICATION, cyphertite chunks are stored only once and subsequent instances of the same data are stored as references to the existing data. Files (called "archive metadata files") reference the chunks needed to retrieve any archived file. Each chunk is identified by its SHA1 hash. Many archive metadata files may reference the same chunk.

COMPRESSION

After files are split into chunks, those chunks are then compressed. The default compression algorithm is LZO because it is the fastest of the 3 algorithms available, but LZW or LZMA can be configured in cyphertite.conf(5). If a chunk increases in size on compression, the uncompressed chunk is used.

ENCRYPTION

cyphertite encrypts each chunk after compression. The encryption algorithm used is 256-bit AES-XTS with a variation on the usual disk encryption method suggested in IEEE 1619-2007: the 256-bit tweak key, K2, is normally taken as the sector number on a hard drive, here it is generated as an HMAC SHA1 of the chunk itself using a separate 256-bit key.

All locally stored metadata is unencrypted. Metadata stored on a remote machine is encrypted using standard AES-XTS, with the chunk number used as the tweak key.

Network traffic is encrypted using per-user certificates signed by a 521-bit ECDSA CA key and a corresponding per-user 521-bit ECDSA key. These certificates and keys are used to setup a 256-bit AES session key for SSL. The relevant client certificates and key are provided by the remote server administrator.

The keys used to perform all the chunk-level encryption are stored in the crypto_secrets file specified in cyphertite.conf(5). The file ~/.cyphertite/ct_crypto is the default. The AES-XTS and IV keys are stored protected by PBKDF2 with a default of 256,000 rounds and a 128-byte salt. The password to unlock the AES-XTS and IV keys is specified as crypto_password in cyphertite.conf(5).

REALM DEDUPLICATION

If multiple machines share cyphertite.conf(5) and ct_crypto files in common, deduplication can be achieved across several machines in a realm. These machines must share an account to obtain the benefit of deduplication.

In all cases except those involving metadata ( -m ), the path to the archive metadata file is required:

-f ctfile
    Filename where the archive metadata is stored. For list and extract commands this is the existing archive metadata file to extract from. For create commands it is the archive metadata file to create. There are limitations placed on the ctfile in terms of length (128 bytes) and that it may not include certain special characters, e.g. ?, *, !, \, / etc.

One of the following flags must be present:

-c  Create new archive or overwrite an existing archive metadata file.

-t  List contents of an archive. If any files are named on the command line, only those files will be listed. The file arguments may be specified as glob(7) patterns (or, with the -r option, regex(3) patterns) and cyphertite will list all archive members that match that pattern.

-x  Extract files from archive. If any files are named on the command line, only those files will be extracted from the archive. The file arguments may be specified as glob(7) patterns (or, with the -r option, regex(3) patterns) and cyphertite will extract all archive members that match that pattern.

In addition to the flags mentioned above, the following flags may be used:

-0  Generate a level 0 (full) backup. Only applicable to remote metadata archive mode.

-B ctfile
    Specify the archive to be used as the basis of a differential backup. Files with a modification time (mtime) newer than the previous backup will be archived. The behavior is dump-like and helps limit the size of the archive metadata file and the backup window.

-C directory
    Set the current working directory. When extracting, files will be extracted into the specified directory; when creating, the specified files will be matched from the directory.

-D debugstring
    Run in debug mode. debugstring is a comma delimited list of the following types:

    socket
        low level socket routines.
    config
        configuration parsing.
    exude
        memory debugging.
    net network.
    trans
        transactions.
    sha deduplication has calculations.
    ctfile
        generation and reading of ctfiles.
    db  Local database.
    crypto
        Cryptographical transforms and key calculations.
    file
        Filesystem access.
    xml xml messages to the server.
    vertree
        version tree calculations.
    all All of the above.

-E pattern_file
    Specify the location of a file containing a list of patterns to be ignored in list, archive and extract modes. The patterns, one per line are interpreted as glob patterns unless the -r flag is specified.

-F config
    Specify the location of the configuration file to use, overriding the default values.

-I pattern_file
    Specify the location of a file containing a list of patterns to included in list, archive and extract modes. In list and extract modes it is allowed to specify a list of patterns on the command line or this option, not both. The file is interpreted as for the -E option.

-P  Do not strip leading slashes (‘/’) from pathnames. The default is to strip leading slashes.

-R  Display statistics at the end of operation. These include compression ratios, transfer speeds, byte details, etc.

-X  The option prevents cyphertite from descending into directories that have a different device number than the file from which the descent began.

-e  Deletes a remotely stored archive metadata file. The option is used in conjunction with -m.

-m  run in metadata mode. See METADATA MODE for an explanation.

-p  Preserve user and group ID as well as file mode regardless of the current umask(2).

-r  Enable regex(3) matching. The default is to use glob(7).

-v  Turn on verbose output.

-V  Display version information. All other options are ignored.

METADATA MODE
If -m is provided on the command mode then cyphertite will operate in metadata mode. The -x, -c and -t commands now operate on the remote archive metadata store. Additionally -e may be used to delete remote metadata from the server.

METADATA OPERATION MODES
Two different metadata modes are supported by cyphertite: local and remote. In local mode, cyphertite operates similarly to tar(1) with the archive metadata files operating analgously to the tar archive files.

In remote mode, cyphertite will instead operate on metadata stored on the remote server. In this case the names provided by -f are used as tags to the metadata. They are stored on the remote server with the form: YYYYMMDD-HHMMSS-tag . Extract commands will operate on the newest archive metadata file on the server unless the full metadata name is provided. The cache directory defined in the cyphertite.conf(5) configuration file will be used to store local copies of the archive metadata files.

FILES
/etc/cyphertite/cyphertite.conf
    Default configuration file.
~/.cyphertite/cyphertite.conf
    User configuration file.
~/.cyphertite/ct_crypto
    Default crypto secrets file.

EXAMPLES
Create an archive named accounting-2010.ct containing the directory /data/accounting/2010:

    $ cyphertite -cf accounting-2010.ct /data/accounting/2010

Verbosely create an archive named pictures.ct, of all files matching regex(3) pattern *.jpg:

    $ cyphertite -rcvf pictures.ct *.jpg

Perform a differential backup of an archive named htdocs-201104.ct. Files in /var/www/htdocs whose modification times (mtime) are newer than in previous backup htdocs-201104.ct will be archived.

    $ cyphertite -B htdocs-201104.ct -cf htdocs-201105.ct /var/www/htdocs

Extract files from archive backup.ct into directory restore.

    $ cyphertite -C restore -xf backup.ct

SEE ALSO
cyphertite.conf(5), glob(7), regex(3)

AUTHORS
cyphertite was written by Conformal Systems, LLC. <info@conformal.com>.

CAVEATS
cyphertite is currently in beta testing. Some of the above options may change before official release. Before executing the first backup on a system, run cyphertite with no parameters to allow cyphertite to prompt for the information needed to setup the account as follows:
    $ cyphertite
    cyphertite config file not found. Create one? [yes]:
    Target conf file [/root/.cyphertite/cyphertite.conf]:
    cyphertite login username: mylogin
    Save cyphertite login password to configuration file? [yes]:
    login password:
    confirm:
    Save cyphertite crypto passphrase to configuration file? [yes]:
    Automatically generate crypto passphrase? [yes]:
    Choose a metadata operation mode (remote/local) [remote]:
    Target metadata cache directory [/root/.cyphertite/ct_cachedir]:
    Use automatic remote differentials? [no]:
    Configuration file created.

Using the built-in configuration file generator simplifies the install substantially.