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列表，并继续往下看哪些已经正在做的工作。