/[mcrypt]/libmcrypt-nm/doc/mcrypt-nm.3
ViewVC logotype

Contents of /libmcrypt-nm/doc/mcrypt-nm.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1.1.1 - (show annotations) (vendor branch)
Mon May 22 13:09:18 2000 UTC (23 years, 10 months ago) by nmav
Branch: MAIN, mcrypt
CVS Tags: start, HEAD
Changes since 1.1: +0 -0 lines

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

webmaster@linux.gr
ViewVC Help
Powered by ViewVC 1.1.26