new manual page CMAC_Init(3);

OK tb@

5 files changed, 298 insertions, 7 deletions

diff --git a/lib/libcrypto/man/CMAC_Init.3 b/lib/libcrypto/man/CMAC_Init.3
new file mode 100644
index 00000000000..55196b32131
--- /dev/null
+++ b/lib/libcrypto/man/CMAC_Init.3
@@ -0,0 +1,287 @@
+.\" $OpenBSD: CMAC_Init.3,v 1.1 2020/06/24 16:06:27 schwarze Exp $
+.\"
+.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 24 2020 $
+.Dt CMAC_INIT 3
+.Os
+.Sh NAME
+.Nm CMAC_CTX_new ,
+.Nm CMAC_Init ,
+.Nm CMAC_Update ,
+.Nm CMAC_Final ,
+.Nm CMAC_resume ,
+.Nm CMAC_CTX_copy ,
+.Nm CMAC_CTX_get0_cipher_ctx ,
+.Nm CMAC_CTX_cleanup ,
+.Nm CMAC_CTX_free
+.Nd Cipher-based message authentication code
+.Sh SYNOPSIS
+.In openssl/cmac.h
+.Ft CMAC_CTX *
+.Fn CMAC_CTX_new void
+.Ft int
+.Fo CMAC_Init
+.Fa "CMAC_CTX *ctx"
+.Fa "const void *key"
+.Fa "size_t key_len"
+.Fa "const EVP_CIPHER *cipher"
+.Fa "ENGINE *impl"
+.Fc
+.Ft int
+.Fo CMAC_Update
+.Fa "CMAC_CTX *ctx"
+.Fa "const void *in_data"
+.Fa "size_t in_len"
+.Fc
+.Ft int
+.Fo CMAC_Final
+.Fa "CMAC_CTX *ctx"
+.Fa "unsigned char *out_mac"
+.Fa "size_t *out_len"
+.Fc
+.Ft int
+.Fn CMAC_resume "CMAC_CTX *ctx"
+.Ft int
+.Fo CMAC_CTX_copy
+.Fa "CMAC_CTX *out_ctx"
+.Fa "CMAC_CTX *in_ctx"
+.Fc
+.Ft EVP_CIPHER_CTX *
+.Fn CMAC_CTX_get0_cipher_ctx "CMAC_CTX *ctx"
+.Ft void
+.Fn CMAC_CTX_cleanup "CMAC_CTX *ctx"
+.Ft void
+.Fn CMAC_CTX_free "CMAC_CTX *ctx"
+.Sh DESCRIPTION
+CMAC is a message authentication code algorithm that can employ an
+arbitrary block cipher using a symmetric key.
+.Pp
+The present manual page describes low-level functions implementing CMAC.
+Instead of using these functions directly,
+application programs normally call
+.Xr EVP_PKEY_CTX_new_id 3
+with an argument of
+.Dv EVP_PKEY_CMAC
+and then pass the resulting
+.Vt EVP_MD_CTX
+object to
+.Xr EVP_DigestInit_ex 3 .
+.Pp
+The CMAC API is object-oriented.
+Calculating a message authentication code requires a
+.Vt CMAC_CTX
+object.
+Usually, the functions
+.Fn CMAC_CTX_new ,
+.Fn CMAC_Init ,
+.Fn CMAC_Update ,
+.Fn CMAC_Final ,
+and
+.Fn CMAC_CTX_free
+need to be called in this order.
+.Pp
+.Fn CMAC_CTX_new
+allocates a new
+.Vt CMAC_CTX
+object, initializes the embedded
+.Vt EVP_CIPHER_CTX
+object, and marks the object itself as uninitialized.
+.Pp
+.Fn CMAC_Init
+selects the given block
+.Fa cipher
+for use by
+.Fa ctx .
+Funtions to obtain suitable
+.Vt EVP_CIPHER
+objects are listed in the CIPHER LISTING section of the
+.Xr EVP_Cipher 3
+manual page.
+Unless
+.Fa key
+is
+.Dv NULL ,
+.Fn CMAC_Init
+also initializes
+.Fa ctx
+for use with the given symmetric
+.Fa key
+that is
+.Fa key_len
+bytes long.
+In particular, it calculates and internally stores the two subkeys
+and initializes
+.Fa ctx
+for subsequently feeding in data with
+.Fn CMAC_Update .
+To use the default cipher implementations provided by the library, pass
+.Dv NULL
+as the
+.Fa impl
+argument.
+.Pp
+If
+.Fa ctx
+is already initialized,
+.Fn CMAC_Init
+can be called again with
+.Fa key ,
+.Fa cipher ,
+and
+.Fa impl
+all set to
+.Dv NULL
+and
+.Fa key_len
+set to 0.
+In that case, any data already processed is discarded and
+.Fa ctx
+is re-initialized to start reading data anew.
+.Pp
+.Fn CMAC_Update
+processes
+.Fa in_len
+bytes of input data pointed to by
+.Fa in_data .
+Depending on the number of input bytes already cached in
+.Fa ctx ,
+on
+.Fa in_len ,
+and on the block size, this may encrypt zero or more blocks.
+Unless
+.Fa in_len
+is zero, this function leaves at least one byte and at most one
+block of input cached but unprocessed inside the
+.Fa ctx
+object.
+.Fn CMAC_Update
+can be called multiple times
+to concatenate several chunks of input data of varying sizes.
+.Pp
+.Fn CMAC_Final
+stores the length of the message authentication code in bytes,
+which equals the cipher block size, into
+.Pf * Fa out_len .
+Unless
+.Fa out_mac
+is
+.Dv NULL ,
+it encrypts the last block, padding it if required, and copies the
+resulting message authentication code to
+.Fa out_mac .
+The caller is responsible for providing a buffer of sufficient size.
+.Pp
+Calling
+.Fn CMAC_resume
+after
+.Fn CMAC_Final
+allows to subsequently append additional data with
+.Fn CMAC_Update .
+.Pp
+.Fn CMAC_CTX_copy
+performs a deep copy of the already initialized
+.Fa in_ctx
+into
+.Fa out_ctx .
+.Pp
+.Fn CMAC_CTX_cleanup
+zeros out both subkeys and all temporary data in
+.Fa ctx
+and in the embedded
+.Vt EVP_CIPHER_CTX
+object, frees all allocated memory associated with it,
+except for
+.Fa ctx
+itself, and marks it as uninitialized,
+such that it can be reused for subsequent
+.Fn CMAC_Init .
+.Pp
+.Fn CMAC_CTX_free
+calls
+.Fn CMAC_CTX_cleanup ,
+then frees
+.Fa ctx
+itself.
+If
+.Fa ctx
+is
+.Dv NULL ,
+no action occurs.
+.Sh RETURN VALUES
+.Fn CMAC_CTX_new
+returns the new context object or
+.Dv NULL
+in case of failure.
+It succeeds unless memory is exhausted.
+.Pp
+.Fn CMAC_Init ,
+.Fn CMAC_Update ,
+.Fn CMAC_Final ,
+.Fn CMAC_resume ,
+and
+.Fn CMAC_CTX_copy
+return 1 on success or 0 on failure.
+.Fn CMAC_Init
+fails if initializing the embedded
+.Vt EVP_CIPHER_CTX
+object fails.
+The others fail if
+.Fa in_ctx
+is uninitialized.
+.Fn CMAC_Update
+and
+.Fn CMAC_Final
+also fail if encrypting a block fails, and
+.Fn CMAC_CTX_copy
+if copying the embedded
+.Vt EVP_CIPHER_CTX
+object fails, which can for example happen when memory is exhausted.
+.Pp
+.Fn CMAC_CTX_get0_cipher_ctx
+returns an internal pointer to the
+.Vt EVP_CIPHER_CTX
+object that is embedded in
+.Fa ctx .
+.Sh ERRORS
+The CMAC code itself does not use the
+.In openssl/err.h
+framework, so in general, the reasons for failure cannot be found out with
+.Xr ERR_get_error 3 .
+However, since the
+.Xr EVP_Cipher 3
+functions are used internally, entries may still get pushed onto
+the error stack in some cases of failure.
+.Sh SEE ALSO
+.Xr EVP_aes_128_cbc 3 ,
+.Xr EVP_Cipher 3 ,
+.Xr EVP_DigestInit 3 ,
+.Xr EVP_PKEY_CTX_new_id 3 ,
+.Xr HMAC 3
+.Sh STANDARDS
+.Rs
+.%A Morris Dworkin
+.%T "Recommendation for Block Cipher Modes of Operation:\
+ The CMAC Mode for Authentication"
+.%I National Institute of Standards and Technology
+.%R NIST Special Publication 800-38B
+.%U https://doi.org/10.6028/NIST.SP.800-38B
+.%C Gaithersburg, Maryland
+.%D May 2005, updated October 6, 2016
+.Re
+.Sh HISTORY
+These functions first appeared in OpenSSL 1.0.1
+and have been available since
+.Ox 5.3 .
diff --git a/lib/libcrypto/man/EVP_DigestInit.3 b/lib/libcrypto/man/EVP_DigestInit.3
index cefd546af37..d8f452fe4c2 100644
--- a/lib/libcrypto/man/EVP_DigestInit.3
+++ b/lib/libcrypto/man/EVP_DigestInit.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_DigestInit.3,v 1.18 2019/08/25 17:08:20 schwarze Exp $
+.\" $OpenBSD: EVP_DigestInit.3,v 1.19 2020/06/24 16:06:27 schwarze Exp $
 .\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000
 .\" selective merge up to: OpenSSL a95d7574 Jul 2 12:16:38 2017 -0400
 .\"
@@ -68,7 +68,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 25 2019 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt EVP_DIGESTINIT 3
 .Os
 .Sh NAME
@@ -671,6 +671,7 @@ main(int argc, char *argv[])
 .Ed
 .Sh SEE ALSO
 .Xr BIO_f_md 3 ,
+.Xr CMAC_Init 3 ,
 .Xr evp 3 ,
 .Xr EVP_BytesToKey 3 ,
 .Xr EVP_DigestSignInit 3 ,
diff --git a/lib/libcrypto/man/HMAC.3 b/lib/libcrypto/man/HMAC.3
index b2a0e2836ef..b76d8b28691 100644
--- a/lib/libcrypto/man/HMAC.3
+++ b/lib/libcrypto/man/HMAC.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: HMAC.3,v 1.16 2019/12/14 09:04:51 tb Exp $
+.\" $OpenBSD: HMAC.3,v 1.17 2020/06/24 16:06:27 schwarze Exp $
 .\" full merge up to: OpenSSL crypto/hmac a528d4f0 Oct 27 13:40:11 2015 -0400
 .\" selective merge up to: OpenSSL man3/HMAC b3696a55 Sep 2 09:35:50 2017 -0400
 .\"
@@ -52,7 +52,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 14 2019 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt HMAC 3
 .Os
 .Sh NAME
@@ -365,6 +365,7 @@ if none was set.
 returns the length in bytes of the underlying hash function output
 or 0 on error.
 .Sh SEE ALSO
+.Xr CMAC_Init 3 ,
 .Xr EVP_DigestInit 3
 .Sh STANDARDS
 RFC 2104
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index c613fdc293e..de6e446f2f5 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.168 2020/06/12 11:37:42 schwarze Exp $
+# $OpenBSD: Makefile,v 1.169 2020/06/24 16:06:26 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -68,6 +68,7 @@ MAN=	\
 	BN_swap.3 \
 	BN_zero.3 \
 	BUF_MEM_new.3 \
+	CMAC_Init.3 \
 	CMS_ContentInfo_new.3 \
 	CMS_add0_cert.3 \
 	CMS_add1_recipient_cert.3 \
diff --git a/lib/libcrypto/man/crypto.3 b/lib/libcrypto/man/crypto.3
index cbc03543aed..9f29698e80c 100644
--- a/lib/libcrypto/man/crypto.3
+++ b/lib/libcrypto/man/crypto.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: crypto.3,v 1.23 2019/11/02 15:28:04 schwarze Exp $
+.\"	$OpenBSD: crypto.3,v 1.24 2020/06/24 16:06:27 schwarze Exp $
 .\"	OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org> and
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 2 2019 $
+.Dd $Mdocdate: June 24 2020 $
 .Dt CRYPTO 3
 .Os
 .Sh NAME
@@ -93,6 +93,7 @@ and
 .Sy Authentication codes and hash functions
 offered include
 .Xr EVP_DigestInit 3 ,
+.Xr CMAC_Init 3 ,
 .Xr HMAC 3 ,
 .Xr MD4 3 ,
 .Xr MD5 3 ,