From patchwork Fri Oct 21 02:59:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephan Mueller X-Patchwork-Id: 9387927 X-Patchwork-Delegate: herbert@gondor.apana.org.au Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 47BB0607F0 for ; Fri, 21 Oct 2016 03:01:00 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4C9C929D73 for ; Fri, 21 Oct 2016 03:01:00 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 4187529D76; Fri, 21 Oct 2016 03:01:00 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 345F329D73 for ; Fri, 21 Oct 2016 03:00:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751665AbcJUDA4 (ORCPT ); Thu, 20 Oct 2016 23:00:56 -0400 Received: from mail.eperm.de ([89.247.134.16]:53672 "EHLO mail.eperm.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751441AbcJUDA4 (ORCPT ); Thu, 20 Oct 2016 23:00:56 -0400 Received: from positron.chronox.de (rrcs-97-79-174-130.sw.biz.rr.com [97.79.174.130]) by mail.eperm.de (Postfix) with ESMTPA id A65F01816080; Fri, 21 Oct 2016 05:00:53 +0200 (CEST) From: Stephan Mueller To: herbert@gondor.apana.org.au Cc: linux-crypto@vger.kernel.org, linux-doc@vger.kernel.org, Harsh Jain Subject: [PATCH v2 7/8] crypto: doc - clarify AEAD memory structure Date: Fri, 21 Oct 2016 04:59:24 +0200 Message-ID: <3596198.suv0AJ2MEx@positron.chronox.de> User-Agent: KMail/5.3.1 (Linux/4.7.7-200.fc24.x86_64; KDE/5.26.0; x86_64; ; ) In-Reply-To: <2053893.WjF01BJSDF@positron.chronox.de> References: <2053893.WjF01BJSDF@positron.chronox.de> MIME-Version: 1.0 Sender: linux-crypto-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The previous description have been misleading and partially incorrect. Reported-by: Harsh Jain Signed-off-by: Stephan Mueller --- crypto/algif_aead.c | 14 ++------------ include/crypto/aead.h | 36 ++++++++++++------------------------ 2 files changed, 14 insertions(+), 36 deletions(-) diff --git a/crypto/algif_aead.c b/crypto/algif_aead.c index 80a0f1a..a0d8377 100644 --- a/crypto/algif_aead.c +++ b/crypto/algif_aead.c @@ -551,18 +551,8 @@ static int aead_recvmsg_sync(struct socket *sock, struct msghdr *msg, int flags) lock_sock(sk); /* - * AEAD memory structure: For encryption, the tag is appended to the - * ciphertext which implies that the memory allocated for the ciphertext - * must be increased by the tag length. For decryption, the tag - * is expected to be concatenated to the ciphertext. The plaintext - * therefore has a memory size of the ciphertext minus the tag length. - * - * The memory structure for cipher operation has the following - * structure: - * AEAD encryption input: assoc data || plaintext - * AEAD encryption output: cipherntext || auth tag - * AEAD decryption input: assoc data || ciphertext || auth tag - * AEAD decryption output: plaintext + * Please see documentation of aead_request_set_crypt for the + * description of the AEAD memory structure expected from the caller. */ if (ctx->more) { diff --git a/include/crypto/aead.h b/include/crypto/aead.h index e725155..03b9762 100644 --- a/include/crypto/aead.h +++ b/include/crypto/aead.h @@ -483,30 +483,18 @@ static inline void aead_request_set_callback(struct aead_request *req, * destination is the ciphertext. For a decryption operation, the use is * reversed - the source is the ciphertext and the destination is the plaintext. * - * For both src/dst the layout is associated data, plain/cipher text, - * authentication tag. - * - * The content of the AD in the destination buffer after processing - * will either be untouched, or it will contain a copy of the AD - * from the source buffer. In order to ensure that it always has - * a copy of the AD, the user must copy the AD over either before - * or after processing. Of course this is not relevant if the user - * is doing in-place processing where src == dst. - * - * IMPORTANT NOTE AEAD requires an authentication tag (MAC). For decryption, - * the caller must concatenate the ciphertext followed by the - * authentication tag and provide the entire data stream to the - * decryption operation (i.e. the data length used for the - * initialization of the scatterlist and the data length for the - * decryption operation is identical). For encryption, however, - * the authentication tag is created while encrypting the data. - * The destination buffer must hold sufficient space for the - * ciphertext and the authentication tag while the encryption - * invocation must only point to the plaintext data size. The - * following code snippet illustrates the memory usage - * buffer = kmalloc(ptbuflen + (enc ? authsize : 0)); - * sg_init_one(&sg, buffer, ptbuflen + (enc ? authsize : 0)); - * aead_request_set_crypt(req, &sg, &sg, ptbuflen, iv); + * The memory structure for cipher operation has the following structure: + * + * - AEAD encryption input: assoc data || plaintext + * - AEAD encryption output: assoc data || cipherntext || auth tag + * - AEAD decryption input: assoc data || ciphertext || auth tag + * - AEAD decryption output: assoc data || plaintext + * + * Albeit the kernel requires the presence of the AAD buffer, however, + * the kernel does not fill the AAD buffer in the output case. If the + * caller wants to have that data buffer filled, the caller must either + * use an in-place cipher operation (i.e. same memory location for + * input/output memory location). */ static inline void aead_request_set_crypt(struct aead_request *req, struct scatterlist *src,