From patchwork Mon Nov 23 10:07:02 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Zaborowski X-Patchwork-Id: 7679481 X-Patchwork-Delegate: herbert@gondor.apana.org.au Return-Path: X-Original-To: patchwork-linux-crypto@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 728D2BF90C for ; Mon, 23 Nov 2015 10:07:25 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 8CC752061B for ; Mon, 23 Nov 2015 10:07:24 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 92E55205C1 for ; Mon, 23 Nov 2015 10:07:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753617AbbKWKHT (ORCPT ); Mon, 23 Nov 2015 05:07:19 -0500 Received: from mail-wm0-f44.google.com ([74.125.82.44]:34610 "EHLO mail-wm0-f44.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753612AbbKWKHQ (ORCPT ); Mon, 23 Nov 2015 05:07:16 -0500 Received: by wmvv187 with SMTP id v187so152596648wmv.1 for ; Mon, 23 Nov 2015 02:07:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:date:message-id; bh=iMUVBzK0zhsCEl6H+CpJBB4KR2JS0honjw//+yoWskw=; b=EafjpEGqjhaa5ET9rVXLCMsIDiLZ2BW/9SUqsgrbXLfw4oMPGzo9y1ckn2q2IUdYLP jryZi1jDnt/wXha0FN3WcTzqvyFqm06si2Ob3Hq08sWPGnctXForW4qbTQWSoH3d1DzI /lmnBVHVT/wuzK6hibSdZ9YP1m47nu+ocye2t2yIqPeKnIJaPamfCoYTsRzraaaDVrUL Uei/t558hPOs44E6psiBOGCaxGWH7mUiIXlO3S5K+Ud/iRKHrQSTDLpm3E/6q1O2Dm6O cT12hPhFHq076I59D571OoCKy2OMQOKU0AFD4td3JjgvDPdV6xwjPxpK73uWl1eDeVxu uQ8w== X-Received: by 10.28.96.4 with SMTP id u4mr19166828wmb.52.1448273235470; Mon, 23 Nov 2015 02:07:15 -0800 (PST) Received: from localhost.localdomain (9.Red-2-136-109.dynamicIP.rima-tde.net. [2.136.109.9]) by smtp.gmail.com with ESMTPSA id q1sm12438766wjy.31.2015.11.23.02.07.14 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 23 Nov 2015 02:07:14 -0800 (PST) From: Andrew Zaborowski To: linux-crypto@vger.kernel.org Cc: herbert@gondor.apana.org.au Subject: [PATCH] crypto: Docs blurb about templates. Date: Mon, 23 Nov 2015 11:07:02 +0100 Message-Id: <1448273222-9914-1-git-send-email-andrew.zaborowski@intel.com> X-Mailer: git-send-email 2.1.4 Sender: linux-crypto-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-crypto@vger.kernel.org X-Spam-Status: No, score=-7.4 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI,RP_MATCHES_RCVD,T_DKIM_INVALID,UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Signed-off-by: Andrew Zaborowski --- These are some notes about the template structs that can take some head-scratching to figure out from the code. Please check that this is the current intended use. --- Documentation/crypto/api-intro.txt | 40 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt index 8b49302..39b5caa 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.txt @@ -117,6 +117,46 @@ Also check the TODO list at the web site listed below to see what people might already be working on. +TEMPLATE ALGORITHMS + +Templates dynamically create algorithms based on algorithm names passed +as parameters. In most cases they modify how another algorithm works by +wrapping around an instance of the other algorithm and operating on its +inputs, outputs, and/or the keys. They can call the child transform's +operations in an arbitrary order. The template can convert one algorithm +type to another and may also combine multiple instances of one or +multiple algorithms. + +The following additional types are used with templates: + +* struct crypto_template + Describes the template and has methods to create actual algorithms as + crypto_instance structures. These are not instances of algorithms + (transforms), instances of the template are algorithms. The template + does not appear in /proc/crypto but the algorithms do. The struct + crypto_template does not statically determine the resulting crypto + types. + +* struct crypto_instance + Represents an instance of a template. Its first member is the + "struct crypto_alg alg" which is a dynamically created algorithm that + behaves like any other. The structure also points back to the template + used. The crypto type-specific methods and other algorithm context is + prepended to struct crypto_instance in a way that it's also prepended + to the .alg member. The children algorithm(s) used by the template + instance are pointed to by the crypto_spawn structure(s) normally + appended after the crypto_instance. + + Actual transforms are created when the context is allocated and .init_tfm + is called same as with non-template algorithms, but the .init_tfm + function will need to trigger creation of child transform(s) from the + crypto_spawn structure(s). + +* struct crypto_spawn + Links a template algorithm (crypto_instance) and a reference to one child + algorithm. + + BUGS Send bug reports to: