Scatterlist Cryptographic API
INTRODUCTION
The Scatterlist Crypto API takes page vectors (scatterlists) as arguments, and works directly on pages. In some cases (e.g. ECB mode ciphers), this will allow for pages to be encrypted in-place with no copying.
Scatterlist Crypto API使用页向量(scatterlists)作为参数,并且直接按页面工作。在某些情况下(例如ECB模式密码),这将允许页面不需复制而按原地加密。
One of the initial goals of this design was to readily support IPsec, so that processing can be applied to paged skb's without the need for linearization.
这个设计的初始目标之一是快捷地支持IPsec,因此处理过程能够应用于页面式缓冲区(paged skb)而无需线性化。
DETAILS
At the lowest level are algorithms, which register dynamically with the API.
处于最底层的是算法,需动态地注册到API中。
'Transforms' are user-instantiated objects, which maintain state, handle all of the implementation logic (e.g. manipulating page vectors) and provide an abstraction to the underlying algorithms. However, at the user level they are very simple.
“转换”是由用户实例化的对象,它维护状态、处理所有执行逻辑(例如操纵页面向量)并且对底层算法提供一个抽象接口。然而,在用户层它们是非常简单的。
Conceptually, the API layering looks like this:
[transform api] (user interface)
[transform ops] (per-type logic glue e.g. cipher.c, compress.c)
[algorithm api] (for registering algorithms)
从概念上讲,API分层看似这样:
[“转换”API](用户界面)
[“转换”OPS](每种类型的接口逻辑模块,例如cipher.c, compress.c)
[“算法”API](用于注册算法)
The idea is to make the user interface and algorithm registration API very simple, while hiding the core logic from both. Many good ideas from existing APIs such as Cryptoapi and Nettle have been adapted for this.
这样做是为了使得“用户界面”和“算法注册”API更加简单,而隐藏了两者之间的核心逻辑。诸如Cryptoapi和Nettle等许多现存API的良好设计都做了这方面改编。
The API currently supports five main types of transforms: AEAD (Authenticated Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and Hashes.
API目前支持五种主要类型“转换”:AEAD(带关联数据的加密认证)、分组加密、加密、压缩和哈希算法。
Please note that Block Ciphers is somewhat of a misnomer. It is in fact meant to support all ciphers including stream ciphers. The difference between Block Ciphers and Ciphers is that the latter operates on exactly one block while the former can operate on an arbitrary amount of data, subject to block size requirements (i.e., non-stream ciphers can only process multiples of blocks).
请注意,分组加密多少有些用词不准。它实际上意味着支持所有加密,包含流加密。分组加密和加密之间不同之处是后者作用于一个精确的数据块而前者可以作用于任意数量的数据,但要求以数据块大小为单位(例如非流密码只能处理数据块整数倍的数据)
Support for hardware crypto devices via an asynchronous interface is under development.
通过一个异步接口支持硬件加密设备的工作正在开发中。
Here's an example of how to use the API:
这是一个如何使用API的例子:
#include <linux/crypto.h>
#include <linux/err.h>
#include <linux/scatterlist.h>
struct scatterlist sg[2];
char result[128];
struct crypto_hash *tfm;
struct hash_desc desc;
tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC);
if (IS_ERR(tfm)) fail();
/* ... set up the scatterlists ... */
desc.tfm = tfm;
desc.flags = 0;
if (crypto_hash_digest(&desc, sg, 2, result)) fail();
crypto_free_hash(tfm);
Many real examples are available in the regression test module (tcrypt.c).
在回归测试模块(tcrypt.c)中提供了许多实际范例
DEVELOPER NOTES
Transforms may only be allocated in user context, and cryptographic methods may only be called from softirq and user contexts. For transforms with a setkey method it too should only be called from user context.
“转换”只能够在用户上下文中分配,加密方法只能从软件中断和用户上下文中回调。对于带SetKey方法的“转换”也只能够从用户上下文中回调。
When using the API for ciphers, performance will be optimal if each scatterlist contains data which is a multiple of the cipher's block size (typically 8 bytes). This prevents having to do any copying across non-aligned page fragment boundaries.
当使用API进行加密时,如果每个scatterlist包含了密码块大小(典型值是8字节)整数倍的数据时,执行性能将是最佳的。这可以防止做跨非对齐页面碎片边界的任何数据拷贝。
ADDING NEW ALGORITHMS
When submitting a new algorithm for inclusion, a mandatory requirement is that at least a few test vectors from known sources (preferably standards) be included.
当提要一个新的列入算法时,一个强制性要求是至少包含一些来源于已知的的资源(更好的标准)的测试向量。
Converting existing well known code is preferred, as it is more likely to have been reviewed and widely tested. If submitting code from LGPL sources, please consider changing the license to GPL (see section 3 of the LGPL).
转化现有的知名的代码是首选方法,因为它更有可能被广泛地审查和测试。如果从LGPL资源中提交代码,请注意改变许可为GPL(请参阅LGPL许可条款3)。
Algorithms submitted must also be generally patent-free (e.g. IDEA will not be included in the mainline until around 2011), and be based on a recognized standard and/or have been subjected to appropriate peer review.
提交的算法必须通常是免专利授权的(例如,IDEA将一直到2011年左右才会包含进主线中),并且必须是基于一个公认的标准和/或已经受到合适的专家评审。
Also check for any RFCs which may relate to the use of specific algorithms, as well as general application notes such as RFC2451 ("The ESP CBC-Mode Cipher Algorithms").
并且,还要检查任何RFC所涉及的具体算法使用说明,以及一般应用笔记,例如RFC2451("The ESP CBC-Mode Cipher Algorithms" ESP CBC模式密码算法)。
It's a good idea to avoid using lots of macros and use inlined functions instead, as gcc does a good job with inlining, while excessive use of macros can cause compilation problems on some platforms.
为避免使用大量的宏而替代地使用内联函数是一个非常好的主意,因为gcc能良好地处理内联,然而过度地使用宏可能会在一些平台上导致编译问题。
Also check the TODO list at the web site listed below to see what people might already be working on.
另外,检查网站上的TODO列表,并继续往下看哪些已经正在做的工作。
BUGS
Send bug reports to:
linux-crypto@vger.kernel.org
Cc: Herbert Xu <herbert@gondor.apana.org.au>,
David S. Miller <davem@redhat.com>
发送漏洞报告给:
linux-crypto@vger.kernel.org,
抄送:
Herbert Xu <herbert@gondor.apana.org.au>,
David S. Miller <davem@redhat.com>
FURTHER INFORMATION
For further patches and various updates, including the current TODO list, see:
http://gondor.apana.org.au/~herbert/crypto/
如需进一步的补丁程序和各种更新,包含当前的TODO列表,参阅:
http://gondor.apana.org.au/~herbert/crypto/
AUTHORS
James Morris
David S. Miller
Herbert Xu
CREDITS
The following people provided invaluable feedback during the development of the API:
在API开发过程中,以下人员提供了宝贵的反馈意见:
Alexey Kuznetzov
Rusty Russell
Herbert Valerio Riedel
Jeff Garzik
Michael Richardson
Andrew Morton
Ingo Oeser
Christoph Hellwig
Portions of this API were derived from the following projects:
API部分代码是来自于以下项目:
Kerneli Cryptoapi (http://www.kerneli.org/)
Alexander Kjeldaas
Herbert Valerio Riedel
Kyle McMartin
Jean-Luc Cooke
David Bryson
Clemens Fruhwirth
Tobias Ringstrom
Harald Welte
and;
和;
Nettle (http://www.lysator.liu.se/~nisse/nettle/)
Niels Möller
Original developers of the crypto algorithms:
加密算法的原始开发者:
Dana L. How (DES)
Andrew Tridgell and Steve French (MD4)
Colin Plumb (MD5)
Steve Reid (SHA1)
Jean-Luc Cooke (SHA256, SHA384, SHA512)
Kazunori Miyazawa / USAGI (HMAC)
Matthew Skala (Twofish)
Dag Arne Osvik (Serpent)
Brian Gladman (AES)
Kartikey Mahendra Bhatt (CAST6)
Jon Oberheide (ARC4)
Jouni Malinen (Michael MIC)
NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
SHA1 algorithm contributors:
Jean-Francois Dive
DES algorithm contributors:
Raimar Falke
Gisle Sælensminde
Niels Möller
Blowfish algorithm contributors:
Herbert Valerio Riedel
Kyle McMartin
Twofish algorithm contributors:
Werner Koch
Marc Mutz
SHA256/384/512 algorithm contributors:
Andrew McDonald
Kyle McMartin
Herbert Valerio Riedel
AES algorithm contributors:
Alexander Kjeldaas
Herbert Valerio Riedel
Kyle McMartin
Adam J. Richter
Fruhwirth Clemens (i586)
Linus Torvalds (i586)
CAST5 algorithm contributors:
Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
TEA/XTEA algorithm contributors:
Aaron Grothe
Michael Ringe
Khazad algorithm contributors:
Aaron Grothe
Whirlpool algorithm contributors:
Aaron Grothe
Jean-Luc Cooke
Anubis algorithm contributors:
Aaron Grothe
Tiger algorithm contributors:
Aaron Grothe
VIA PadLock contributors:
Michal Ludvig
Camellia algorithm contributors:
NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
Please send any credits updates or corrections to:
Herbert Xu <herbert@gondor.apana.org.au>