[thirdparty/openssl.git] / doc / man1 / mac.pod

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