TCPLAY(3)

NAME
tc_api_init, tc_api_uninit, tc_api_info_volume, tc_api_info_mapped_volume, tc_api_create_volume, tc_api_modify_volume, tc_api_map_volume, tc_api_unmap_volume, tc_api_check_cipher, tc_api_check_prf_hash, tc_api_get_error_msg, tc_api_get_summary, tc_api_get_state - TrueCrypt volume management

LIBRARY
libtcplay

SYNOPSIS
#include <tcplay_api.h>
int
tc_api_init(int verbose);
int
tc_api_uninit(void);
int
tc_api_info_volume(tc_api_opts *api_opts, tc_api_volinfo *info);
int
tc_api_info_mapped_volume(tc_api_opts *api_opts, tc_api_volinfo *info);
int
tc_api_create_volume(tc_api_opts *api_opts);
int
tc_api_modify_volume(tc_api_opts *api_opts);
int
tc_api_map_volume(tc_api_opts *api_opts);
int
tc_api_unmap_volume(tc_api_opts *api_opts);
int
tc_api_check_cipher(tc_api_opts *api_opts);
int
tc_api_check_prf_hash(tc_api_opts *api_opts);
const char *
tc_api_get_error_msg(void);
const char *
tc_api_get_summary(void);
tc_api_state
tc_api_get_state(float *progress_pct);

DESCRIPTION
The tcplay library provides an interface to create, query and map TrueCrypt-compatible volumes.

The tc_api_create_volume(), tc_api_modify_volume(), tc_api_map_volume(), tc_api_unmap_volume(), tc_api_check_cipher() and tc_api_check_prf_hash() functions take a tc_api_opts data structure as only argument, which is defined as follows:

    typedef struct tc_api_opts {
    	/* Common fields */
    	const char	*tc_device;
    	const char	*tc_passphrase;
    	const char	**tc_keyfiles;
    	const char	**tc_passphrase_hidden;
    	const char	**tc_keyfiles_hidden;
    	/* Fields for mapping / info */
    	const char	*tc_map_name;
    	int		tc_protect_hidden;
    	/* Fields for mapping / info / modify */
    	int		tc_password_retries;
    	int		tc_interactive_prompt;
    	unsigned long	tc_prompt_timeout;
    	int		tc_use_system_encryption;
    	const char	*tc_system_device;
    	int		tc_use_fde;
    	int		tc_use_backup;
    	/* Fields for modify */
    	const char	*tc_new_passphrase;
    	const char	**tc_new_keyfiles;
    	const char	*tc_new_prf_hash;
    	int		tc_use_weak_salt;
    	/* Fields for creation */
    	const char	*tc_cipher;
    	const char	*tc_prf_hash;
    	const char	*tc_cipher_hidden;
    	const char	*tc_prf_hash_hidden;
    	size_t		tc_size_hidden_in_bytes;
    	int		tc_no_secure_erase;
    	int		tc_use_weak_keys;
    } tc_api_opts;

where the keyfile fields, tc_keyfiles, tc_keyfiles_hidden and tc_new_keyfiles are NULL terminated arrays of key file strings.

The tc_api_info_volume() and tc_api_info_mapped_volume() functions take a tc_api_volinfo data structure as second argument, which is defined as follows:

    typedef struct tc_api_volinfo {
    	char		tc_device[1024];
    	char		tc_cipher[256];
    	char		tc_prf[64];
    	int		tc_key_bits;
    	size_t		tc_size;		/* in bytes */
    	off_t		tc_iv_offset;		/* in bytes */
    	off_t		tc_block_offset;	/* in bytes */
    } tc_api_volinfo;

The tc_api_init() function initializes the library internals and prepares it for use via the API. This function has to be called before using any other API function. If the verbose argument is non-zero, then the library will output information such as errors via stdout and stderr.

The tc_api_uninit() function clears up all internal secure memory, such as memory used for decrypted headers, passphrases, keyfiles, etc.

The tc_api_info_volume() function retrieves information about a volume using the parameters specified in the api_opts argument. All fields except tc_map_name are used in the same way as for tc_api_map_volume(). The retrieved information is placed into the info argument. The tc_cipher and tc_prf fields will contain a string describing the block cipher (chain) and PBKDF2 PRF algorithm respectively. The tc_key_bits field gives the total key size used for the block cipher(s). The tc_size field gives the size of the volume in bytes. The tc_iv_offset and tc_block_offset fields give the IV and block offset in bytes of the volume, respectively. The tc_device field contains the path to the raw encrypted block device.

The tc_api_info_mapped_volume() is similar to the tc_api_info_volume() function, but is to be used on already mapped volumes and doesn't require any passphrase or keyfiles. The tc_map_name field in the api_opts parameter determines which mapped volume is to be queried. The retrieved information is placed into the info argument. All fields will be populated as when calling tc_api_info_volume() except for the tc_prf field, which will contain the string "(unknown)".

The tc_api_create_volume() function creates a new volume using the parameters specified in the api_opts argument. The new volume will be created on the device specified by tc_device using the cipher specified by tc_cipher and the pbkdf2 prf hash algorithm specified by tc_prf_hash and using the passphrase and keyfiles specified by tc_passphrase and tc_keyfiles respectively. If tc_size_hidden_in_bytes is not zero, a hidden volume of the given size will be created, using the cipher specified by tc_cipher_hidden and the pbkdf2 prf hash algorithm specified by tc_prf_hash_hidden. If tc_cipher_hidden or tc_prf_hash_hidden are NULL, the same algorithm as for the outer volume will be used. The passphrase and keyfiles used are specified by tc_passphrase_hidden and tc_keyfiles_hidden respectively. If tc_no_secure_erase is specified, no erase will be performed. If tc_use_weak_keys is specified, the key material for the master key will be taken from /dev/urandom instead of /dev/random. This option should never be used other than for testing.

The tc_api_modify_volume() function modifies a volume (header) according to the parameters specified in the api_opts parameter. The volume is specified in tc_device. The tc_interactive_prompt field determines whether the user will be prompted to enter a passphrase interactively or whether the passphrase in tc_passphrase will be used. If an interactive prompt is used, the prompt will time out after tc_prompt_timeout seconds. A value of 0 indicates that no timeout will occur. The number of passphrase entry retries is defined by tc_password_retries. Depending on the passphrase/keyfiles used either the outer or the hidden volume header will be modified. Any keyfiles that are needed to unlock the volume are specified in tc_keyfiles. If tc_use_system_encryption is specified, a device using system encryption can be accessed. The tc_system_device should point to the parent device (i.e. underlying physical disk), while the tc_device argument should point to the actual encrypted partition. If tc_use_fde is specified, the device pointed to by tc_device should be a whole disk device, not any partition. If tc_use_backup is specified, tcplay will use the backup headers at the end of a volume instead of the primary headers as template for the modification. Both the backup and the main header will always be written as part of a tc_api_modify_volume() call. The tc_new_passphrase and tc_new_keyfiles arguments specify the new passphrase and keyfile(s) to be used, respectively. The tc_new_passphrase argument will only be used if tc_interactive_prompt is not set, otherwise the user will be prompted for the new passphrase. The tc_new_prf_hash specifies the PBKDF2 PRF hash algorithm to be used when reencrypting the header. If it is NULL, the same PBKDF2 PRF hash function will be used that the header already uses. If tc_use_weak_salt is set, a weak source of entropy will be used for the salt of both the main and backup headers. This option does not affect the entropy of the master volume keys, as these are not modified.

The tc_api_map_volume() function maps a volume using the parameters specified in the api_opts argument. The volume, which will be mapped as tc_map_name, is specified in tc_device. The tc_interactive_prompt field determines whether the user will be prompted to enter a passphrase interactively or whether the passphrase in tc_passphrase will be used. If an interactive prompt is used, the prompt will time out after tc_prompt_timeout seconds. A value of 0 indicates that no timeout will occur. The number of passphrase entry retries is defined by tc_password_retries. Depending on the passphrase/keyfiles used either the outer or the hidden volume will be mapped. If tc_protect_hidden is specified, the outer volume will be mapped, but its size will be adjusted so that it does not map over the hidden volume - the hidden volume will hence be protected from any accidental overwriting. If tc_protect_hidden is specified, the passphrase and keyfiles for the hidden volume must be specified in tc_passphrase_hidden and tc_keyfiles_hidden. If tc_use_system_encryption is specified, a device using system encryption can be accessed. The tc_system_device should point to the parent device (i.e. underlying physical disk), while the tc_device argument should point to the actual encrypted partition. If tc_use_fde is specified, the device pointed to by tc_device should be a whole disk device, not any partition. The device will be mapped or queried as a whole. To access individual partitions, a utility such as kpartx(8) should be used, which will create additional individual mappings for each partition in the decrypted mapped volume. For more details on full disk encryption, see tcplay(8). If tc_use_backup is specified, tcplay will use the backup headers at the end of a volume instead of the primary headers to access it.

The tc_api_unmap_volume() unmaps / closes the volume specified in tc_map_name.

The tc_api_check_cipher() function checks whether the cipher specified in the api_opts argument field tc_cipher is valid.

The tc_api_check_prf_hash() function checks whether the prf hash algorithm specified in the api_opts argument field tc_prf_hash is valid.

The tc_api_get_error_msg() function should be called whenver another API function returns TC_ERR. It returns a string containing a description of the error that occured.

The tc_api_get_summary() function returns a string containing a summary of the current progress of a certain operation. Currently only the volume erasing part of creating a new volume can provide a summary. When no summary is available, an empty string is returned. The output otherwise is equivalent to that of a SIGINFO signal when using tcplay(8).

The tc_api_get_state() function returns information on the current state of tcplay. Three states are currently reported:

TC_STATE_GET_RANDOM
    is reported when tcplay is gathering entropy for key material.

TC_STATE_ERASE
    is reported when the volume is being erased.

TC_STATE_UNKNOWN
    is reported in all other cases.

The two states TC_STATE_GET_RANDOM and TC_STATE_ERASE are reported separately, as they are the only lengthy steps during the use of tcplay. The progress_pct parameter, if not NULL, will be set to the percentage completed so far of these operations.

NOTES
TrueCrypt limits passphrases to 64 characters (including the terminating null character). To be compatible with it, tcplay does the same. All passphrases (exlcuding keyfiles) are trimmed to 64 characters. Similarly, keyfiles are limited to a size of 1 MB, but up to 256 keyfiles can be used.

RETURN VALUES
All functions except tc_api_get_error_msg() and tc_api_get_summary() return either TC_OK to signal that the operation completed successfully, or TC_ERR to signal that an error occured.

The tc_api_get_error_msg() and tc_api_get_summary() functions always return a valid, but possibly empty, string.

The tc_api_get_state() function always returns one of: TC_STATE_UNKNOWN, TC_STATE_ERASE or TC_STATE_GET_RANDOM.

COMPATIBILITY
The tcplay library offers full compatibility with TrueCrypt volumes including hidden volumes, system encryption (map-only), keyfiles and cipher cascading.

SEE ALSO
tcplay(8), kpartx(8)

HISTORY
The tcplay library appeared in DragonFly 2.11.

AUTHORS
Alex Hornung