Remove redundant declaration.
[openssl.git] / crypto / des / des.pod
1 =pod
2
3 =head1 NAME
4
5 des - encrypt or decrypt data using Data Encryption Standard
6
7 =head1 SYNOPSIS
8
9 B<des>
10 (
11 B<-e>
12 |
13 B<-E>
14 ) | (
15 B<-d>
16 |
17 B<-D>
18 ) | (
19 B<->[B<cC>][B<ckname>]
20 ) |
21 [
22 B<-b3hfs>
23 ] [
24 B<-k>
25 I<key>
26 ]
27 ] [
28 B<-u>[I<uuname>]
29 [
30 I<input-file>
31 [
32 I<output-file>
33 ] ]
34
35 =head1 NOTE
36
37 This page describes the B<des> stand-alone program, not the B<openssl des>
38 command.
39
40 =head1 DESCRIPTION
41
42 B<des>
43 encrypts and decrypts data using the
44 Data Encryption Standard algorithm.
45 One of
46 B<-e>, B<-E>
47 (for encrypt) or
48 B<-d>, B<-D>
49 (for decrypt) must be specified.
50 It is also possible to use
51 B<-c>
52 or
53 B<-C>
54 in conjunction or instead of the a encrypt/decrypt option to generate
55 a 16 character hexadecimal checksum, generated via the
56 I<des_cbc_cksum>.
57
58 Two standard encryption modes are supported by the
59 B<des>
60 program, Cipher Block Chaining (the default) and Electronic Code Book
61 (specified with
62 B<-b>).
63
64 The key used for the DES
65 algorithm is obtained by prompting the user unless the
66 B<-k>
67 I<key>
68 option is given.
69 If the key is an argument to the
70 B<des>
71 command, it is potentially visible to users executing
72 ps(1)
73 or a derivative.  To minimise this possibility,
74 B<des>
75 takes care to destroy the key argument immediately upon entry.
76 If your shell keeps a history file be careful to make sure it is not
77 world readable.
78
79 Since this program attempts to maintain compatibility with sunOS's
80 des(1) command, there are 2 different methods used to convert the user
81 supplied key to a des key.
82 Whenever and one or more of
83 B<-E>, B<-D>, B<-C>
84 or
85 B<-3>
86 options are used, the key conversion procedure will not be compatible
87 with the sunOS des(1) version but will use all the user supplied
88 character to generate the des key.
89 B<des>
90 command reads from standard input unless
91 I<input-file>
92 is specified and writes to standard output unless
93 I<output-file>
94 is given.
95
96 =head1 OPTIONS
97
98 =over 4
99
100 =item B<-b>
101
102 Select ECB
103 (eight bytes at a time) encryption mode.
104
105 =item B<-3>
106
107 Encrypt using triple encryption.
108 By default triple cbc encryption is used but if the
109 B<-b>
110 option is used then triple ECB encryption is performed.
111 If the key is less than 8 characters long, the flag has no effect.
112
113 =item B<-e>
114
115 Encrypt data using an 8 byte key in a manner compatible with sunOS
116 des(1).
117
118 =item B<-E>
119
120 Encrypt data using a key of nearly unlimited length (1024 bytes).
121 This will product a more secure encryption.
122
123 =item B<-d>
124
125 Decrypt data that was encrypted with the B<-e> option.
126
127 =item B<-D>
128
129 Decrypt data that was encrypted with the B<-E> option.
130
131 =item B<-c>
132
133 Generate a 16 character hexadecimal cbc checksum and output this to
134 stderr.
135 If a filename was specified after the
136 B<-c>
137 option, the checksum is output to that file.
138 The checksum is generated using a key generated in a sunOS compatible
139 manner.
140
141 =item B<-C>
142
143 A cbc checksum is generated in the same manner as described for the
144 B<-c>
145 option but the DES key is generated in the same manner as used for the
146 B<-E>
147 and
148 B<-D>
149 options
150
151 =item B<-f>
152
153 Does nothing - allowed for compatibility with sunOS des(1) command.
154
155 =item B<-s>
156
157 Does nothing - allowed for compatibility with sunOS des(1) command.
158
159 =item B<-k> I<key>
160
161 Use the encryption 
162 I<key>
163 specified.
164
165 =item B<-h>
166
167 The
168 I<key>
169 is assumed to be a 16 character hexadecimal number.
170 If the
171 B<-3>
172 option is used the key is assumed to be a 32 character hexadecimal
173 number.
174
175 =item B<-u>
176
177 This flag is used to read and write uuencoded files.  If decrypting,
178 the input file is assumed to contain uuencoded, DES encrypted data.
179 If encrypting, the characters following the B<-u> are used as the name of
180 the uuencoded file to embed in the begin line of the uuencoded
181 output.  If there is no name specified after the B<-u>, the name text.des
182 will be embedded in the header.
183
184 =head1 SEE ALSO
185
186 ps(1),
187 L<des_crypt(3)|des_crypt(3)>
188
189 =head1 BUGS
190
191 The problem with using the
192 B<-e>
193 option is the short key length.
194 It would be better to use a real 56-bit key rather than an
195 ASCII-based 56-bit pattern.  Knowing that the key was derived from ASCII
196 radically reduces the time necessary for a brute-force cryptographic attack.
197 My attempt to remove this problem is to add an alternative text-key to
198 DES-key function.  This alternative function (accessed via
199 B<-E>, B<-D>, B<-S>
200 and
201 B<-3>)
202 uses DES to help generate the key.
203
204 Be carefully when using the B<-u> option.  Doing B<des -ud> I<filename> will
205 not decrypt filename (the B<-u> option will gobble the B<-d> option).
206
207 The VMS operating system operates in a world where files are always a
208 multiple of 512 bytes.  This causes problems when encrypted data is
209 send from Unix to VMS since a 88 byte file will suddenly be padded
210 with 424 null bytes.  To get around this problem, use the B<-u> option
211 to uuencode the data before it is send to the VMS system.
212
213 =head1 AUTHOR
214
215 Eric Young (eay@cryptsoft.com)
216
217 =cut