]>
Commit | Line | Data |
---|---|---|
4d768e96 | 1 | =pod |
5e98904c | 2 | {- OpenSSL::safe::output_do_not_edit_headers(); -} |
4d768e96 SL |
3 | |
4 | =head1 NAME | |
5 | ||
b6b66573 | 6 | openssl-mac - perform Message Authentication Code operations |
4d768e96 SL |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl mac> | |
11 | [B<-help>] | |
12 | [B<-macopt>] | |
e8769719 RS |
13 | [B<-in> I<filename>] |
14 | [B<-out> I<filename>] | |
4d768e96 | 15 | [B<-binary>] |
6bd4e3f2 | 16 | {- $OpenSSL::safe::opt_provider_synopsis -} |
2f0ea936 | 17 | I<mac_name> |
4d768e96 | 18 | |
4d768e96 SL |
19 | =head1 DESCRIPTION |
20 | ||
21 | The message authentication code functions output the MAC of a supplied input | |
22 | file. | |
23 | ||
24 | =head1 OPTIONS | |
25 | ||
26 | =over 4 | |
27 | ||
28 | =item B<-help> | |
29 | ||
30 | Print a usage message. | |
31 | ||
e8769719 | 32 | =item B<-in> I<filename> |
4d768e96 SL |
33 | |
34 | Input filename to calculate a MAC for, or standard input by default. | |
35 | Standard input is used if the filename is '-'. | |
36 | Files are expected to be in binary format, standard input uses hexadecimal text | |
37 | format. | |
38 | ||
e8769719 | 39 | =item B<-out> I<filename> |
4d768e96 SL |
40 | |
41 | Filename to output to, or standard output by default. | |
42 | ||
43 | =item B<-binary> | |
44 | ||
45 | Output the MAC in binary form. Uses hexadecimal text format if not specified. | |
46 | ||
e8769719 | 47 | =item B<-macopt> I<nm>:I<v> |
4d768e96 SL |
48 | |
49 | Passes options to the MAC algorithm. | |
50 | A comprehensive list of controls can be found in the EVP_MAC implementation | |
51 | documentation. | |
1ce60442 | 52 | Common parameter names used by EVP_MAC_CTX_get_params() are: |
4d768e96 SL |
53 | |
54 | =over 4 | |
55 | ||
2f0ea936 | 56 | =item B<key:>I<string> |
4d768e96 SL |
57 | |
58 | Specifies the MAC key as an alphanumeric string (use if the key contains | |
59 | printable characters only). | |
60 | The string length must conform to any restrictions of the MAC algorithm. | |
61 | A key must be specified for every MAC algorithm. | |
62 | ||
2f0ea936 | 63 | =item B<hexkey:>I<string> |
4d768e96 SL |
64 | |
65 | Specifies the MAC key in hexadecimal form (two hex digits per byte). | |
66 | The key length must conform to any restrictions of the MAC algorithm. | |
67 | A key must be specified for every MAC algorithm. | |
68 | ||
2f0ea936 | 69 | =item B<digest:>I<string> |
4d768e96 SL |
70 | |
71 | Used by HMAC as an alphanumeric string (use if the key contains printable | |
72 | characters only). | |
73 | The string length must conform to any restrictions of the MAC algorithm. | |
35a810bb | 74 | To see the list of supported digests, use C<openssl list -digest-commands>. |
4d768e96 | 75 | |
2f0ea936 | 76 | =item B<cipher:>I<string> |
4d768e96 | 77 | |
c2969ff6 | 78 | Used by CMAC and GMAC to specify the cipher algorithm. |
4d768e96 SL |
79 | For CMAC it must be one of AES-128-CBC, AES-192-CBC, AES-256-CBC or |
80 | DES-EDE3-CBC. | |
81 | For GMAC it should be a GCM mode cipher e.g. AES-128-GCM. | |
82 | ||
2f0ea936 | 83 | =item B<iv:>I<string> |
4d768e96 SL |
84 | |
85 | Used by GMAC to specify an IV as an alphanumeric string (use if the IV contains | |
86 | printable characters only). | |
87 | ||
2f0ea936 | 88 | =item B<hexiv:>I<string> |
4d768e96 SL |
89 | |
90 | Used by GMAC to specify an IV in hexadecimal form (two hex digits per byte). | |
91 | ||
1242f3c7 | 92 | =item B<size:>I<int> |
4d768e96 SL |
93 | |
94 | Used by KMAC128 or KMAC256 to specify an output length. | |
95 | The default sizes are 32 or 64 bytes respectively. | |
96 | ||
2f0ea936 | 97 | =item B<custom:>I<string> |
4d768e96 SL |
98 | |
99 | Used by KMAC128 or KMAC256 to specify a customization string. | |
100 | The default is the empty string "". | |
101 | ||
102 | =back | |
103 | ||
6bd4e3f2 P |
104 | {- $OpenSSL::safe::opt_provider_item -} |
105 | ||
2f0ea936 | 106 | =item I<mac_name> |
4d768e96 SL |
107 | |
108 | Specifies the name of a supported MAC algorithm which will be used. | |
35a810bb RL |
109 | To see the list of supported MAC's use the command C<opensssl list |
110 | -mac-algorithms>. | |
4d768e96 SL |
111 | |
112 | =back | |
113 | ||
114 | ||
115 | =head1 EXAMPLES | |
116 | ||
117 | To create a hex-encoded HMAC-SHA1 MAC of a file and write to stdout: \ | |
118 | openssl mac -macopt digest:SHA1 \ | |
119 | -macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \ | |
120 | -in msg.bin HMAC | |
121 | ||
122 | To create a SipHash MAC from a file with a binary file output: \ | |
123 | openssl mac -macopt hexkey:000102030405060708090A0B0C0D0E0F \ | |
124 | -in msg.bin -out out.bin -binary SipHash | |
125 | ||
126 | To create a hex-encoded CMAC-AES-128-CBC MAC from a file:\ | |
127 | openssl mac -macopt cipher:AES-128-CBC \ | |
128 | -macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B \ | |
129 | -in msg.bin CMAC | |
130 | ||
131 | To create a hex-encoded KMAC128 MAC from a file with a Customisation String | |
132 | 'Tag' and output length of 16: \ | |
133 | openssl mac -macopt custom:Tag -macopt hexkey:40414243444546 \ | |
1242f3c7 | 134 | -macopt size:16 -in msg.bin KMAC128 |
4d768e96 SL |
135 | |
136 | To create a hex-encoded GMAC-AES-128-GCM with a IV from a file: \ | |
137 | openssl mac -macopt cipher:AES-128-GCM -macopt hexiv:E0E00F19FED7BA0136A797F3 \ | |
138 | -macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B -in msg.bin GMAC | |
139 | ||
140 | =head1 NOTES | |
141 | ||
142 | The MAC mechanisms that are available will depend on the options | |
143 | used when building OpenSSL. | |
35a810bb | 144 | Use C<openssl list -mac-algorithms> to list them. |
4d768e96 SL |
145 | |
146 | =head1 SEE ALSO | |
147 | ||
b6b66573 | 148 | L<openssl(1)>, |
4d768e96 | 149 | L<EVP_MAC(3)>, |
1ce60442 P |
150 | L<EVP_MAC-CMAC(7)>, |
151 | L<EVP_MAC-GMAC(7)>, | |
152 | L<EVP_MAC-HMAC(7)>, | |
153 | L<EVP_MAC-KMAC(7)>, | |
d7cea0b8 RS |
154 | L<EVP_MAC-Siphash(7)>, |
155 | L<EVP_MAC-Poly1305(7)> | |
4d768e96 SL |
156 | |
157 | =head1 COPYRIGHT | |
158 | ||
33388b44 | 159 | Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved. |
4d768e96 SL |
160 | |
161 | Licensed under the OpenSSL license (the "License"). You may not use | |
162 | this file except in compliance with the License. You can obtain a copy | |
163 | in the file LICENSE in the source distribution or at | |
164 | L<https://www.openssl.org/source/license.html>. | |
165 | ||
166 | =cut |