'\" te
.\" Copyright 2008, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH ENCRYPT 1 "Dec 17, 2008"
.SH NAME
encrypt, decrypt \- encrypt or decrypt files
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/encrypt\fR \fB-l\fR
.fi

.LP
.nf
\fB/usr/bin/encrypt\fR \fB-a\fR \fIalgorithm\fR [\fB-v\fR]
     [\fB-k\fR \fIkey_file\fR | \fB-K\fR \fIkey_label\fR [\fB-T\fR \fItoken_spec\fR]]
     [\fB-i\fR \fIinput_file\fR] [\fB-o\fR \fIoutput_file\fR]
.fi

.LP
.nf
\fB/usr/bin/decrypt\fR \fB-l\fR
.fi

.LP
.nf
\fB/usr/bin/decrypt\fR \fB-a\fR \fIalgorithm\fR [\fB-v\fR]
     [\fB-k\fR \fIkey_file\fR | \fB-K\fR \fIkey_label\fR [\fB-T\fR \fItoken_spec\fR]]
     [\fB-i\fR \fIinput_file\fR] [\fB-o\fR \fIoutput_file\fR]
.fi

.SH DESCRIPTION
.sp
.LP
This utility encrypts or decrypts the given file or stdin using the algorithm
specified. If no output file is specified, output is to standard out. If input
and output are the same file, the encrypted output is written to a temporary
work file in the same filesystem and then used to replace the original file.
.sp
.LP
On decryption, if the input and output are the same file, the cleartext
replaces the ciphertext file.
.sp
.LP
The output file of \fBencrypt\fR and the input file for \fBdecrypt\fR contains
the following information:
.RS +4
.TP
.ie t \(bu
.el o
Output format version number, 4 bytes in network byte order. The current
version is 1.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Iterations used in key generation function, 4 bytes in network byte order.
.RE
.RS +4
.TP
.ie t \(bu
.el o
IV (\fBivlen\fR bytes)[1]. iv data is generated by random bytes equal to one
block size.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Salt data used in key generation (16 bytes).
.RE
.RS +4
.TP
.ie t \(bu
.el o
Cipher text data.
.RE
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR \fIalgorithm\fR\fR
.ad
.RS 18n
Specify the name of the algorithm to use during the encryption or decryption
process. See USAGE, \fBAlgorithms\fR for details.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIinput_file\fR\fR
.ad
.RS 18n
Specify the input file. Default is stdin if \fIinput_file\fR is not specified.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR \fIkey_file\fR\fR
.ad
.RS 18n
Specify the file containing the key value for the encryption algorithm. Each
algorithm has specific key material requirements, as stated in the PKCS#11
specification. If \fB-k\fR is not specified, \fBencrypt\fR prompts for key
material using \fBgetpassphrase\fR(3C). The size of the key file determines the
key length, and passphrases set from the terminal are always used to generate
128 bit long keys for ciphers with a variable key length.
.sp
For information on generating a key file, see the \fBgenkey\fR subcommand in
\fBpktool\fR(1). Alternatively, \fBdd\fR(1M) can be used.
.RE

.sp
.ne 2
.na
\fB\fB-K\fR \fIkey_label\fR\fR
.ad
.RS 18n
Specify the label of a symmetric token key in a PKCS#11 token.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 18n
Display the list of algorithms available on the system. This list can change
depending on the configuration of the cryptographic framework. The keysizes are
displayed in bits.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoutput_file\fR\fR
.ad
.RS 18n
Specify output file. Default is stdout if \fIoutput_file\fR is not specified.
If stdout is used without redirecting to a file, the terminal window can appear
to hang because the raw encrypted or decrypted data has disrupted the terminal
emulation, much like viewing a binary file can do at times.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fItoken_spec\fR\fR
.ad
.RS 18n
Specify a PKCS#11 token other than the default soft token object store when the
\fB-K\fR is specified.
.sp
\fItoken_spec\fR has the format of:
.sp
.in +2
.nf
\fItoken_name\fR \fB[:\fR\fImanuf_id\fR \fB[:\fR\fIserial_no\fR\fB]]\fR
.fi
.in -2
.sp

When a token label contains trailing spaces, this option does not require them
to be typed as a convenience to the user.
.sp
Colon separates token identification string. If any of the parts have a literal
colon (\fB:\fR) character, it must be escaped by a backslash (\fB\e\fR). If a
colon (\fB:\fR) is not found, the entire string (up to 32 characters) is taken
as the token label. If only one colon (\fB:\fR) is found, the string is the
token label and the manufacturer.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 18n
Display verbose information. See \fBVerbose\fR.
.RE

.SH USAGE
.SS "Algorithms"
.sp
.LP
The supported algorithms are displayed with their minimum and maximum key sizes
in the \fB-l\fR option. These algorithms are provided by the cryptographic
framework. Each supported algorithm is an alias of the PKCS #11 mechanism that
is the most commonly used and least restricted version of a particular
algorithm type. For example, \fBdes\fR is an alias to \fBCKM_DES_CBC_PAD\fR and
\fBarcfour\fR is an alias to \fBCKM_RC4\fR. Algorithm variants with no padding
or \fBECB\fR are not supported.
.sp
.LP
These aliases are used with the \fB-a\fR option and are case-sensitive.
.SS "Passphrase"
.sp
.LP
When the \fB-k\fR option is not used during encryption and decryption tasks,
the user is prompted for a passphrase. The passphrase is manipulated into a
more secure key using the PBKDF2 algorithm specified in PKCS #5.
.sp
.LP
When a passphrase is used with encrypt and decrypt, the user entered passphrase
is turned into an encryption key using the \fBPBKDF2\fR algorithm as defined
defined in http://www.rsasecurity.com, \fBPKCS #5 v2.0.\fR
.SS "Verbose"
.sp
.LP
If an input file is provided to the command, a progress bar spans the screen.
The progress bar denotes every 25% completed with a pipe sign (\fB|\fR). If the
input is from standard input, a period (\fB\&.\fR) is displayed each time 40KB
is read. Upon completion of both input methods, \fBDone\fR is printed.
.SH EXAMPLES
.LP
\fBExample 1 \fRListing Available Algorithms
.sp
.LP
The following example lists available algorithms:

.sp
.in +2
.nf
example$ encrypt -l
     Algorithm       Keysize:  Min   Max
     -----------------------------------
     aes                       128   128
     arcfour                     8   128
     des                        64    64
     3des                      192   192
.fi
.in -2
.sp

.LP
\fBExample 2 \fREncrypting Using AES
.sp
.LP
The following example encrypts using AES and prompts for the encryption key:

.sp
.in +2
.nf
example$ encrypt -a aes -i myfile.txt -o secretstuff
.fi
.in -2
.sp

.LP
\fBExample 3 \fREncrypting Using AES with a Key File
.sp
.LP
The following example encrypts using AES after the key file has been created:

.sp
.in +2
.nf
example$ pktool genkey keystore=file keytype=aes keylen=128 \e
            outkey=key
example$ encrypt -a aes -k key -i myfile.txt -o secretstuff
.fi
.in -2
.sp

.LP
\fBExample 4 \fRUsing an In Pipe to Provide Encrypted Tape Backup
.sp
.LP
The following example uses an in pipe to provide encrypted tape backup:

.sp
.in +2
.nf
example$ ufsdump 0f - /var | encrypt -a arcfour \e
     -k /etc/mykeys/backup.k | dd of=/dev/rmt/0
.fi
.in -2
.sp

.LP
\fBExample 5 \fRUsing an In Pipe to Restore Tape Backup
.sp
.LP
The following example uses and in pipe to restore a tape backup:

.sp
.in +2
.nf
example$ decrypt -a arcfour -k /etc/mykeys/backup.k \e
     -i /dev/rmt/0 | ufsrestore xvf -
.fi
.in -2
.sp

.LP
\fBExample 6 \fREncrypting an Input File Using the 3DES Algorithm
.sp
.LP
The following example encrypts the \fBinputfile\fR file with the 192-bit key
stored in the \fBdes3key\fR file:

.sp
.in +2
.nf
example$ encrypt -a 3des -k des3key -i inputfile -o outputfile
.fi
.in -2
.sp

.LP
\fBExample 7 \fREncrypting an Input File with a DES token key
.sp
.LP
The following example encrypts the input file file with a DES token key in the
soft token keystore. The DES token key can be generated with \fBpktool\fR(1):

.sp
.in +2
.nf
example$ encrypt -a des -K mydeskey \e
     -T "Sun Software PKCS#11 softtoken" -i inputfile \e
     -o outputfile
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBdigest\fR(1), \fBpktool\fR(1), \fBmac\fR(1), \fBdd\fR(1M),
\fBgetpassphrase\fR(3C), \fBlibpkcs11\fR(3LIB), \fBattributes\fR(5),
\fBpkcs11_softtoken\fR(5)
.sp
.LP
\fISystem Administration Guide: Security Services\fR
.sp
.LP
RSA PKCS#11 v2.11: http://www.rsasecurity.com
.sp
.LP
RSA PKCS#5 v2.0: http://www.rsasecurity.com