]>
Commit | Line | Data |
---|---|---|
a0e9f529 | 1 | =pod |
19d2bb57 | 2 | |
a0e9f529 DSH |
3 | =head1 NAME |
4 | ||
5 | enc - symmetric cipher routines | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl enc -ciphername> | |
10 | [B<-in filename>] | |
11 | [B<-out filename>] | |
cd3c54e5 | 12 | [B<-pass arg>] |
a0e9f529 DSH |
13 | [B<-e>] |
14 | [B<-d>] | |
15 | [B<-a>] | |
16 | [B<-A>] | |
17 | [B<-k password>] | |
18 | [B<-kfile filename>] | |
19 | [B<-K key>] | |
20 | [B<-iv IV>] | |
21 | [B<-p>] | |
22 | [B<-P>] | |
23 | [B<-bufsize number>] | |
f2e5ca84 | 24 | [B<-nopad>] |
a0e9f529 DSH |
25 | [B<-debug>] |
26 | ||
27 | =head1 DESCRIPTION | |
28 | ||
19d2bb57 | 29 | The symmetric cipher commands allow data to be encrypted or decrypted |
a0e9f529 DSH |
30 | using various block and stream ciphers using keys based on passwords |
31 | or explicitly provided. Base64 encoding or decoding can also be performed | |
32 | either by itself or in addition to the encryption or decryption. | |
33 | ||
34 | =head1 OPTIONS | |
35 | ||
36 | =over 4 | |
37 | ||
38 | =item B<-in filename> | |
39 | ||
40 | the input filename, standard input by default. | |
41 | ||
42 | =item B<-out filename> | |
43 | ||
44 | the output filename, standard output by default. | |
45 | ||
cd3c54e5 DSH |
46 | =item B<-pass arg> |
47 | ||
48 | the password source. For more information about the format of B<arg> | |
49 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. | |
50 | ||
fd699ac5 DSH |
51 | =item B<-salt> |
52 | ||
53 | use a salt in the key derivation routines. This option should B<ALWAYS> | |
19d2bb57 | 54 | be used unless compatibility with previous versions of OpenSSL or SSLeay |
fd699ac5 DSH |
55 | is required. This option is only present on OpenSSL versions 0.9.5 or |
56 | above. | |
57 | ||
58 | =item B<-nosalt> | |
59 | ||
60 | don't use a salt in the key derivation routines. This is the default for | |
19d2bb57 | 61 | compatibility with previous versions of OpenSSL and SSLeay. |
fd699ac5 | 62 | |
a0e9f529 DSH |
63 | =item B<-e> |
64 | ||
65 | encrypt the input data: this is the default. | |
66 | ||
67 | =item B<-d> | |
68 | ||
69 | decrypt the input data. | |
70 | ||
71 | =item B<-a> | |
72 | ||
73 | base64 process the data. This means that if encryption is taking place | |
74 | the data is base64 encoded after encryption. If decryption is set then | |
75 | the input data is base64 decoded before being decrypted. | |
76 | ||
77 | =item B<-A> | |
78 | ||
79 | if the B<-a> option is set then base64 process the data on one line. | |
80 | ||
81 | =item B<-k password> | |
82 | ||
cd3c54e5 DSH |
83 | the password to derive the key from. This is for compatibility with previous |
84 | versions of OpenSSL. Superseded by the B<-pass> argument. | |
a0e9f529 DSH |
85 | |
86 | =item B<-kfile filename> | |
87 | ||
cd3c54e5 DSH |
88 | read the password to derive the key from the first line of B<filename>. |
89 | This is for computability with previous versions of OpenSSL. Superseded by | |
90 | the B<-pass> argument. | |
a0e9f529 | 91 | |
fd699ac5 DSH |
92 | =item B<-S salt> |
93 | ||
94 | the actual salt to use: this must be represented as a string comprised only | |
95 | of hex digits. | |
96 | ||
a0e9f529 DSH |
97 | =item B<-K key> |
98 | ||
99 | the actual key to use: this must be represented as a string comprised only | |
43f9391b LJ |
100 | of hex digits. If only the key is specified, the IV must additionally specified |
101 | using the B<-iv> option. When both a key and a password are specified, the | |
102 | key given with the B<-K> option will be used and the IV generated from the | |
103 | password will be taken. It probably does not make much sense to specify | |
104 | both key and password. | |
a0e9f529 DSH |
105 | |
106 | =item B<-iv IV> | |
107 | ||
108 | the actual IV to use: this must be represented as a string comprised only | |
43f9391b LJ |
109 | of hex digits. When only the key is specified using the B<-K> option, the |
110 | IV must explicitly be defined. When a password is being specified using | |
111 | one of the other options, the IV is generated from this password. | |
a0e9f529 DSH |
112 | |
113 | =item B<-p> | |
114 | ||
115 | print out the key and IV used. | |
116 | ||
117 | =item B<-P> | |
118 | ||
119 | print out the key and IV used then immediately exit: don't do any encryption | |
120 | or decryption. | |
121 | ||
122 | =item B<-bufsize number> | |
123 | ||
124 | set the buffer size for I/O | |
125 | ||
f2e5ca84 DSH |
126 | =item B<-nopad> |
127 | ||
128 | disable standard block padding | |
129 | ||
a0e9f529 DSH |
130 | =item B<-debug> |
131 | ||
132 | debug the BIOs used for I/O. | |
133 | ||
134 | =back | |
135 | ||
136 | =head1 NOTES | |
137 | ||
138 | The program can be called either as B<openssl ciphername> or | |
139 | B<openssl enc -ciphername>. | |
140 | ||
141 | A password will be prompted for to derive the key and IV if necessary. | |
142 | ||
6d1b637b | 143 | The B<-salt> option should B<ALWAYS> be used if the key is being derived |
19d2bb57 | 144 | from a password unless you want compatibility with previous versions of |
6d1b637b | 145 | OpenSSL and SSLeay. |
fd699ac5 DSH |
146 | |
147 | Without the B<-salt> option it is possible to perform efficient dictionary | |
148 | attacks on the password and to attack stream cipher encrypted data. The reason | |
149 | for this is that without the salt the same password always generates the same | |
150 | encryption key. When the salt is being used the first eight bytes of the | |
151 | encrypted data are reserved for the salt: it is generated at random when | |
152 | encrypting a file and read from the encrypted file when it is decrypted. | |
153 | ||
4abc5c62 DSH |
154 | Some of the ciphers do not have large keys and others have security |
155 | implications if not used correctly. A beginner is advised to just use | |
156 | a strong block cipher in CBC mode such as bf or des3. | |
157 | ||
f2e5ca84 | 158 | All the block ciphers normally use PKCS#5 padding also known as standard block |
a0e9f529 DSH |
159 | padding: this allows a rudimentary integrity or password check to be |
160 | performed. However since the chance of random data passing the test is | |
161 | better than 1 in 256 it isn't a very good test. | |
162 | ||
3b80e3aa | 163 | If padding is disabled then the input data must be a multiple of the cipher |
f2e5ca84 DSH |
164 | block length. |
165 | ||
a0e9f529 DSH |
166 | All RC2 ciphers have the same key and effective key length. |
167 | ||
168 | Blowfish and RC5 algorithms use a 128 bit key. | |
169 | ||
170 | =head1 SUPPORTED CIPHERS | |
171 | ||
172 | base64 Base 64 | |
173 | ||
174 | bf-cbc Blowfish in CBC mode | |
175 | bf Alias for bf-cbc | |
19d2bb57 | 176 | bf-cfb Blowfish in CFB mode |
a0e9f529 DSH |
177 | bf-ecb Blowfish in ECB mode |
178 | bf-ofb Blowfish in OFB mode | |
179 | ||
180 | cast-cbc CAST in CBC mode | |
181 | cast Alias for cast-cbc | |
182 | cast5-cbc CAST5 in CBC mode | |
183 | cast5-cfb CAST5 in CFB mode | |
184 | cast5-ecb CAST5 in ECB mode | |
185 | cast5-ofb CAST5 in OFB mode | |
186 | ||
187 | des-cbc DES in CBC mode | |
188 | des Alias for des-cbc | |
189 | des-cfb DES in CBC mode | |
190 | des-ofb DES in OFB mode | |
191 | des-ecb DES in ECB mode | |
192 | ||
193 | des-ede-cbc Two key triple DES EDE in CBC mode | |
194 | des-ede Alias for des-ede | |
195 | des-ede-cfb Two key triple DES EDE in CFB mode | |
196 | des-ede-ofb Two key triple DES EDE in OFB mode | |
197 | ||
198 | des-ede3-cbc Three key triple DES EDE in CBC mode | |
199 | des-ede3 Alias for des-ede3-cbc | |
200 | des3 Alias for des-ede3-cbc | |
201 | des-ede3-cfb Three key triple DES EDE CFB mode | |
202 | des-ede3-ofb Three key triple DES EDE in OFB mode | |
203 | ||
204 | desx DESX algorithm. | |
205 | ||
206 | idea-cbc IDEA algorithm in CBC mode | |
207 | idea same as idea-cbc | |
208 | idea-cfb IDEA in CFB mode | |
209 | idea-ecb IDEA in ECB mode | |
210 | idea-ofb IDEA in OFB mode | |
211 | ||
212 | rc2-cbc 128 bit RC2 in CBC mode | |
213 | rc2 Alias for rc2-cbc | |
214 | rc2-cfb 128 bit RC2 in CBC mode | |
215 | rc2-ecb 128 bit RC2 in CBC mode | |
216 | rc2-ofb 128 bit RC2 in CBC mode | |
217 | rc2-64-cbc 64 bit RC2 in CBC mode | |
218 | rc2-40-cbc 40 bit RC2 in CBC mode | |
219 | ||
220 | rc4 128 bit RC4 | |
221 | rc4-64 64 bit RC4 | |
222 | rc4-40 40 bit RC4 | |
223 | ||
224 | rc5-cbc RC5 cipher in CBC mode | |
225 | rc5 Alias for rc5-cbc | |
226 | rc5-cfb RC5 cipher in CBC mode | |
227 | rc5-ecb RC5 cipher in CBC mode | |
228 | rc5-ofb RC5 cipher in CBC mode | |
229 | ||
230 | =head1 EXAMPLES | |
231 | ||
4abc5c62 DSH |
232 | Just base64 encode a binary file: |
233 | ||
234 | openssl base64 -in file.bin -out file.b64 | |
235 | ||
236 | Decode the same file | |
237 | ||
238 | openssl base64 -d -in file.b64 -out file.bin | |
239 | ||
240 | Encrypt a file using triple DES in CBC mode using a prompted password: | |
241 | ||
fd699ac5 | 242 | openssl des3 -salt -in file.txt -out file.des3 |
4abc5c62 DSH |
243 | |
244 | Decrypt a file using a supplied password: | |
245 | ||
fd699ac5 | 246 | openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword |
4abc5c62 DSH |
247 | |
248 | Encrypt a file then base64 encode it (so it can be sent via mail for example) | |
249 | using Blowfish in CBC mode: | |
250 | ||
fd699ac5 | 251 | openssl bf -a -salt -in file.txt -out file.bf |
4abc5c62 DSH |
252 | |
253 | Base64 decode a file then decrypt it: | |
254 | ||
fd699ac5 | 255 | openssl bf -d -salt -a -in file.bf -out file.txt |
4abc5c62 DSH |
256 | |
257 | Decrypt some data using a supplied 40 bit RC4 key: | |
258 | ||
259 | openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 | |
a0e9f529 DSH |
260 | |
261 | =head1 BUGS | |
262 | ||
263 | The B<-A> option when used with large files doesn't work properly. | |
264 | ||
fd699ac5 | 265 | There should be an option to allow an iteration count to be included. |
a0e9f529 | 266 | |
f2e5ca84 DSH |
267 | The B<enc> program only supports a fixed number of algorithms with |
268 | certain parameters. So if, for example, you want to use RC2 with a | |
269 | 76 bit key or RC4 with an 84 bit key you can't use this program. | |
a0e9f529 DSH |
270 | |
271 | =cut |