c2969ff6e7
CLA: trivial Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/9288)
163 lines
4.2 KiB
Text
163 lines
4.2 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
openssl-mac,
|
|
mac - perform Message Authentication Code operations
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<openssl mac>
|
|
[B<-help>]
|
|
[B<-macopt>]
|
|
[B<-in filename>]
|
|
[B<-out filename>]
|
|
[B<-binary>]
|
|
B<mac_name>
|
|
|
|
B<openssl> I<mac> [B<...>] B<mac_name>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The message authentication code functions output the MAC of a supplied input
|
|
file.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-help>
|
|
|
|
Print a usage message.
|
|
|
|
=item B<-in filename>
|
|
|
|
Input filename to calculate a MAC for, or standard input by default.
|
|
Standard input is used if the filename is '-'.
|
|
Files are expected to be in binary format, standard input uses hexadecimal text
|
|
format.
|
|
|
|
=item B<-out filename>
|
|
|
|
Filename to output to, or standard output by default.
|
|
|
|
=item B<-binary>
|
|
|
|
Output the MAC in binary form. Uses hexadecimal text format if not specified.
|
|
|
|
=item B<-macopt nm:v>
|
|
|
|
Passes options to the MAC algorithm.
|
|
A comprehensive list of controls can be found in the EVP_MAC implementation
|
|
documentation.
|
|
Common control strings used by EVP_MAC_ctrl_str() are:
|
|
|
|
=over 4
|
|
|
|
=item B<key:string>
|
|
|
|
Specifies the MAC key as an alphanumeric string (use if the key contains
|
|
printable characters only).
|
|
The string length must conform to any restrictions of the MAC algorithm.
|
|
A key must be specified for every MAC algorithm.
|
|
|
|
=item B<hexkey:string>
|
|
|
|
Specifies the MAC key in hexadecimal form (two hex digits per byte).
|
|
The key length must conform to any restrictions of the MAC algorithm.
|
|
A key must be specified for every MAC algorithm.
|
|
|
|
=item B<digest:string>
|
|
|
|
Used by HMAC as an alphanumeric string (use if the key contains printable
|
|
characters only).
|
|
The string length must conform to any restrictions of the MAC algorithm.
|
|
To see the list of supported digests, use the command I<list -digest-commands>.
|
|
|
|
=item B<cipher:string>
|
|
|
|
Used by CMAC and GMAC to specify the cipher algorithm.
|
|
For CMAC it must be one of AES-128-CBC, AES-192-CBC, AES-256-CBC or
|
|
DES-EDE3-CBC.
|
|
For GMAC it should be a GCM mode cipher e.g. AES-128-GCM.
|
|
|
|
=item B<iv:string>
|
|
|
|
Used by GMAC to specify an IV as an alphanumeric string (use if the IV contains
|
|
printable characters only).
|
|
|
|
=item B<hexiv:string>
|
|
|
|
Used by GMAC to specify an IV in hexadecimal form (two hex digits per byte).
|
|
|
|
=item B<outlen:int>
|
|
|
|
Used by KMAC128 or KMAC256 to specify an output length.
|
|
The default sizes are 32 or 64 bytes respectively.
|
|
|
|
=item B<custom:string>
|
|
|
|
Used by KMAC128 or KMAC256 to specify a customization string.
|
|
The default is the empty string "".
|
|
|
|
=back
|
|
|
|
=item B<mac_name>
|
|
|
|
Specifies the name of a supported MAC algorithm which will be used.
|
|
To see the list of supported MAC's use the command I<list -mac-algorithms>.
|
|
|
|
=back
|
|
|
|
|
|
=head1 EXAMPLES
|
|
|
|
To create a hex-encoded HMAC-SHA1 MAC of a file and write to stdout: \
|
|
openssl mac -macopt digest:SHA1 \
|
|
-macopt hexkey:000102030405060708090A0B0C0D0E0F10111213 \
|
|
-in msg.bin HMAC
|
|
|
|
To create a SipHash MAC from a file with a binary file output: \
|
|
openssl mac -macopt hexkey:000102030405060708090A0B0C0D0E0F \
|
|
-in msg.bin -out out.bin -binary SipHash
|
|
|
|
To create a hex-encoded CMAC-AES-128-CBC MAC from a file:\
|
|
openssl mac -macopt cipher:AES-128-CBC \
|
|
-macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B \
|
|
-in msg.bin CMAC
|
|
|
|
To create a hex-encoded KMAC128 MAC from a file with a Customisation String
|
|
'Tag' and output length of 16: \
|
|
openssl mac -macopt custom:Tag -macopt hexkey:40414243444546 \
|
|
-macopt outlen:16 -in msg.bin KMAC128
|
|
|
|
To create a hex-encoded GMAC-AES-128-GCM with a IV from a file: \
|
|
openssl mac -macopt cipher:AES-128-GCM -macopt hexiv:E0E00F19FED7BA0136A797F3 \
|
|
-macopt hexkey:77A77FAF290C1FA30C683DF16BA7A77B -in msg.bin GMAC
|
|
|
|
=head1 NOTES
|
|
|
|
The MAC mechanisms that are available will depend on the options
|
|
used when building OpenSSL.
|
|
The B<list -mac-algorithms> command can be used to list them.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<EVP_MAC(3)>,
|
|
L<EVP_MAC_CMAC(7)>,
|
|
L<EVP_MAC_GMAC(7)>,
|
|
L<EVP_MAC_HMAC(7)>,
|
|
L<EVP_MAC_KMAC(7)>,
|
|
L<EVP_MAC_SIPHASH(7)>,
|
|
L<EVP_MAC_POLY1305(7)>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the OpenSSL license (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|