| blob | 054c3d2da607962bd1c6a717db396e17d62a81e9 |
1 '\" te
2 .\" Copyright 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH ENCRYPT 1 "Dec 17, 2008"
7 .SH NAME
8 encrypt, decrypt \- encrypt or decrypt files
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/bin/encrypt\fR \fB-l\fR
13 .fi
15 .LP
16 .nf
17 \fB/usr/bin/encrypt\fR \fB-a\fR \fIalgorithm\fR [\fB-v\fR]
18 [\fB-k\fR \fIkey_file\fR | \fB-K\fR \fIkey_label\fR [\fB-T\fR \fItoken_spec\fR]]
19 [\fB-i\fR \fIinput_file\fR] [\fB-o\fR \fIoutput_file\fR]
20 .fi
22 .LP
23 .nf
24 \fB/usr/bin/decrypt\fR \fB-l\fR
25 .fi
27 .LP
28 .nf
29 \fB/usr/bin/decrypt\fR \fB-a\fR \fIalgorithm\fR [\fB-v\fR]
30 [\fB-k\fR \fIkey_file\fR | \fB-K\fR \fIkey_label\fR [\fB-T\fR \fItoken_spec\fR]]
31 [\fB-i\fR \fIinput_file\fR] [\fB-o\fR \fIoutput_file\fR]
32 .fi
34 .SH DESCRIPTION
35 .sp
36 .LP
37 This utility encrypts or decrypts the given file or stdin using the algorithm
38 specified. If no output file is specified, output is to standard out. If input
39 and output are the same file, the encrypted output is written to a temporary
40 work file in the same filesystem and then used to replace the original file.
41 .sp
42 .LP
43 On decryption, if the input and output are the same file, the cleartext
44 replaces the ciphertext file.
45 .sp
46 .LP
47 The output file of \fBencrypt\fR and the input file for \fBdecrypt\fR contains
48 the following information:
49 .RS +4
50 .TP
51 .ie t \(bu
52 .el o
53 Output format version number, 4 bytes in network byte order. The current
54 version is 1.
55 .RE
56 .RS +4
57 .TP
58 .ie t \(bu
59 .el o
60 Iterations used in key generation function, 4 bytes in network byte order.
61 .RE
62 .RS +4
63 .TP
64 .ie t \(bu
65 .el o
66 IV (\fBivlen\fR bytes)[1]. iv data is generated by random bytes equal to one
67 block size.
68 .RE
69 .RS +4
70 .TP
71 .ie t \(bu
72 .el o
73 Salt data used in key generation (16 bytes).
74 .RE
75 .RS +4
76 .TP
77 .ie t \(bu
78 .el o
79 Cipher text data.
80 .RE
81 .SH OPTIONS
82 .sp
83 .LP
84 The following options are supported:
85 .sp
86 .ne 2
87 .na
88 \fB\fB-a\fR \fIalgorithm\fR\fR
89 .ad
90 .RS 18n
91 Specify the name of the algorithm to use during the encryption or decryption
92 process. See USAGE, \fBAlgorithms\fR for details.
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fB-i\fR \fIinput_file\fR\fR
99 .ad
100 .RS 18n
101 Specify the input file. Default is stdin if \fIinput_file\fR is not specified.
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB\fB-k\fR \fIkey_file\fR\fR
108 .ad
109 .RS 18n
110 Specify the file containing the key value for the encryption algorithm. Each
111 algorithm has specific key material requirements, as stated in the PKCS#11
112 specification. If \fB-k\fR is not specified, \fBencrypt\fR prompts for key
113 material using \fBgetpassphrase\fR(3C). The size of the key file determines the
114 key length, and passphrases set from the terminal are always used to generate
115 128 bit long keys for ciphers with a variable key length.
116 .sp
117 For information on generating a key file, see the \fBgenkey\fR subcommand in
118 \fBpktool\fR(1). Alternatively, \fBdd\fR(8) can be used.
119 .RE
121 .sp
122 .ne 2
123 .na
124 \fB\fB-K\fR \fIkey_label\fR\fR
125 .ad
126 .RS 18n
127 Specify the label of a symmetric token key in a PKCS#11 token.
128 .RE
130 .sp
131 .ne 2
132 .na
133 \fB\fB-l\fR\fR
134 .ad
135 .RS 18n
136 Display the list of algorithms available on the system. This list can change
137 depending on the configuration of the cryptographic framework. The keysizes are
138 displayed in bits.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-o\fR \fIoutput_file\fR\fR
145 .ad
146 .RS 18n
147 Specify output file. Default is stdout if \fIoutput_file\fR is not specified.
148 If stdout is used without redirecting to a file, the terminal window can appear
149 to hang because the raw encrypted or decrypted data has disrupted the terminal
150 emulation, much like viewing a binary file can do at times.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fB-T\fR \fItoken_spec\fR\fR
157 .ad
158 .RS 18n
159 Specify a PKCS#11 token other than the default soft token object store when the
160 \fB-K\fR is specified.
161 .sp
162 \fItoken_spec\fR has the format of:
163 .sp
164 .in +2
165 .nf
166 \fItoken_name\fR \fB[:\fR\fImanuf_id\fR \fB[:\fR\fIserial_no\fR\fB]]\fR
167 .fi
168 .in -2
169 .sp
171 When a token label contains trailing spaces, this option does not require them
172 to be typed as a convenience to the user.
173 .sp
174 Colon separates token identification string. If any of the parts have a literal
175 colon (\fB:\fR) character, it must be escaped by a backslash (\fB\e\fR). If a
176 colon (\fB:\fR) is not found, the entire string (up to 32 characters) is taken
177 as the token label. If only one colon (\fB:\fR) is found, the string is the
178 token label and the manufacturer.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fB-v\fR\fR
185 .ad
186 .RS 18n
187 Display verbose information. See \fBVerbose\fR.
188 .RE
190 .SH USAGE
191 .SS "Algorithms"
192 .sp
193 .LP
194 The supported algorithms are displayed with their minimum and maximum key sizes
195 in the \fB-l\fR option. These algorithms are provided by the cryptographic
196 framework. Each supported algorithm is an alias of the PKCS #11 mechanism that
197 is the most commonly used and least restricted version of a particular
198 algorithm type. For example, \fBdes\fR is an alias to \fBCKM_DES_CBC_PAD\fR and
199 \fBarcfour\fR is an alias to \fBCKM_RC4\fR. Algorithm variants with no padding
200 or \fBECB\fR are not supported.
201 .sp
202 .LP
203 These aliases are used with the \fB-a\fR option and are case-sensitive.
204 .SS "Passphrase"
205 .sp
206 .LP
207 When the \fB-k\fR option is not used during encryption and decryption tasks,
208 the user is prompted for a passphrase. The passphrase is manipulated into a
209 more secure key using the PBKDF2 algorithm specified in PKCS #5.
210 .sp
211 .LP
212 When a passphrase is used with encrypt and decrypt, the user entered passphrase
213 is turned into an encryption key using the \fBPBKDF2\fR algorithm as defined
214 defined in http://www.rsasecurity.com, \fBPKCS #5 v2.0.\fR
215 .SS "Verbose"
216 .sp
217 .LP
218 If an input file is provided to the command, a progress bar spans the screen.
219 The progress bar denotes every 25% completed with a pipe sign (\fB|\fR). If the
220 input is from standard input, a period (\fB\&.\fR) is displayed each time 40KB
221 is read. Upon completion of both input methods, \fBDone\fR is printed.
222 .SH EXAMPLES
223 .LP
224 \fBExample 1 \fRListing Available Algorithms
225 .sp
226 .LP
227 The following example lists available algorithms:
229 .sp
230 .in +2
231 .nf
232 example$ encrypt -l
233 Algorithm Keysize: Min Max
234 -----------------------------------
235 aes 128 128
236 arcfour 8 128
237 des 64 64
238 3des 192 192
239 .fi
240 .in -2
241 .sp
243 .LP
244 \fBExample 2 \fREncrypting Using AES
245 .sp
246 .LP
247 The following example encrypts using AES and prompts for the encryption key:
249 .sp
250 .in +2
251 .nf
252 example$ encrypt -a aes -i myfile.txt -o secretstuff
253 .fi
254 .in -2
255 .sp
257 .LP
258 \fBExample 3 \fREncrypting Using AES with a Key File
259 .sp
260 .LP
261 The following example encrypts using AES after the key file has been created:
263 .sp
264 .in +2
265 .nf
266 example$ pktool genkey keystore=file keytype=aes keylen=128 \e
267 outkey=key
268 example$ encrypt -a aes -k key -i myfile.txt -o secretstuff
269 .fi
270 .in -2
271 .sp
273 .LP
274 \fBExample 4 \fRUsing an In Pipe to Provide Encrypted Tape Backup
275 .sp
276 .LP
277 The following example uses an in pipe to provide encrypted tape backup:
279 .sp
280 .in +2
281 .nf
282 example$ ufsdump 0f - /var | encrypt -a arcfour \e
283 -k /etc/mykeys/backup.k | dd of=/dev/rmt/0
284 .fi
285 .in -2
286 .sp
288 .LP
289 \fBExample 5 \fRUsing an In Pipe to Restore Tape Backup
290 .sp
291 .LP
292 The following example uses and in pipe to restore a tape backup:
294 .sp
295 .in +2
296 .nf
297 example$ decrypt -a arcfour -k /etc/mykeys/backup.k \e
298 -i /dev/rmt/0 | ufsrestore xvf -
299 .fi
300 .in -2
301 .sp
303 .LP
304 \fBExample 6 \fREncrypting an Input File Using the 3DES Algorithm
305 .sp
306 .LP
307 The following example encrypts the \fBinputfile\fR file with the 192-bit key
308 stored in the \fBdes3key\fR file:
310 .sp
311 .in +2
312 .nf
313 example$ encrypt -a 3des -k des3key -i inputfile -o outputfile
314 .fi
315 .in -2
316 .sp
318 .LP
319 \fBExample 7 \fREncrypting an Input File with a DES token key
320 .sp
321 .LP
322 The following example encrypts the input file file with a DES token key in the
323 soft token keystore. The DES token key can be generated with \fBpktool\fR(1):
325 .sp
326 .in +2
327 .nf
328 example$ encrypt -a des -K mydeskey \e
329 -T "Sun Software PKCS#11 softtoken" -i inputfile \e
330 -o outputfile
331 .fi
332 .in -2
333 .sp
335 .SH EXIT STATUS
336 .sp
337 .LP
338 The following exit values are returned:
339 .sp
340 .ne 2
341 .na
342 \fB\fB0\fR\fR
343 .ad
344 .RS 6n
345 Successful completion.
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fB>0\fR\fR
352 .ad
353 .RS 6n
354 An error occurred.
355 .RE
357 .SH ATTRIBUTES
358 .sp
359 .LP
360 See \fBattributes\fR(5) for descriptions of the following attributes:
361 .sp
363 .sp
364 .TS
365 box;
366 c | c
367 l | l .
368 ATTRIBUTE TYPE ATTRIBUTE VALUE
369 _
370 Interface Stability Committed
371 .TE
373 .SH SEE ALSO
374 .sp
375 .LP
376 \fBdigest\fR(1), \fBpktool\fR(1), \fBmac\fR(1), \fBdd\fR(8),
377 \fBgetpassphrase\fR(3C), \fBlibpkcs11\fR(3LIB), \fBattributes\fR(5),
378 \fBpkcs11_softtoken\fR(5)
379 .sp
380 .LP
381 \fISystem Administration Guide: Security Services\fR
382 .sp
383 .LP
384 RSA PKCS#11 v2.11: http://www.rsasecurity.com
385 .sp
386 .LP
387 RSA PKCS#5 v2.0: http://www.rsasecurity.com