Add -show_chain option to print out verified chain.
[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 =back
185
186 =head1 SEE ALSO
187
188 ps(1),
189 L<des_crypt(3)|des_crypt(3)>
190
191 =head1 BUGS
192
193 The problem with using the
194 B<-e>
195 option is the short key length.
196 It would be better to use a real 56-bit key rather than an
197 ASCII-based 56-bit pattern.  Knowing that the key was derived from ASCII
198 radically reduces the time necessary for a brute-force cryptographic attack.
199 My attempt to remove this problem is to add an alternative text-key to
200 DES-key function.  This alternative function (accessed via
201 B<-E>, B<-D>, B<-S>
202 and
203 B<-3>)
204 uses DES to help generate the key.
205
206 Be carefully when using the B<-u> option.  Doing B<des -ud> I<filename> will
207 not decrypt filename (the B<-u> option will gobble the B<-d> option).
208
209 The VMS operating system operates in a world where files are always a
210 multiple of 512 bytes.  This causes problems when encrypted data is
211 send from Unix to VMS since a 88 byte file will suddenly be padded
212 with 424 null bytes.  To get around this problem, use the B<-u> option
213 to uuencode the data before it is send to the VMS system.
214
215 =head1 AUTHOR
216
217 Eric Young (eay@cryptsoft.com)
218
219 =cut