1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
'\" t
.\" Title: libtwofish
.\" Author: Mats Erik Andersson
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: October 20th, 2010
.\" Manual: twofish
.\" Source: twofish 0.3
.\" Language: English
.\"
.TH "LIBTWOFISH" "3" "October 20th, 2010" "twofish 0\&.3" "twofish"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
libtwofish \- Cryptographic library using the twofish algorithm\&.
.SH "DESCRIPTION"
.PP
\fBlibtwofish\fR
is a small library to encrypt and decrypt data using the Twofish cryptographic algorithm\&.
.SH "FUNCTIONS"
.HP \w'void\ Twofish_initialise('u
.BI "void Twofish_initialise(void);"
.PP
Initialise the Twofish crypto engine\&.
.PP
This function
\fImust\fR
be called before any other function in the Twofish implementation is called upon\&. The call needs only be made once in each application program\&.
.PP
Apart from initialising the engine, the call also performs a self test\&.
.HP \w'void\ Twofish_prepare_key('u
.BI "void Twofish_prepare_key(Twofish_Byte\ " "key[]" ", int\ " "key_len" ", Twofish_key\ *" "xkey" ");"
.PP
Convert a cipher key to the internal form used for encryption and decryption\&.
.PP
The cipher
\fIkey\fR
is an array of bytes\&. The type Twofish_Byte is internally defined to a type suitable for your platform\&.
.PP
Any key must be converted to the internal representation
\fIxkey\fR
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\&.
.PP
Be sure to wipe all key storage, including the Twofish_key structure, once you are done with the key data\&. A simple call
.sp
.if n \{\
.RS 4
.\}
.nf
memset(xkey, 0, sizeof(Twofish_key));
.fi
.if n \{\
.RE
.\}
.sp
will do just fine\&.
.PP
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\&.
.PP
The key length argument
\fIkey_len\fR
must be in the proper range\&. If
\fIkey_len\fR
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\&.
.HP \w'void\ Twofish_encrypt('u
.BI "void Twofish_encrypt(Twofish_key\ *" "xkey" ", Twofish_Byte\ " "plain[16]" ", Twofish_Byte\ " "crypto[16]" ");"
.PP
Encrypt a single block of data\&.
.PP
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\&.
.PP
The xkey structure is not modified by this routine, and can be used for further encryption and decryption operations\&.
.HP \w'void\ Twofish_decrypt('u
.BI "void Twofish_decrypt(Twofish_key\ *" "xkey" ", Twofish_Byte\ " "crypto[16]" ", Twofish_Byte\ " "plain[16]" ");"
.PP
Decrypt a single block of data\&.
.PP
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\&.
.PP
The xkey structure is not modified by this routine, and can be used for further encryption and decryption operations\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
/*
* catwo\&.c
*
* A simple\-minded encryptor and decryptor application\&.
*
* Usage: catwo {[\-e] | \-d} key\-string < infile > 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 <stdio\&.h>
#include <string\&.h>
#include <stdlib\&.h>
#include <unistd\&.h>
#include <twofish\&.h>
#define MIN_KEYLEN 2
int main(int argc, char * argv[]) {
int 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 < 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 < 2)
return 1; /* No key is possible\&. */
keylen = strlen(argv[1 + shift]);
if (keylen < MIN_KEYLEN) {
fprintf(stderr, "Key material too short\&.\en");
return 1;
}
if (keylen > sizeof(key))
keylen = sizeof(key);
Twofish_initialise();
strncpy(key, argv[1 + shift], sizeof(key));
memset(inblock, 0, sizeof(inblock));
Twofish_prepare_key(key, keylen, &xkey);
while (read(STDIN_FILENO, inblock, sizeof(inblock)) > 0) {
if (encrypt)
Twofish_encrypt(&xkey, inblock, outblock);
else
Twofish_decrypt(&xkey, inblock, outblock);
write(STDOUT_FILENO, outblock, sizeof(outblock));
memset(inblock, 0, sizeof(inblock));
}
return 0;
}
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.PP
This text was written by Mats Erik Andersson for the
Debian GNU/Linux
system, but may be used by others\&. It is mainly collected from the source header file
twofish\&.h\&. Permission is granted to copy, distribute and/or modify this document under the same terms as
libtwofish
itself\&.
.SH "AUTHOR"
.PP
\fBMats Erik Andersson\fR
.RS 4
Author.
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2010 Mats Erik Andersson
.br
|