TFCRYPT(1) General Commands Manual TFCRYPT(1)
 

NAME

tfcrypta set of tools to manipulate data.
 

SYNOPSIS

tfcrypt [-n passes] [-C modeop] [-t twfile] [-K file] [-c ctropt] [-r rndsource] [-RZ nrb_spec] [-U mackeyopt] [-SM MAC] [-D macbits] [-E erropt] [-O optlist] [-V seconds] [-edpkwmPqvaAWV] [-sum] [-b64] [--] [key] [source] [dest]
 

tfcrypt sksum [-l nrb_spec] [-c checkfile] [-U mackeyopt] [-AWV] [--] [source] ...
 

tfcrypt base64 [-edV] [--] [source] [dest]
 

tfcrypt mtcrypt [-O count=] [-O mtpart=] [-O mtnum=] [-O mtnoiseek] [tfcrypt opts]
 

tfcrypt tfbench seconds
 

DESCRIPTION

tfcrypt is a symmetric cryptography toolkit to operate over the existing or newly appearing data in the easiest way.
 
tfcrypt was initially developed as a frontend tool to a most secure Threefish stream cipher at a time (2012), the only world's cipher which allowed to use 1024 bit keys and data blocks.
 
tfcrypt tries to be very accurate about IO. It can process files, storage media, and other data that comes from sources which are non-rewindable (like Unix standard streams or pipes). It is fully Unix compilant tool: tfcrypt may serve as a fully transparent filter.
 
tfcrypt uses CTR stream cipher by default, but also includes TCTR mode which is a Threefish specific mode, and usual, well known CBC mode. It is probably better to use TCTR mode by default, because of CTR mode limitations: key and counter reuse leads to revealing of changed bits in two nearly same clear text messages.
 
tfcrypt is enabled to process very large amounts of data, and it's typical to process data amounts within T (terabyte) range.
 
tfcrypt enables user to perform a random access within encrypted space, requiring to know only offset (in block aligned bytes), or TF blocks offset number. Note that this feature works seamlessly only with CTR and like modes, not with CBC!
 
tfcrypt offers plausible deniability of encrypted data: there are absolutely no any distinctive headers are stored, and validity of decrypted data cannot be verified. That is: every key which is supplied to tfcrypt is potentially a valid key, it's just the decrypted data is unusable if wrong key was supplied. tfcrypt never detects and does not give a chance to detect if one key is wrong and other is right especially to fight brute force attempts. Even if a valid MAC is attached to a stream, one must decrypt and hashsum the entire stream just to guess if the candidate key is valid. The situation is actually worse because tfcrypt uses key derivation from user key material, which means that it is easier to guess raw TF keys directly rather than to (painfully slowly!) derivate candidate user keys.
 

IMPORANT TERMINOLOGY

“TF” short for Threefish.
 
“message” is an encrypted or decrypted result. “message” can be of any length: it may be a simple text message less than one TF block size, or a encrypted disk image of a 500G in length.
 
“stream” means any non-seekable, potentially length limited non-renewable set of bytes coming out somewhere, or a fixed size set of bytes available at any time. Well known streams are: files on media, media as a whole accessed through special files, Unix standard streams (stdin, stdout, stderr), other non-standard streams like pipes of any kinds, inherited file descriptors.
 
“EIO block” is a minimal TF engine block length. With TF, the block length is 128 bytes, or 1024 bits. EIO block defines cipher strength. EIO block also is a minimal data amount which is processed within TF modes of operation such as CTR or TCTR.
 
“IO block” is a tfcrypt configured data block which is typically larger than EIO block. The default one is set to be a 65536 bytes. tfcrypt tries to read(2) and write(2) blocks of this length. Modes of operation included also can accept these lengths of blocks and operate over them internally with smaller EIO blocks.
 
“rawkey” is a key which is ‘raw’, i.e. the key material which is possible result of key derivation from the user supplied password or keyfile. It is used directly inside TF engine when decrypting or encrypting, not the user data such as password or keyfile. In tfcrypt it's length is always same as EIO block.
 
“tweak” is a special small key which is property of TF engine. TF engine is a tweaked cipher, and it uses two keys: main user key and tweak key which can be incremented like a counter (see TCTR mode). By default tfcrypt generates tweak from rawkey, then uses it as a key extension, so total key length increases to 1216 bits (but effective key length still remains to be 1024 bits), and does not increment it. In TCTR mode tfcrypt increments tweak once per EIO block.
 
“MAC” is a Message Authentication Code. MAC serves to verify integrity of message, and can verify if specified decryption key is correct. MAC however cannot prove identity of message source. In tfcrypt, it is appended to end of stream or saved to separate file each time an [-S] option is used. [-D] option controls MAC length, and [-U] changes MAC with specified MAC key. MAC can be further verified with [-M] option. tfcrypt does not calculate MAC by default - it slows down encryption, because it is a separate task. Specifying MAC key with [-U] while encrypting stream additionally changes main key, so two separate keys are required then to decrypt the stream.
 
“CTR” mode is a stream oriented mode of operation. It works by encrypting a block of incrementing counter, then adding user data to result. CTR wins by enabling parallel operation, but looses when key and counter gets reused (bit differences of updated messages will be visible to attacker even if no key and counter pair is known).
 
“TCTR” mode is a CTR like mode which is unique to TF: it reuses TF tweak value as a counter. Because this tweak value acts as a second secret key input, it enables encrypting input blocks directly without encrypting a counter. This mode shares CBC security of single block while maintaining parallel operation of CTR, and it's indeed more secure than CTR mode.
 
“nrb_spec” is a multipurpose specifier which is accepted in several places of tfcrypt. nrb_spec may specify a single number of bytes, say 7650, a short human readable number, say 7k, or a path to a file which size will be determined and used as a number there. Note that tfcrypt currently does not accept complex human readable numbers, so only single prefixed ones are recognised. This may be fixed in future revisions of tfcrypt.
 

OPTIONS

-e
Encrypt [source] stream (if mode requires separate encrypt and decrypt operations)
-d
Decrypt [source] stream (if mode requires separate encrypt and decrypt operations)
-p
Do not require [key] stream separately, but ask user for a password safely inside a tty directly.
-k
Read first 128 bytes of [key] and assume that these bytes are already rawkey data to be used within TF engine.
-K file
In key derivation mode, generate rawkey from user data and store it to file. The file will be 128 bytes in length and will contain random looking rawkey data. You should keep this file away from other's eyes. It is effectively a shortcut key which can be used without precomputing derivation.
-w
Overwrite [source] file in place, without placing result into [dest] (destination will be ignored). Warning: this may or may not work flawlessly with prepending a counter to the beginning or placing a MAC signature at the end. This option should be used only when an exact same amount of bytes will be processed.
-n passes
Specify key derivation passes. Higher values make key guess much harder, higher than 200000 are probably useless and slow even on powerful desktop machines. Lower values are easier for embedded systems. Since that TF is a 1024 bit cipher, it is easier to use a lower value of, say 23000, as a compromiss for anyone. Further, a [-K] permits to precompute key to be used on a really slow systems.
-t file
Read tweak value from a file. tfcrypt comes with embedded tweak value, which is specified in tfcrypt_defs.h file at compile time, but it does not use it anymore by default. This value is historical, one should not change it at compile time: tfcrypt now precomputes tweak from a rawkey directly. If one wishes to specify own tweak, an [-T] option must also be used.
-T
Derive tweak value from key. This option is default. If used again, it will turn off tweak derivation, and embedded tweak will be used instead. The embedded tweak value can be changed with [-t] option.
-C modeop
Specify mode of operation: CTR, TCTR or CBC. CBC is well known Cipher Block Chaining mode, a non-parallel block mode. By default, CTR is used. This default can be overriden at compile time in tfcrypt_defs.h include file.
-c ctropt
Specify counter value, or show it. Depends on the way of operation [-ed], and can take these arguments: show will dump counter value to stderr, either as hex string or base64 (depending if [--A] is used before), head With [-d] will read EIO block as counter value directly from beginning of [source] stream and will display an error if not enough bytes were read, rand With [-e] will generate new random counter value and write it to [dest] stream before any encryption will occur. Instead of specifying these options, a path to a file can be specified instead: the counter value will be read from that file in both [-ed] modes.
-q
Be always quiet, do not display any strings even on error. Supresses both [-vV], if it comes after them.
-v
Enable some verbose messages about progress (password was read, key is derived, process is started). Note that this option does not turn on status timer, use [-V] to do that.
-V seconds
Enable status timer to display current progress: it will dynamically update a string once per seconds containing information about read bytes from [source], written (encrypted or decrypted) bytes to [dest], non approximated realtime speed in bytes per seconds specified. A shorter form of this string can be also enabled via signal (see SIGNALS section), or with [-O statless] option. All numbers will also include human readable numbers such as 1.58M, 2.63K or 87.54G. The numbers base (either powers of two or decimals) can be selected with [-O gibsize] option. Default to use is powers of two, the native metering system of computers.
-V
Without seconds argument, it will display tfcrypt version string, then exit.
-a
This is convenient shortcut of [-O xtime], like cp(1) does: copy timestamps between files.
-r file
Specify randomness source as file. Default one is /dev/urandom, this option is provided mainly to be used as [-r -/dev/random] or something like that.
-R nrb_spec
Generate nrb_spec bytes of Cryptographically Secure randomness. Note that C.S. randomness is guaranteed only if /dev/urandom is available and generates sufficient C.S. random data, or random source specified with [-r] also matches the required C.S. criteria.
-Z nrb_spec
Like [-R], but generates zeroes instead. Therefore, it does not require any random source.
-D macbits
Specify MAC signature bit width.
-U mackeyopt
Specify MAC key. MAC key is a key which alters MAC in a way that only party having the key can verify MAC correctness. It is useful with sksum tool. With tfcrypt it alters encryption key in a way that two keys are required to decrypt the stream. mackeyopt specifies a way in which the key should be read: key use rawkey as a key, pwd bring secure tty password asking mechanism to read password and use it as a key (no key derivation is performed over MAC key password!), file read entire file of arbitrary length as a MAC key.
-S MAC
Generate MAC signature while encrypting the stream. MAC specifies how to store it: MAC or mac tells tfcrypt to write it to end of stream upon finishing, file specifies path to a file where it will be written, - says to write it to stdout instead. Note that failure to write signature will result in a wasted calculation times, so be careful about specifying the destination. In particular, this option is not useful for you if you're encrypting fixed length device such as disk storage or other fixed size buffer or media. tfcrypt will error out in such cases without attempts to force the bytes into filled bottle.
-A
Turn hex strings produced by sksum or tfcrypt by default into base64 compilant strings.
-W
Do not output hex strings - dump raw binary data directly. When used in sksum, with multiple files to generate hashes for, this will produce raw block of merged binary hashsums together without filenames embedded, in order of specified files.
-M MAC
(Try to) Verify MAC signature while decrypting the stream. MAC specifies source where signature is obtained: MAC or mac tells tfcrypt to take the tail of [source] stream as MAC signature, file is a named file from which first EIO block byte or [-D] bit length MAC signature is read, - forces tfcrypt to read it from stdin directly, and special drop tells tfcrypt not to verify existing tail MAC signature, but still drop it from the end of stream, so there will be no ‘garbage’ output at the end of stream. Influential options are [-D], which changes MAC signature length, and [-U], which sets second encryption MAC key. It is impossible to tell if MAC signature is present inside the stream without decrypting it with valid key, then manually analyzing it. Therefore, an invalid MAC signature error may appear on streams where it is absent at all. Any corruption of stream will also generate such error with present MAC signature. tfcrypt cannot tell the difference between two because of guaranteed plausible deniability.
-m
Do not write decrypted data anywhere, just verify MAC signature. The [-M] must set the source from which it will be read first.
-E erropt
sets tfcrypt (read) error behavior. erropt may be one of: exit print error if not quiet, then cleanly exit, cont print error if not quiet, then always continue without attempt to pad missing data with zeroes, sync print error if not quiet, then pad missing data up to fill the IO block with zeroes, process the padded block and continue. Note that sync will produce garbage in output if triggered by error while decrypting. Default error action is exit. A special xall value for [-E] turns on catching all errors, not just EIO error. This one must be supplied separately (i.e. multiple [-E] specifiers).
-O optlist
Set tfcrypt options. optlist can take one or more comma separated options which may be in form of single flag or flag=value.
 
These options are currently defined:
 
sync
Ask operating system to do synchronous reads and writes, i.e. do not fill the temporary OS buffers on reads and writes and write data immediately. Please note that underlying hardware may still implement transparent buffers, data in which may be lost during power outage. This mode, if supported by OS also results in much slower performance.
 
fsync
Do a fsync(2) call on each write(2). Applies to any write over any physical file, not just [dest].
 
trunc
Truncate [dest] physical file to zero before writing. Warning: file will be truncated even if no IO will be performed (if read from [source] was zero for example).
 
pad
Pad incomplete tail block to EIO block size so if a block wide mode of operation is used (e.g. CBC), the last block will not be decryptable in a CTR mode of operation, to which tfcrypt falls back in any mode of operation if last (tail) block is incomplete. The padding is always performed with zeroes.
 
xtime
Copy timestamps of physical files from [source] to [dest].
 
gibsize
Use SI units of size when ‘1k’ means ‘1000’. This option is applied only to shorter, human readable numbers which are translated by program. By default, tfcrypt uses powers of two numbers when ‘1k’ means ‘1024’, which is common and well to computers.
 
plainstats
Status line is dynamic by default on ttys which support dynamic text updating. This option forces printing status line on a new line, without erasing previous one.
 
statless
Print only total processed number of bytes and current IO speed, only in human readable form.
 
norepeat
Do not ask for any password confirmations. Usually, password confirmation is asked when encrypting.
 
prompt=str
Set main password prompts to this string. This string will be echoed back to stderr instead of regular “Enter password:” string. This string does not have any effect over MAC password prompt (see below).
 
macprompt=str
Set MAC password prompts to this string. This string will be echoed back to stderr instead of regular “Enter MAC password:” string. This setting is only for MAC password prompts.
 
iobs=nrb_spec
Specifies IO block size which will be used when reading and writing. It cannot be larger than a hardcoded maximum default IO block size (typically 64k or BLKSIZE).
 
iseek=nrb_spec
In crypt mode, this command tells tfcrypt to seek [source] file or device by specified number of bytes (nrb_spec). Counter is also adjusted by computed number of blocks. If a number is not round to a block size, an error is displayed early prior to any IO and program exits. In plain mode, counter is obviously not adjusted, and error is not generated on not aligned block, the seek is performed by exact number of bytes specified.
 
ixseek=nrb_spec
Same as iseek, but does not adjusts counter and ignores block aligning to a block size. It behaves as iseek in plain mode, but in crypt mode.
 
ictr=blocks
Tell tfcrypt to increment counter value by specified blocks number. Size of each block is EIO block size (128 bytes). This operation does not seek the [source] by specified number of blocks, it simply adjusts the counter. Warning: ictr is valid only for CTR and CTR like modes of operation, and ignored in plain mode.
 
ixctr=nrb_spec
Like ictr, but increments counter by a number of blocks which is calculated from specified number of bytes (nrb_spec). If a number is not round to a block size, an error is displayed early prior to any IO and program exits. This option is ignored in plain mode.
 
oseek=nrb_spec
Seek [dest] file or device by specified number of bytes (nrb_spec). The writes will occur from specified position.
 
count=nrb_spec
Process only specified number of bytes (nrb_spec), not whole [source] or [dest] streams. Internally, processing stops after reading specified number of bytes from [source].
 
xkey=nrb_spec
Read only first number of bytes (nrb_spec) from [key].
 
 

EMBEDDED TOOLS

tfcrypt includes some helper tools to work with data: a Skein hashsum tool sksum, base64 encoder and decoder base64, a multitask helper scheduler mtcrypt, a benchmark tool tfbench.
 
There is also an tfsign tool, but it's not going to be documented: it maybe removed in future versions of tfcrypt.
 
Invoking
 
To invoke the embedded tool, one must pass it's name as a name of program during an execve(2) into the very first argv cell: argv[0].
 
For example: execve(/local/bin/tfcrypt, {[sksum], [-A], [/etc/passwd], NULL}, {environ})
 
Simply speaking without internals, you should make a hard link to tfcrypt with the name of the tool or symlink pointing to tfcrypt binary with the name of the tool:
	# ln /local/bin/tfcrypt /local/bin/sksum
 
or
	# ln -s /local/bin/tfcrypt /local/bin/sksum
 
Descriptions of the tools
 
sksum is needed when you need to verify data integrity, compare two or more files, or save their hashsums for later verification. It is important to have this tool embedded, so it could be useful in tight situations.
 
sksum allows to verify files or streams of almost unlimited length.
 
The amount of files specified in cmdline after all options is believed to be unlimited. To verify standard input, use ‘-’ as a file name.
 
By default, sksum reads standard input if no files or streams are specified in it's cmdline.
 
sksum options:
-l nrb_spec
Read and process only this number of bytes (nrb_spec) from each specified source, not whole source. Useful when you need to verify a part of message when message actually lays on a fixed size media such as disk and it is (much) smaller than the media.
-c checkfile
Read checkfile line by line and verify each “hash file” pair. On each succeed verification, sksum will emit “file: OK” line, while on a failed one it will emit “file: FAIL” line. An exit status is zero if all files were verified and found to be OK, nonzero if there were errors (not only failed verifications, but any other system or user errors).
-V
When used together with [-U pwd], it will report a ‘magic’, very short password checksum to help user to identify that the password he entered is correct. This is to replace a ‘double asking’ functionality found in other password asking mechanisms. The user must first enter the password several times before and know the control checksum.
 
sksum [-AWU] options have same meaning as tfcrypt ones.
 
base64 encoder and decoder helps to translate binary input to base64 (ASCII) text output and vice versa. It is essential to convert files to ASCII format to send them over non-binary media such as to post them somewhere online in Internet: into comment, post, pastebin or some other text-only field.
 
base64 accepts only two arguments: input filename or stream and output filename or stream. It also accepts the following options:
 
-e
Encode (default) binary stream into ASCII output,
-d
Decode ASCII input back into binary stream.
 
You should know that ASCII output will be larger in size of it's input by about approx. 33%%.
 
base64 does a little formatting so text editors will not go mad if they will load an encoded file. It splits it's output into 76 character lines by inserting newlines. There is no currently an option to override this value.
 
base64 will try to do it's best to decode the stream. If a correct base64 input is feed, it's guaranteed that it will be decoded back to original binary stream. The ‘=’ padding characters are required, but base64 will hopefully decode correctly an input which lacks them. On any other malformed or invalid input, the behavior is undefined.
 
mtcrypt accepts all the options tfcrypt currently understands but has two mutually exclusive options which [-O] understands additionally: [-O mtnum=] accepts a number of tfcrypt tasks to spawn, and [-O mtpart=] accepts a partition area size from which to compute a number of tasks to spawn.
 
mtcrypt calculates partitioned offsets and lengths and spawns multiple regular tfcrypt instances to do actual tasks, then exits successfully (unless there is an error during execution).
 
To use mtcrypt successfully, you must supply a maximum file or device length with either [-l] or [-O count=] options.
 
mtcrypt [-O mtnoiseek] option disables source stream seeking. This is useful when reads are performed from an infinite stream of something (for example, zeroes or random numbers).
 
Not all options tfcrypt understands are useful with mtcrypt! For example, doing MAC signature calculation is completely useless in this mode. Using such options together with mtcrypt will result in undefined behavior: random results could be obtained, including data loss. Original intent of mtcrypt is to schedule multitask read/writes from and to block devices. Using it beyond this intent is probably ask for problems. You have been warned!
 
Warning! Using mtcrypt on non-seekable files results in undefined behavior!
 
tfbench measures host performance for Threefish. Usually this tool should be run if you're concerned about host being too slow to perform some big task with tfcrypt. Mandatory seconds argument can be specified as a fraction or integer.
 
tfbench accepts almost all tfcrypt arguments which are meaningful here.
 

SIGNALS

During operation user may alter tfcrypt behavior by sending the following Unix signals with kill(1):
 
 
Unix signals are very scarce and archaic resource. I wanted to make status timer change more human friendly, but lack of usable signals made it more obscured. That's shame the Unix signals thing is still encouraged to be used.
 

EXAMPLES

This section shows how tfcrypt can be used. Actual commands here start after a ‘%’ prompt, while lines with comments describing what they do start with ‘#’ character. Some examples may require elevated superuser privileges, but they still shown with a ‘%’ prompt.
 
tfcrypt examples
 
The most simplest and most useful example is to encrypt and decrypt files without fuss:
# To encrypt: 
% tfcrypt my.key /bin/busybox my.encrypted 
 
# To decrypt: 
% tfcrypt -d my.key my.encrypted busybox.orig 
 
# To verify (assuming the key is same): 
% sksum -A busybox.orig /bin/busybox
 
This example encrypts a regular file /bin/busybox into my.encrypted using user key my.key. Note that my.key maybe of an arbitrary length, and every bit of that key will be meaningful when decrypting my.encrypted back again to a matching /bin/busybox (in our case, it's a busybox.orig file).
 
You may encrypt small files (a message to someone) with big keys (using, for example, your whole CD with your favourite music as a key ):
% tfcrypt -v /dev/sr0 msg.txt msg.enc
 
No one will be ever read your encrypted message without access to your full CD or it's image. But please be careful: CDs are fragile and proven to be erratic.
 
tfcrypt offers possibility to decrypt data from anywhere inside a (big) encrypted file or stream. You must specify offset within that file:
% tfcrypt -d -O iseek=63s my.key /dev/sda sda.63s.img
 
You may specify length that must be decrypted, instead of going to the end of file or stream:
% tfcrypt -d -O iseek=93000032s,count=80k my.key /dev/sda sda.part.img
 
tfcrypt does not support multiple threads and there are reasons to omit such functionality. Basically, if your storage is really big enough, you may “partition” the task into multiple blocks simply by dividing whole space into smaller pieces by your CPU cores for example, then run each tfcrypt separately exactly only for this piece:
# 
# Say we have a space to encrypt of 128241s (128241 512 byte sectors). 
# You may partition this space into 3 * 42747s smaller pieces. 
# Then run tfcrypt for each piece separately, caring about 
# that it will not overwrite others. 
# The parameters -O iseek,oseek and -O count are to help. 
# 
# To save time, you may precompute rawkey for the task with -K. 
# 
% cat zero.sh 
#!/bin/sh 
fork tfcrypt -v -O count=42747s -w -k my.key zero.dd 
fork tfcrypt -v -O iseek=42747s,oseek=42747s,count=42747s -w -k my.key zero.dd 
fork tfcrypt -v -O iseek=85494s,oseek=85494s,count=42747s -w -k my.key zero.dd
 
Keep in mind that the more “threads” you launch over same disk, the slower maybe a process because disk has to move it's heads between the concurrent tasks.
 
In future revisions of tfcrypt there maybe a functionality to assist of creating such pseudo multithreaded tasks. Or separate tool included into tfcrypt distribution.
 
You probably wish to preserve the integrity of your encrypted data, so you will be able to detect a fact of tampering or corruption of the data later. To request tfcrypt to add a MAC signature to an encrypted file, use [-S] option:
# Store MAC signature into encrypted file itself 
% tfcrypt -S mac my.key /bin/busybox my.encrypted 
 
# Store MAC signature into separate file 
% tfcrypt -S my.encrypted.sig my.key /bin/busybox my.encrypted
 
You can then verify MAC signatures with an [-M] option:
# Verify embedded into file signature, and decrypt file 
% tfcrypt -d -M mac my.key my.encrypted busybox.orig 
 
# Verify separate file signature, and decrypt file 
% tfcrypt -d -M my.encrypted.sig my.key my.encrypted busybox.orig 
 
# Verify, but do not decrypt file, just show how it's feeling 
% tfcrypt -d -M mac -m my.key my.encrypted 
% tfcrypt -d -M my.encrypted.sig -m my.key my.encrypted
 
Verification status of [-M] option will be reported to stderr (unless [-q] is in effect): “signature is good” indicates that signature was found, verified and OK while “signature is BAD: ...” indicates that either: signature was not found (not embedded, not attached, invalid parameters, it does not exist, stream is bad, stream is not encrypted etc.), data is corrupt (but tfcrypt will not tell you where because it's not possible), or signature somewhere else (possibly as a detached file - go find out).
 
tfcrypt is able to tell you a progress of process. Use [-V] option with a time specifier to set the progress update timer:
# Enable 500ms status display timer 
% tfcrypt -V 0.5 -e my.key /bin/busybox my.encrypted
 
If you need to change the timer at runtime, send a SIGUSR2 signal to already running tfcrypt. It will double the value each time the signal is caught. If two signals will arrive in less than 100ms, then tfcrypt will reset status timer to 250ms and for any future signal it will start to double the value from there.
 
tfcrypt will compute the user key into raw key (a key of fixed key size: see tfcrypt rawkey definition in IMPORTANT TERMINOLOGY above). Sometimes this process maybe slow or very slow (on embedded systems for example). To speed up the encryption, you may generate an exact raw key from the user key or password:
# Generate from user key 
% tfcrypt -K rawkey.out my.key 
 
# Generate from password 
% tfcrypt -K rawkey.out -p
 
Then use this raw key as:
% tfcrypt -e -k rawkey.out /bin/busybox my.encrypted
 
You may also decrypt the stream in same manner:
% tfcrypt -d -k rawkey.out my.encrypted busybox.x
 
Here, my.key equals to rawkey.out.
 
Warning: such key has all the power as a regular, user key or password! Do not leave it alone after use! Erase it or handle in the same manner as you may do with your user key.
 
Overwriting files with [-w] in place is easy. Moreover, tfcrypt will overwrite them securely (as long as host OS does not steal unencrypted data somewhere else), by writing to a file in place instead of writing to a new file and deleting old one. However this may be dangerous with large media such as disks because if your power will cut off accidentially, you may or may not tell where tfcrypt had *exactly* ‘stopped’. Already encrypted data maybe a problem because you could encrypt already encrypted data :-) tfcrypt currently does not provide an option to write a progress file, so using [-w] is recommended only for small files or when you absolutely sure that your system is stable enough to carry the operation, or you have a reliable backup.
 
tfcrypt provides a strong random data generator, which maybe even stronger than most /dev/urandom implementations ever existed. It is activated with an [-R] option and accepts a number of bytes to be generated. Because of it's flexibility, it can be used in a very wide number of cases:
# Just generate 8k bytes of random and emit them to stdout 
% tfcrypt -R 8k 
 
# Generate 3G of random data and write it to a random.bin file 
% tfcrypt -R 3G random.bin 
 
# Same, but with shell redirection 
% tfcrypt -R 3G >random.bin 
 
# Generate a rawkey size file to be used as a raw key later 
% tfcrypt -R cbs raw.key 
 
# Generate a CD or DVD size random data 
% tfcrypt -R /dev/sr0 my_cddvd_rnd.bin 
 
# ... then use it as a key to encrypt something important and useful 
% tar -C /mnt -zc . | tfcrypt -e -S mac my_cddvd_rnd.bin - bkup.tar.x 
 
# You may even wish to generate stronger random. Use /dev/random as random source! 
# The result will be completely unpredictable and it will have nearly same quality 
# as the /dev/random itself (assuming Threefish is unbreakable) 
tfcrypt -r /dev/random -v -R 8M my_c00l.key
 
However this RNG relies on an existing random source. Even if it reads the numbers from it and the context is such big enough to be almost never guessable, the randomness of the source must be unpredictable enough. tfcrypt defaults to /dev/urandom for several reasons. First, it's fast. Second, it's secure enough on most platforms. Third, it's nonblocking (usually). For stronger quality output, you may with to use /dev/random as the random [-r] source.
 
The PRNG included is much faster than traditional /dev/urandom. It is capable to produce random bytes at an encryption speed of Threefish.
 
The included NUL (zero) bytes generator [-Z] has same syntax and semantics as RNG. It is useful to finally wipe and zero fixed media.
 
Both [-RZ] accept ‘-1’ as a size to request an infinite output.
 
Real life author's examples:
# Make encrypted clone of *whole* disk, preserving it's partitioning, 
# filesystems and all the files on it. Also useful to encrypt the drive 
# for a future transparent encryption kernel extension. 
# Assuming that /dev/sdb1 is equal or larger than /dev/sda. 
% tfcrypt -e -S sdb.sig my.key /dev/sda /dev/sdb1 
 
# Live encrypted tar.gz backup 
% tar -zcf - lynx | tfcrypt -e -S mac my.key - lynx.tar.gz 
 
# tfcrypt by default asks for password, then encrypts stdin to stdout. 
# Thus, it can be used as a basic "filter" program. This complex example 
# shows how to send the output into two places at the same time. 
% tar -zcf - lynx | tfcrypt | tee /mnt/lynx.tar.gz >/data/lynxbk.tar.gz.x 
 
# Just overwrite the file 
% tfcrypt -p -w -e x.bin 
 
# Erase hard drive. tfcrypt takes the size of drive and erases 
# only this available size, not trying beyond. 
% tfcrypt -V1 -R /dev/sda /dev/sda 
% tfcrypt -V1 -Z /dev/sda /dev/sda 
 
# Encrypt file, preserve it's timestamp 
% tfcrypt -ea -p /bin/busybox busybox.x 
 
# Generate signature of lesser bit length (here: 256 bits) 
% tfcrypt -e -S 256.sig -D 256 my.key /dev/sda /dev/sdb1 
 
# Generate a random key file of 64k size 
% tfcrypt -v -r /dev/random -R iobs my.key 
 
# Truncate files before writing to them 
% tfcrypt -v -O trunc -e my.key /bin/busybox busybox.x
 
This list of examples is incomplete. It will be continously updated.
 

BUGS

Currently, tfcrypt does not support multiple threads or multithreaded operation. There are reasons for that:
 
 
Some options maybe awkward to use. Author had noted that tfcrypt has so many options that it is easy to do something wrong even with the data. Take care!
 
Currently, there are bugs inside signal handling code versus status display. They're going to be fixed later...
 
There is also a bug that prevents tfcrypt from stopping by signal when “-E cont” is in effect and continuous errors appear. It will be fixed later.
 

AUTHOR

tfcrypt was written by Andrey “ElectroRys” Rys (rys@lynxlynx.ru).
29Dec2017 R2