<?xml version='1.0' encoding='ISO-8859-1'?>
<!--
#	vim: set sw=2 ts=2:
-->

<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
			"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

	<!ENTITY fnamn				"<firstname>Mats Erik</firstname>">
	<!ENTITY enamn				"<surname>Andersson</surname>">
	<!ENTITY aar				"2010">
	<!ENTITY datum-en			"<date>October 20th, 2010</date>">
	<!ENTITY epost				"<email>debain@gisladisker.se</email>">
	<!ENTITY namn				"Mats Erik Andersson">

	<!ENTITY paket				"twofish">
	<!ENTITY version			"0.3">
	<!ENTITY lib				"libtwofish">
	<!ENTITY handbok-lib		"<refentrytitle>&lib;</refentrytitle>">

	<!ENTITY debian			"<systemitem class='osname'>Debian GNU/Linux</systemitem>">
]>

<part lang="en">
	<title>&paket;</title>

<reference id="referens.en" lang="en">
	<title>Manual for &paket;.</title>

<!--
	Manualsida engelsk: libtwofish.3
-->
<refentry lang="en" id="&lib;.en">
	<refentryinfo>
		<address>
			&epost;
		</address>
		<author>
			&fnamn;
			&enamn;
		</author>
		<copyright>
			<year>&aar;</year>
			<holder>&namn;</holder>
		</copyright>
		&datum-en;
	</refentryinfo>
	<refmeta>
		&handbok-lib;
		<manvolnum>3</manvolnum>
		<refmiscinfo class="source">&paket;</refmiscinfo>
		<refmiscinfo class="version">&version;</refmiscinfo>
	</refmeta>
	<refnamediv>
		<refname>&lib;</refname>
		<refpurpose>Cryptographic library using the twofish algorithm.</refpurpose>
	</refnamediv>
	<refsect1>
		<title>Description</title>
		<para>
			<command>&lib;</command>
			is a small library to encrypt and decrypt data using the Twofish
			cryptographic algorithm.
		</para>
	</refsect1>
	<refsect1>
		<title>Functions</title>
		<funcsynopsis>
			<funcprototype>
				<funcdef>void <function>Twofish_initialise</function></funcdef>
				<void />
			</funcprototype>
		</funcsynopsis>
		<para>
			Initialise the Twofish crypto engine. 
		</para>
		<para>
			This function <emphasis>must</emphasis> be called before any other
			function in the Twofish implementation is called upon. The call needs
			only be made once in each application program.
		</para>
		<para>
			Apart from initialising the engine, the call also performs a self test.
		</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef>void <function>Twofish_prepare_key</function></funcdef>
				<paramdef>Twofish_Byte <parameter>key[]</parameter></paramdef>
				<paramdef>int <parameter>key_len</parameter></paramdef>
				<paramdef>Twofish_key *<parameter>xkey</parameter></paramdef>
			</funcprototype>
		</funcsynopsis>
		<para>
			Convert a cipher key to the internal form used for 
			encryption and decryption.
		</para>
		<para>
			The cipher <parameter>key</parameter> is an array of bytes.
			The type Twofish_Byte is internally defined to a type suitable
			for your platform. 
		</para>
		<para>
			Any key must be converted to the internal representation
			<parameter>xkey</parameter> as a Twofish_key
			structure before it can be used. The encryption and decryption functions
			only work with the internal form. The conversion to internal form need
			only be done once for each key value.
		</para>
		<para>
			Be sure to wipe all key storage, including the Twofish_key structure, 
			once you are done with the key data.  A simple call
			<programlisting>memset(xkey, 0, sizeof(Twofish_key));</programlisting>
			will do just fine.
		</para>
		<para>
			Unlike most implementations, the present one allows any key size from
			zero bytes to 32 bytes. According to the Twofish specifications, irregular
			key sizes are handled by padding the key with zeroes at the end until the
			key size is 16, 24, or 32 bytes, whichever comes first. Note that each key
			of irregular size is equivalent to exactly one key of 16, 24, or 32 bytes.
		</para>
		<para>
			The key length argument <parameter>key_len</parameter> must be in the
			proper range. If <parameter>key_len</parameter> is not in the range
			0,...,32, this routine attempts to generate a fatal error (depending
			on the code environment), and at best (or worst) returns without having
			done anything.
		</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef>void <function>Twofish_encrypt</function></funcdef>
				<paramdef>Twofish_key *<parameter>xkey</parameter></paramdef>
				<paramdef>Twofish_Byte <parameter>plain[16]</parameter></paramdef>
				<paramdef>Twofish_Byte <parameter>crypto[16]</parameter></paramdef>
			</funcprototype>
		</funcsynopsis>
		<para>
			Encrypt a single block of data.
		</para>
		<para>
			This function encrypts a single block of 16 bytes of data.
			If you want to encrypt a larger or variable-length message, 
			you will have to use a cipher mode, such as CBC or CTR. 
			These are outside the scope of this implementation.
		</para>
		<para>
			The xkey structure is not modified by this routine, and can be
			used for further encryption and decryption operations.
		</para>
		<funcsynopsis>
			<funcprototype>
				<funcdef>void <function>Twofish_decrypt</function></funcdef>
				<paramdef>Twofish_key *<parameter>xkey</parameter></paramdef>
				<paramdef>Twofish_Byte <parameter>crypto[16]</parameter></paramdef>
				<paramdef>Twofish_Byte <parameter>plain[16]</parameter></paramdef>
			</funcprototype>
		</funcsynopsis>
		<para>
			Decrypt a single block of data.
		</para>
		<para>
			This function decrypts a single block of 16 bytes of data.
			If you want to decrypt a larger or variable-length message, 
			you will have to use a cipher mode, such as CBC or CTR. 
			These are outside the scope of this implementation.
		</para>
		<para>
			The xkey structure is not modified by this routine, and can be
			used for further encryption and decryption operations.
		</para>
	</refsect1>
	<refsect1>
		<title>Example</title>
		<programlisting>/*
* catwo.c
*
* A simple-minded encryptor and decryptor application.
*
* Usage:  catwo {[-e] | -d} key-string  &lt; infile  &gt; outfile
*
* The switch "-d" calls for decryption, whereas the optional
* switch "-e" entails encryption.
*
* The argument "key-string" is required to contain at least
* two characters, and will be truncated at 32 characters.
* The program reads from STDIN and writes to STDOUT.
*
* Of technical reasons, the encrypted output will be increased
* to a size of the nearest multiple of 16. Likewise, any decrypted
* output will be padded with NUL until the same size condition holds.
*/

#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;unistd.h&gt;

#include &lt;twofish.h&gt;

#define MIN_KEYLEN 2

int main(int argc, char * argv[]) {
	size_t keylen;
	int shift = 1, encrypt = 1;
	Twofish_Byte key[32];
	Twofish_key xkey;
	Twofish_Byte inblock[16], outblock[16];

	memset(key, 0, sizeof(key));

	if (argc &lt; 2)
		return 1; /* No key is possible.  */

	if (strcmp(argv[1], "-d") == 0)
		encrypt = 0;
	else if (strcmp(argv[1], "-e") != 0)
		shift = 0;

	if (argc - shift &lt; 2)
		return 1; /* No key is possible.  */

	keylen = strlen(argv[1 + shift]);

	if (keylen &lt; MIN_KEYLEN) {
		fprintf(stderr, "Key material too short.\n");
		return 1;
	}

	if (keylen &gt; sizeof(key))
		keylen = sizeof(key);

	Twofish_initialise();

	strncpy((char *) key, argv[1 + shift], sizeof(key));

	memset(inblock, 0, sizeof(inblock));

	Twofish_prepare_key(key, keylen, &amp;xkey);

	while (read(STDIN_FILENO, inblock, sizeof(inblock)) &gt; 0) {
		if (encrypt)
			Twofish_encrypt(&amp;xkey, inblock, outblock);
		else
			Twofish_decrypt(&amp;xkey, inblock, outblock);

		write(STDOUT_FILENO, outblock, sizeof(outblock));

		memset(inblock, 0, sizeof(inblock));
	}

	return 0;
}
		</programlisting>
	</refsect1>
	<refsect1>
		<title>Author</title>
		<para>
			This text was written by &namn; for the &debian; system,
			but may be used by others. It is mainly collected from the
			source header file <filename>twofish.h</filename>.
			Permission is granted to copy, distribute and/or modify this
			document under the same terms as
			<systemitem class="library">&lib;</systemitem>
			itself.
		</para>
	</refsect1>
</refentry>

</reference>

</part>