Initial import from FreeBSD RELENG_4:
[dragonfly.git] / secure / usr.bin / openssl / man / enc.1
CommitLineData
984263bc
MD
1.\" Automatically generated by Pod::Man version 1.15
2.\" Wed Feb 19 16:49:33 2003
3.\"
4.\" Standard preamble:
5.\" ======================================================================
6.de Sh \" Subsection heading
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
14.de Sp \" Vertical space (when we can't use .PP)
15.if t .sp .5v
16.if n .sp
17..
18.de Ip \" List item
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
24.de Vb \" Begin verbatim text
25.ft CW
26.nf
27.ne \\$1
28..
29.de Ve \" End verbatim text
30.ft R
31
32.fi
33..
34.\" Set up some character translations and predefined strings. \*(-- will
35.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
36.\" double quote, and \*(R" will give a right double quote. | will give a
37.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
38.\" to do unbreakable dashes and therefore won't be available. \*(C` and
39.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
40.tr \(*W-|\(bv\*(Tr
41.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
42.ie n \{\
43. ds -- \(*W-
44. ds PI pi
45. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
46. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47. ds L" ""
48. ds R" ""
49. ds C` ""
50. ds C' ""
51'br\}
52.el\{\
53. ds -- \|\(em\|
54. ds PI \(*p
55. ds L" ``
56. ds R" ''
57'br\}
58.\"
59.\" If the F register is turned on, we'll generate index entries on stderr
60.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
61.\" index entries marked with X<> in POD. Of course, you'll have to process
62.\" the output yourself in some meaningful fashion.
63.if \nF \{\
64. de IX
65. tm Index:\\$1\t\\n%\t"\\$2"
66..
67. nr % 0
68. rr F
69.\}
70.\"
71.\" For nroff, turn off justification. Always turn off hyphenation; it
72.\" makes way too many mistakes in technical documents.
73.hy 0
74.if n .na
75.\"
76.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
77.\" Fear. Run. Save yourself. No user-serviceable parts.
78.bd B 3
79. \" fudge factors for nroff and troff
80.if n \{\
81. ds #H 0
82. ds #V .8m
83. ds #F .3m
84. ds #[ \f1
85. ds #] \fP
86.\}
87.if t \{\
88. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89. ds #V .6m
90. ds #F 0
91. ds #[ \&
92. ds #] \&
93.\}
94. \" simple accents for nroff and troff
95.if n \{\
96. ds ' \&
97. ds ` \&
98. ds ^ \&
99. ds , \&
100. ds ~ ~
101. ds /
102.\}
103.if t \{\
104. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
105. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
106. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
107. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
108. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
109. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
110.\}
111. \" troff and (daisy-wheel) nroff accents
112.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
113.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
114.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
115.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
116.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
117.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
118.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
119.ds ae a\h'-(\w'a'u*4/10)'e
120.ds Ae A\h'-(\w'A'u*4/10)'E
121. \" corrections for vroff
122.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
123.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
124. \" for low resolution devices (crt and lpr)
125.if \n(.H>23 .if \n(.V>19 \
126\{\
127. ds : e
128. ds 8 ss
129. ds o a
130. ds d- d\h'-1'\(ga
131. ds D- D\h'-1'\(hy
132. ds th \o'bp'
133. ds Th \o'LP'
134. ds ae ae
135. ds Ae AE
136.\}
137.rm #[ #] #H #V #F C
138.\" ======================================================================
139.\"
140.IX Title "ENC 1"
141.TH ENC 1 "0.9.7a" "2003-02-19" "OpenSSL"
142.UC
143.SH "NAME"
144enc \- symmetric cipher routines
145.SH "SYNOPSIS"
146.IX Header "SYNOPSIS"
147\&\fBopenssl enc \-ciphername\fR
148[\fB\-in filename\fR]
149[\fB\-out filename\fR]
150[\fB\-pass arg\fR]
151[\fB\-e\fR]
152[\fB\-d\fR]
153[\fB\-a\fR]
154[\fB\-A\fR]
155[\fB\-k password\fR]
156[\fB\-kfile filename\fR]
157[\fB\-K key\fR]
158[\fB\-iv \s-1IV\s0\fR]
159[\fB\-p\fR]
160[\fB\-P\fR]
161[\fB\-bufsize number\fR]
162[\fB\-nopad\fR]
163[\fB\-debug\fR]
164.SH "DESCRIPTION"
165.IX Header "DESCRIPTION"
166The symmetric cipher commands allow data to be encrypted or decrypted
167using various block and stream ciphers using keys based on passwords
168or explicitly provided. Base64 encoding or decoding can also be performed
169either by itself or in addition to the encryption or decryption.
170.SH "OPTIONS"
171.IX Header "OPTIONS"
172.Ip "\fB\-in filename\fR" 4
173.IX Item "-in filename"
174the input filename, standard input by default.
175.Ip "\fB\-out filename\fR" 4
176.IX Item "-out filename"
177the output filename, standard output by default.
178.Ip "\fB\-pass arg\fR" 4
179.IX Item "-pass arg"
180the password source. For more information about the format of \fBarg\fR
181see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
182.Ip "\fB\-salt\fR" 4
183.IX Item "-salt"
184use a salt in the key derivation routines. This option should \fB\s-1ALWAYS\s0\fR
185be used unless compatibility with previous versions of OpenSSL or SSLeay
186is required. This option is only present on OpenSSL versions 0.9.5 or
187above.
188.Ip "\fB\-nosalt\fR" 4
189.IX Item "-nosalt"
190don't use a salt in the key derivation routines. This is the default for
191compatibility with previous versions of OpenSSL and SSLeay.
192.Ip "\fB\-e\fR" 4
193.IX Item "-e"
194encrypt the input data: this is the default.
195.Ip "\fB\-d\fR" 4
196.IX Item "-d"
197decrypt the input data.
198.Ip "\fB\-a\fR" 4
199.IX Item "-a"
200base64 process the data. This means that if encryption is taking place
201the data is base64 encoded after encryption. If decryption is set then
202the input data is base64 decoded before being decrypted.
203.Ip "\fB\-A\fR" 4
204.IX Item "-A"
205if the \fB\-a\fR option is set then base64 process the data on one line.
206.Ip "\fB\-k password\fR" 4
207.IX Item "-k password"
208the password to derive the key from. This is for compatibility with previous
209versions of OpenSSL. Superseded by the \fB\-pass\fR argument.
210.Ip "\fB\-kfile filename\fR" 4
211.IX Item "-kfile filename"
212read the password to derive the key from the first line of \fBfilename\fR.
213This is for computability with previous versions of OpenSSL. Superseded by
214the \fB\-pass\fR argument.
215.Ip "\fB\-S salt\fR" 4
216.IX Item "-S salt"
217the actual salt to use: this must be represented as a string comprised only
218of hex digits.
219.Ip "\fB\-K key\fR" 4
220.IX Item "-K key"
221the actual key to use: this must be represented as a string comprised only
222of hex digits. If only the key is specified, the \s-1IV\s0 must additionally specified
223using the \fB\-iv\fR option. When both a key and a password are specified, the
224key given with the \fB\-K\fR option will be used and the \s-1IV\s0 generated from the
225password will be taken. It probably does not make much sense to specify
226both key and password.
227.Ip "\fB\-iv \s-1IV\s0\fR" 4
228.IX Item "-iv IV"
229the actual \s-1IV\s0 to use: this must be represented as a string comprised only
230of hex digits. When only the key is specified using the \fB\-K\fR option, the
231\&\s-1IV\s0 must explicitly be defined. When a password is being specified using
232one of the other options, the \s-1IV\s0 is generated from this password.
233.Ip "\fB\-p\fR" 4
234.IX Item "-p"
235print out the key and \s-1IV\s0 used.
236.Ip "\fB\-P\fR" 4
237.IX Item "-P"
238print out the key and \s-1IV\s0 used then immediately exit: don't do any encryption
239or decryption.
240.Ip "\fB\-bufsize number\fR" 4
241.IX Item "-bufsize number"
242set the buffer size for I/O
243.Ip "\fB\-nopad\fR" 4
244.IX Item "-nopad"
245disable standard block padding
246.Ip "\fB\-debug\fR" 4
247.IX Item "-debug"
248debug the BIOs used for I/O.
249.SH "NOTES"
250.IX Header "NOTES"
251The program can be called either as \fBopenssl ciphername\fR or
252\&\fBopenssl enc \-ciphername\fR.
253.PP
254A password will be prompted for to derive the key and \s-1IV\s0 if necessary.
255.PP
256The \fB\-salt\fR option should \fB\s-1ALWAYS\s0\fR be used if the key is being derived
257from a password unless you want compatibility with previous versions of
258OpenSSL and SSLeay.
259.PP
260Without the \fB\-salt\fR option it is possible to perform efficient dictionary
261attacks on the password and to attack stream cipher encrypted data. The reason
262for this is that without the salt the same password always generates the same
263encryption key. When the salt is being used the first eight bytes of the
264encrypted data are reserved for the salt: it is generated at random when
265encrypting a file and read from the encrypted file when it is decrypted.
266.PP
267Some of the ciphers do not have large keys and others have security
268implications if not used correctly. A beginner is advised to just use
269a strong block cipher in \s-1CBC\s0 mode such as bf or des3.
270.PP
271All the block ciphers normally use PKCS#5 padding also known as standard block
272padding: this allows a rudimentary integrity or password check to be
273performed. However since the chance of random data passing the test is
274better than 1 in 256 it isn't a very good test.
275.PP
276If padding is disabled then the input data must be a multiple of the cipher
277block length.
278.PP
279All \s-1RC2\s0 ciphers have the same key and effective key length.
280.PP
281Blowfish and \s-1RC5\s0 algorithms use a 128 bit key.
282.SH "SUPPORTED CIPHERS"
283.IX Header "SUPPORTED CIPHERS"
284.Vb 1
285\& base64 Base 64
286.Ve
287.Vb 5
288\& bf-cbc Blowfish in CBC mode
289\& bf Alias for bf-cbc
290\& bf-cfb Blowfish in CFB mode
291\& bf-ecb Blowfish in ECB mode
292\& bf-ofb Blowfish in OFB mode
293.Ve
294.Vb 6
295\& cast-cbc CAST in CBC mode
296\& cast Alias for cast-cbc
297\& cast5-cbc CAST5 in CBC mode
298\& cast5-cfb CAST5 in CFB mode
299\& cast5-ecb CAST5 in ECB mode
300\& cast5-ofb CAST5 in OFB mode
301.Ve
302.Vb 5
303\& des-cbc DES in CBC mode
304\& des Alias for des-cbc
305\& des-cfb DES in CBC mode
306\& des-ofb DES in OFB mode
307\& des-ecb DES in ECB mode
308.Ve
309.Vb 4
310\& des-ede-cbc Two key triple DES EDE in CBC mode
311\& des-ede Alias for des-ede
312\& des-ede-cfb Two key triple DES EDE in CFB mode
313\& des-ede-ofb Two key triple DES EDE in OFB mode
314.Ve
315.Vb 5
316\& des-ede3-cbc Three key triple DES EDE in CBC mode
317\& des-ede3 Alias for des-ede3-cbc
318\& des3 Alias for des-ede3-cbc
319\& des-ede3-cfb Three key triple DES EDE CFB mode
320\& des-ede3-ofb Three key triple DES EDE in OFB mode
321.Ve
322.Vb 1
323\& desx DESX algorithm.
324.Ve
325.Vb 5
326\& idea-cbc IDEA algorithm in CBC mode
327\& idea same as idea-cbc
328\& idea-cfb IDEA in CFB mode
329\& idea-ecb IDEA in ECB mode
330\& idea-ofb IDEA in OFB mode
331.Ve
332.Vb 7
333\& rc2-cbc 128 bit RC2 in CBC mode
334\& rc2 Alias for rc2-cbc
335\& rc2-cfb 128 bit RC2 in CBC mode
336\& rc2-ecb 128 bit RC2 in CBC mode
337\& rc2-ofb 128 bit RC2 in CBC mode
338\& rc2-64-cbc 64 bit RC2 in CBC mode
339\& rc2-40-cbc 40 bit RC2 in CBC mode
340.Ve
341.Vb 3
342\& rc4 128 bit RC4
343\& rc4-64 64 bit RC4
344\& rc4-40 40 bit RC4
345.Ve
346.Vb 5
347\& rc5-cbc RC5 cipher in CBC mode
348\& rc5 Alias for rc5-cbc
349\& rc5-cfb RC5 cipher in CBC mode
350\& rc5-ecb RC5 cipher in CBC mode
351\& rc5-ofb RC5 cipher in CBC mode
352.Ve
353.SH "EXAMPLES"
354.IX Header "EXAMPLES"
355Just base64 encode a binary file:
356.PP
357.Vb 1
358\& openssl base64 -in file.bin -out file.b64
359.Ve
360Decode the same file
361.PP
362.Vb 1
363\& openssl base64 -d -in file.b64 -out file.bin
364.Ve
365Encrypt a file using triple \s-1DES\s0 in \s-1CBC\s0 mode using a prompted password:
366.PP
367.Vb 1
368\& openssl des3 -salt -in file.txt -out file.des3
369.Ve
370Decrypt a file using a supplied password:
371.PP
372.Vb 1
373\& openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
374.Ve
375Encrypt a file then base64 encode it (so it can be sent via mail for example)
376using Blowfish in \s-1CBC\s0 mode:
377.PP
378.Vb 1
379\& openssl bf -a -salt -in file.txt -out file.bf
380.Ve
381Base64 decode a file then decrypt it:
382.PP
383.Vb 1
384\& openssl bf -d -salt -a -in file.bf -out file.txt
385.Ve
386Decrypt some data using a supplied 40 bit \s-1RC4\s0 key:
387.PP
388.Vb 1
389\& openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
390.Ve
391.SH "BUGS"
392.IX Header "BUGS"
393The \fB\-A\fR option when used with large files doesn't work properly.
394.PP
395There should be an option to allow an iteration count to be included.
396.PP
397The \fBenc\fR program only supports a fixed number of algorithms with
398certain parameters. So if, for example, you want to use \s-1RC2\s0 with a
39976 bit key or \s-1RC4\s0 with an 84 bit key you can't use this program.