usr/src/man/man1/mac.1

   1 '\" te
   2 .\" Copyright 2007, 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 MAC 1 "Mar 21, 2007"
   7 .SH NAME
   8 mac \- calculate message authentication codes of the input
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/bin/mac\fR \fB-l\fR
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fB/usr/bin/mac\fR [\fB-v\fR] \fB-a\fR \fIalgorithm\fR
  18    [\fB-k\fR \fIkeyfile\fR | \fB-K\fR \fIkey_label\fR [\fB-T\fR \fItoken_spec\fR]] [\fIfile\fR]...
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBmac\fR utility calculates the message authentication code (\fBMAC\fR) of
  25 the given file or files or \fBstdin\fR using the algorithm specified.
  26 .sp
  27 .LP
  28 If more than one file is given, each line of output is the \fBMAC\fR of a
  29 single file.
  30 .SH OPTIONS
  31 .sp
  32 .LP
  33 The following options are supported:
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fB-a\fR \fIalgorithm\fR\fR
  38 .ad
  39 .RS 17n
  40 Specifies the name of the algorithm to use during the encryption or decryption
  41 process. See USAGE, \fBAlgorithms\fR for details. \fBNote:\fR Algorithms for
  42 producing general length \fBMAC\fRs are not supported.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fB-k\fR \fIkeyfile\fR\fR
  49 .ad
  50 .RS 17n
  51 Specifies the file containing the key value for the encryption algorithm. Each
  52 algorithm has specific key material requirements, as stated in the PKCS#11
  53 specification. If \fB-k\fR is not specified, \fBmac\fR prompts for  key
  54 material using \fBgetpassphrase\fR(3C).
  55 .sp
  56 For information on generating a key file, see \fBpktool\fR(1), \fBdd\fR(1M) or
  57 the \fISystem Administration Guide: Security Services\fR.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fB-K\fR \fIkey_label\fR\fR
  64 .ad
  65 .RS 17n
  66 Specify the label of a symmetric token key in a PKCS#11 token.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fB-l\fR\fR
  73 .ad
  74 .RS 17n
  75 Displays the list of algorithms available on the system. This list can change
  76 depending on the configuration of the cryptographic framework. The keysizes are
  77 displayed in bits.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fB-T\fR \fItoken_spec\fR\fR
  84 .ad
  85 .RS 17n
  86 Specify a PKCS#11 token other than the default soft token object store when the
  87 \fB-K\fR is specified.
  88 .sp
  89 \fItoken_spec\fR has the format of:
  90 .sp
  91 .in +2
  92 .nf
  93 \fItoken_name\fR \fB[:\fR\fImanuf_id\fR \fB[:\fR\fIserial_no\fR\fB]]\fR
  94 .fi
  95 .in -2
  96 .sp
  97
  98 When a token label contains trailing spaces, this option does not require them
  99 to be typed as a convenience to the user.
 100 .sp
 101 Colon separates token identification string. If any of the parts have a literal
 102 colon (\fB:\fR) character, it must be escaped by a backslash (\fB\e\fR). If a
 103 colon (\fB:\fR) is not found, the entire string (up to 32 characters) is taken
 104 as the token label. If only one colon (\fB:\fR) is found, the string is the
 105 token label and the manufacturer.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-v\fR\fR
 112 .ad
 113 .RS 17n
 114 Provides verbose information.
 115 .RE
 116
 117 .SH USAGE
 118 .SS "Algorithms"
 119 .sp
 120 .LP
 121 The supported algorithms are displayed with the \fB-l\fR option. These
 122 algorithms are provided by the cryptographic framework. Each supported
 123 algorithm is an alias to the most commonly used and least restricted version of
 124 a particular algorithm type. For example, \fBmd5_hmac\fR is an alias to
 125 \fBCKM_MD5_HMAC\fR.
 126 .sp
 127 .LP
 128 These aliases are used with the \fB-a\fR option and are case-sensitive.
 129 .SS "Passphrase"
 130 .sp
 131 .LP
 132 When the \fB-k\fR option is not used during encryption and decryption tasks,
 133 the user is prompted for a passphrase. The passphrase is manipulated into a
 134 more secure key using the \fBPBKDF2\fR algorithm specified in PKCS #5.
 135 .SH EXAMPLES
 136 .LP
 137 \fBExample 1 \fRListing Available Algorithms
 138 .sp
 139 .LP
 140 The following example lists available algorithms:
 141
 142 .sp
 143 .in +2
 144 .nf
 145 example$ mac -l
 146 Algorithm       Keysize:  Min   Max
 147 -----------------------------------
 148 des_mac                    64    64
 149 sha1_hmac                   8   512
 150 md5_hmac                    8   512
 151 sha256_hmac                 8   512
 152 sha384_hmac                 8  1024
 153 sha512_hmac                 8  1024
 154 .fi
 155 .in -2
 156 .sp
 157
 158 .LP
 159 \fBExample 2 \fRGetting the Message Authentication Code
 160 .sp
 161 .LP
 162 The following example gets the message authentication code for a file:
 163
 164 .sp
 165 .in +2
 166 .nf
 167 example$ mac -v -k mykey -a sha1_hmac /export/foo
 168 sha1_hmac (/export/foo) = 913ced311df10f1708d9848641ca8992f4718057
 169 .fi
 170 .in -2
 171 .sp
 172
 173 .LP
 174 \fBExample 3 \fRGetting the Message Authentication Code with a Token Key
 175 .sp
 176 .LP
 177 The following example gets the message authentication code with a generic token
 178 key in the soft token keystore.  The generic token  key can be generated with
 179 \fBpktool\fR(1):
 180
 181 .sp
 182 .in +2
 183 .nf
 184 encrypt -v -a sha1_hmac -K my_generic_key \e
 185      -T "Sun Software PKCS#11 softtoken" /export/foo
 186 Enter pin for Sun Software PKCS#11 softtoken:
 187      sha1_hmac (/etc/foo) = c2ba5c38458c092a68940081240d22b670182968
 188 .fi
 189 .in -2
 190 .sp
 191
 192 .SH EXIT STATUS
 193 .sp
 194 .LP
 195 The following exit values are returned:
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fB0\fR\fR
 200 .ad
 201 .RS 6n
 202 Successful completion.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fB>0\fR\fR
 209 .ad
 210 .RS 6n
 211 An error occurred.
 212 .RE
 213
 214 .SH ATTRIBUTES
 215 .sp
 216 .LP
 217 See \fBattributes\fR(5) for descriptions of the following attributes:
 218 .sp
 219
 220 .sp
 221 .TS
 222 box;
 223 c | c
 224 l | l .
 225 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 226 _
 227 Interface Stability     Evolving
 228 .TE
 229
 230 .SH SEE ALSO
 231 .sp
 232 .LP
 233 \fBdigest\fR(1), \fBpktool\fR(1), \fBdd\fR(1M), \fBgetpassphrase\fR(3C),
 234 \fBlibpkcs11\fR(3LIB), \fBattributes\fR(5), \fBpkcs11_softtoken\fR(5)
 235 .sp
 236 .LP
 237 \fISystem Administration Guide: Security Services\fR
 238 .sp
 239 .LP
 240 RSA PKCS#11 v2.20 and RSA PKCS#5 v2.0, http://www.rsasecurity.com