1 |
.TH MCRYPT 3 "17 Oct 1999" |
2 |
.SH NAME |
3 |
libmcrypt \- encryption/decryption library |
4 |
.SH SYNOPSIS |
5 |
[see also |
6 |
.I mcrypt-nm.h |
7 |
for more information] |
8 |
.SH DESCRIPTION |
9 |
The |
10 |
.I libmcrypt |
11 |
is a data encryption library. |
12 |
The library is thread safe and provides encryption and decryption functions. |
13 |
This version of the library supports many encryption algorithms and encryption |
14 |
modes. Some algorithms which are supported: |
15 |
TWOFISH, SERPENT, RIJNDAEL, 3DES, GOST, SAFER+, CAST-256, |
16 |
TWOFISH, IDEA and RC6 (for RC6 and IDEA read the README.nonfree |
17 |
included in the distribution). Check mcrypt-nm.h for a full list of the algorithms. |
18 |
.LP |
19 |
OFB, CBC, ECB, nOFB and CFB are the modes that all algorithms may function. |
20 |
ECB and CBC encrypt in blocks but CFB and OFB in bytes (8bits). Note that |
21 |
CFB and OFB in the rest of the document represent the "8bit CFB or OFB" mode. |
22 |
nOFB mode represents a n-bit OFB mode, n is used to represent the |
23 |
algorithm's block size. |
24 |
The library supports an extra STREAM mode to include some stream algorithms |
25 |
like RC4. |
26 |
|
27 |
.LP |
28 |
Encryption can be done as follows: |
29 |
|
30 |
A call to function |
31 |
|
32 |
.B int mcrypt_generic_init( const int mode, |
33 |
.B const int algorithm, |
34 |
.B void *key, |
35 |
.B int lenofkey, |
36 |
.B void *IV); |
37 |
|
38 |
This function initializes all buffers for the specified algorithm and |
39 |
mode. Mode and algorithm should be one of the defined values in mcrypt-nm.h. |
40 |
The length of the key should be the one obtained by mcrypt_get_key_size(), |
41 |
you shouldn't use a smaller key. The IV should have the size of the |
42 |
algorithms block size (obtained by mcrypt_get_block_size()). IV is ignored in ECB and STREAM modes |
43 |
and should exist in CBC mode. It MUST exist in CFB, nOFB and OFB modes. It needs to be random and |
44 |
unique (but not secret). Normally it returns a thread descriptor (nothing to |
45 |
do with posix threads), or (-1) on error. |
46 |
|
47 |
To encrypt now call: |
48 |
|
49 |
.B int mcrypt_generic( MCRYPT td, void *plaintext, int len); |
50 |
|
51 |
This is the main encryption function. td is the thread descriptor |
52 |
returned by mcrypt_generic_init(). Plaintext is the plaintext you |
53 |
wish to encrypt and len should be the length (in bytes) of the |
54 |
plaintext and it should be k*algorithms_block_size if used in a mode |
55 |
which operated in blocks (cbc, ecb, nofb), or whatever when used in |
56 |
cfb or ofb which operate in streams. The plaintext is replaced by the |
57 |
ciphertext. |
58 |
|
59 |
To decrypt you can call: |
60 |
|
61 |
.B int mdecrypt_generic( MCRYPT td, void *ciphertext, int len); |
62 |
|
63 |
The decryption function. It is almost the same with mcrypt_generic. |
64 |
|
65 |
When you're finished you should call: |
66 |
|
67 |
.B int mcrypt_generic_end( const MCRYPT td); |
68 |
|
69 |
This function terminates encryption specified by the thread descriptor (td). |
70 |
Actually it clears all buffers. |
71 |
Returns (-1) on error. |
72 |
|
73 |
.P |
74 |
These are some extra functions: |
75 |
|
76 |
.B int mcrypt_get_block_size( int algorithm); |
77 |
|
78 |
Returns the block size of the given algorithm in bytes. |
79 |
Algorithm should be one of the defined in mcrypt-nm.h. |
80 |
|
81 |
.B int mcrypt_get_key_size( int algorithm); |
82 |
|
83 |
Returns the key size of the given algorithm in bytes. |
84 |
|
85 |
.B char* mcrypt_get_algorithms_name( int algorithm); |
86 |
|
87 |
Returns a character array containing the name of the algorithm. |
88 |
This array is malloc'ed so it needs to be freed via free(). |
89 |
|
90 |
.B char* mcrypt_get_modes_name( int mode); |
91 |
|
92 |
Returns a character array containing the name of the mode. |
93 |
This array is malloc'ed so it needs to be freed via free(). |
94 |
|
95 |
.B int mcrypt_mode_has_iv( int mode); |
96 |
|
97 |
Returns 1 if the mode needs an IV. |
98 |
|
99 |
.LP |
100 |
Some example programs follow here (compile as "cc prog.c -lmcrypt"): |
101 |
|
102 |
.nf |
103 |
/* First example: Encrypts stdin to stdout using TWOFISH-128 and CFB */ |
104 |
|
105 |
#include <mcrypt-nm.h> |
106 |
#include <stdio.h> |
107 |
#include <stdlib.h> |
108 |
|
109 |
main() { |
110 |
|
111 |
MCRYPT td; |
112 |
int i; |
113 |
char *key; |
114 |
char password[20]; |
115 |
char block_buffer[16]; |
116 |
char *IV; |
117 |
int keysize=16; |
118 |
|
119 |
key=calloc(1, keysize); |
120 |
strcpy(password, "A_large_key"); |
121 |
|
122 |
/* The key should have been generated by a password to key transformation |
123 |
* (check libmhash for this) |
124 |
*/ |
125 |
memmove(key, password, strlen(password)); |
126 |
|
127 |
IV=malloc(mcrypt_get_block_size(MCRYPT_TWOFISH)); |
128 |
|
129 |
/* Put random data in IV. Note these are not real random data, |
130 |
* consider using /dev/random or /dev/urandom. |
131 |
*/ |
132 |
|
133 |
/* srand(time(0)); */ |
134 |
for (i=0; i< mcrypt_get_block_size(MCRYPT_TWOFISH); i++) { |
135 |
IV[i]=rand(); |
136 |
} |
137 |
|
138 |
td=mcrypt_generic_init(MCRYPT_CFB, MCRYPT_TWOFISH, key, keysize, IV); |
139 |
|
140 |
/* Encryption in CFB is performed in bytes */ |
141 |
while ( fread (block_buffer, 1, 1, stdin) == 1 ) { |
142 |
mcrypt_generic (td, block_buffer, 1); |
143 |
|
144 |
/* Comment above and uncomment this to decrypt */ |
145 |
/* mdecrypt_generic (td, block_buffer, 1); */ |
146 |
|
147 |
fwrite ( block_buffer, 1, 1, stdout); |
148 |
} |
149 |
mcrypt_generic_end(td); |
150 |
|
151 |
return 0; |
152 |
|
153 |
} |
154 |
|
155 |
|
156 |
/* Second Example: encrypts using CBC and TWOFISH-192 */ |
157 |
|
158 |
#include <mcrypt-nm.h> |
159 |
#include <stdio.h> |
160 |
#include <stdlib.h> |
161 |
|
162 |
main() { |
163 |
|
164 |
MCRYPT td; |
165 |
int i; |
166 |
char *key; /* created using gen_key */ |
167 |
char *block_buffer; |
168 |
char *IV; |
169 |
int blocksize = mcrypt_get_block_size(MCRYPT_TWOFISH); |
170 |
|
171 |
block_buffer = malloc(blocksize); |
172 |
key = calloc(1, 24); |
173 |
strcpy(key, "A_large_and_random_key"); |
174 |
|
175 |
IV=malloc(blocksize); |
176 |
|
177 |
/* Put random data in IV. Note these are not real random data, |
178 |
* consider using /dev/random or /dev/urandom. |
179 |
*/ |
180 |
|
181 |
/* srand(time(0)); */ |
182 |
for (i=0; i < blocksize; i++) { |
183 |
IV[i]=rand(); |
184 |
} |
185 |
|
186 |
td=mcrypt_generic_init (MCRYPT_CBC, MCRYPT_TWOFISH, key, 24, IV); |
187 |
|
188 |
/* Encryption in CBC is performed in blocks */ |
189 |
while ( fread (block_buffer, 1, blocksize, stdin) == blocksize ) { |
190 |
mcrypt_generic (td, block_buffer, blocksize); |
191 |
/* mdecrypt_generic (td, block_buffer, blocksize); */ |
192 |
fwrite ( block_buffer, 1, blocksize, stdout); |
193 |
} |
194 |
mcrypt_generic_end (td); |
195 |
|
196 |
return 0; |
197 |
|
198 |
} |
199 |
.fi |
200 |
|
201 |
.LP |
202 |
The library does not install any signal handler. |
203 |
.LP |
204 |
Questions about libmcrypt should be sent to: |
205 |
.IP |
206 |
mcrypt-dev@argeas.cs-net.gr |
207 |
or, if this fails, to the author addresses given below. |
208 |
The mcrypt home page is: |
209 |
.IP |
210 |
http://mcrypt.hellug.gr |
211 |
.LP |
212 |
.SH AUTHORS |
213 |
Version nm-1.0.0 |
214 |
Copyright (C) 1998-1999 Nikos Mavroyanopoulos (nmav@hellug.gr). |
215 |
.LP |
216 |
Thanks to all the people who reported problems and suggested various |
217 |
improvements for mcrypt; who are too numerous to cite here. |
218 |
.LP |
219 |
.\" end of man page |