Merge branch 'linus' of git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6

      <para>type:

       <itemizedlist>

        <listitem>

         <para>blkcipher for synchronous block ciphers</para>

        </listitem>

        <listitem>

         <para>ablkcipher for asynchronous block ciphers</para>

         <para>skcipher for symmetric key ciphers</para>

        </listitem>

        <listitem>

         <para>cipher for single block ciphers that may be used with

     <listitem>

      <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para>

     </listitem>

     <listitem>

      <para>CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher</para>

     </listitem>

     <listitem>

      <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of

       CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /

      v                   v

+-----------+       +-----------+

|           |       |           |

| ablkcipher|       |   ahash   |

|  skcipher |       |   ahash   |

|   (ctr)   | ---+  |  (ghash)  |

+-----------+    |  +-----------+

                 |

      <listitem>

       <para>

        The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API

        The GCM AEAD cipher type implementation now invokes the SKCIPHER API

        with the instantiated CTR(AES) cipher handle.

       </para>

       </para>

       <para>

        That means that the ABLKCIPHER implementation of CTR(AES) only

        That means that the SKCIPHER implementation of CTR(AES) only

        implements the CTR block chaining mode. After performing the block

        chaining operation, the CIPHER implementation of AES is invoked.

       </para>

      <listitem>

       <para>

        The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES

        The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES

        cipher handle to encrypt one block.

       </para>

      </listitem>

     <para>

      For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The

      ASCII art picture above applies as well with the difference that only

      step (4) is used and the ABLKCIPHER block chaining mode is CBC.

      step (4) is used and the SKCIPHER block chaining mode is CBC.

     </para>

    </sect2>

    </sect2>

   </sect1>

   <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title>

   <sect1><title>Multi-Block Ciphers</title>

    <para>

     Example of transformations: cbc(aes), ecb(arc4), ...

    </para>

    <para>

     This section describes the multi-block cipher transformation

     implementations for both synchronous [BLKCIPHER] and

     asynchronous [ABLKCIPHER] case. The multi-block ciphers are

     implementations. The multi-block ciphers are

     used for transformations which operate on scatterlists of

     data supplied to the transformation functions. They output

     the result into a scatterlist of data as well.

    <sect2><title>Registration Specifics</title>

     <para>

      The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms

      The registration of multi-block cipher algorithms

      is one of the most standard procedures throughout the crypto API.

     </para>

     <para>

      Note, if a cipher implementation requires a proper alignment

      of data, the caller should use the functions of

      crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask()

      respectively to identify a memory alignment mask. The kernel

      crypto API is able to process requests that are unaligned.

      crypto_skcipher_alignmask() to identify a memory alignment mask.

      The kernel crypto API is able to process requests that are unaligned.

      This implies, however, additional overhead as the kernel

      crypto API needs to perform the realignment of the data which

      may imply moving of data.

     <para>

      Please refer to the single block cipher description for schematics

      of the block cipher usage. The usage patterns are exactly the same

      for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER].

      of the block cipher usage.

     </para>

    </sect2>

    <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title>

     <para>

      There are a couple of specifics to the [ABLKCIPHER] interface.

      There are a couple of specifics to the asynchronous interface.

     </para>

     <para>

!Finclude/linux/crypto.h cipher_alg

!Finclude/crypto/rng.h rng_alg

   </sect1>

   <sect1><title>Asynchronous Block Cipher API</title>

   <sect1><title>Symmetric Key Cipher API</title>

!Pinclude/crypto/skcipher.h Symmetric Key Cipher API

!Finclude/crypto/skcipher.h crypto_alloc_skcipher

!Finclude/crypto/skcipher.h crypto_free_skcipher

!Finclude/crypto/skcipher.h crypto_has_skcipher

!Finclude/crypto/skcipher.h crypto_skcipher_ivsize

!Finclude/crypto/skcipher.h crypto_skcipher_blocksize

!Finclude/crypto/skcipher.h crypto_skcipher_setkey

!Finclude/crypto/skcipher.h crypto_skcipher_reqtfm

!Finclude/crypto/skcipher.h crypto_skcipher_encrypt

!Finclude/crypto/skcipher.h crypto_skcipher_decrypt

   </sect1>

   <sect1><title>Symmetric Key Cipher Request Handle</title>

!Pinclude/crypto/skcipher.h Symmetric Key Cipher Request Handle

!Finclude/crypto/skcipher.h crypto_skcipher_reqsize

!Finclude/crypto/skcipher.h skcipher_request_set_tfm

!Finclude/crypto/skcipher.h skcipher_request_alloc

!Finclude/crypto/skcipher.h skcipher_request_free

!Finclude/crypto/skcipher.h skcipher_request_set_callback

!Finclude/crypto/skcipher.h skcipher_request_set_crypt

   </sect1>

   <sect1><title>Asynchronous Block Cipher API - Deprecated</title>

!Pinclude/linux/crypto.h Asynchronous Block Cipher API

!Finclude/linux/crypto.h crypto_alloc_ablkcipher

!Finclude/linux/crypto.h crypto_free_ablkcipher

!Finclude/linux/crypto.h crypto_ablkcipher_encrypt

!Finclude/linux/crypto.h crypto_ablkcipher_decrypt

   </sect1>

   <sect1><title>Asynchronous Cipher Request Handle</title>

   <sect1><title>Asynchronous Cipher Request Handle - Deprecated</title>

!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle

!Finclude/linux/crypto.h crypto_ablkcipher_reqsize

!Finclude/linux/crypto.h ablkcipher_request_set_tfm

!Finclude/crypto/aead.h aead_request_free

!Finclude/crypto/aead.h aead_request_set_callback

!Finclude/crypto/aead.h aead_request_set_crypt

!Finclude/crypto/aead.h aead_request_set_assoc

!Finclude/crypto/aead.h aead_request_set_ad

   </sect1>

   <sect1><title>Synchronous Block Cipher API</title>

   <sect1><title>Synchronous Block Cipher API - Deprecated</title>

!Pinclude/linux/crypto.h Synchronous Block Cipher API

!Finclude/linux/crypto.h crypto_alloc_blkcipher

!Finclude/linux/crypto.h crypto_free_blkcipher

!Finclude/linux/crypto.h crypto_cipher_setkey

!Finclude/linux/crypto.h crypto_cipher_encrypt_one

!Finclude/linux/crypto.h crypto_cipher_decrypt_one

   </sect1>

   <sect1><title>Synchronous Message Digest API</title>

!Pinclude/linux/crypto.h Synchronous Message Digest API

!Finclude/linux/crypto.h crypto_alloc_hash

!Finclude/linux/crypto.h crypto_free_hash

!Finclude/linux/crypto.h crypto_has_hash

!Finclude/linux/crypto.h crypto_hash_blocksize

!Finclude/linux/crypto.h crypto_hash_digestsize

!Finclude/linux/crypto.h crypto_hash_init

!Finclude/linux/crypto.h crypto_hash_update

!Finclude/linux/crypto.h crypto_hash_final

!Finclude/linux/crypto.h crypto_hash_digest

!Finclude/linux/crypto.h crypto_hash_setkey

   </sect1>

   <sect1><title>Message Digest Algorithm Definitions</title>

!Pinclude/crypto/hash.h Message Digest Algorithm Definitions

!Finclude/crypto/rng.h crypto_alloc_rng

!Finclude/crypto/rng.h crypto_rng_alg

!Finclude/crypto/rng.h crypto_free_rng

!Finclude/crypto/rng.h crypto_rng_generate

!Finclude/crypto/rng.h crypto_rng_get_bytes

!Finclude/crypto/rng.h crypto_rng_reset

!Finclude/crypto/rng.h crypto_rng_seedsize

!Cinclude/crypto/rng.h

   </sect1>

   <sect1><title>Asymmetric Cipher API</title>

!Pinclude/crypto/akcipher.h Generic Public Key API

!Finclude/crypto/akcipher.h akcipher_alg

!Finclude/crypto/akcipher.h akcipher_request

!Finclude/crypto/akcipher.h crypto_alloc_akcipher

!Finclude/crypto/akcipher.h crypto_free_akcipher

!Finclude/crypto/akcipher.h crypto_akcipher_set_pub_key

!Finclude/crypto/akcipher.h crypto_akcipher_set_priv_key

   </sect1>

   <sect1><title>Asymmetric Cipher Request Handle</title>

!Finclude/crypto/akcipher.h akcipher_request_alloc

!Finclude/crypto/akcipher.h akcipher_request_free

!Finclude/crypto/akcipher.h akcipher_request_set_callback

!Finclude/crypto/akcipher.h akcipher_request_set_crypt

!Finclude/crypto/akcipher.h crypto_akcipher_maxsize

!Finclude/crypto/akcipher.h crypto_akcipher_encrypt

!Finclude/crypto/akcipher.h crypto_akcipher_decrypt

!Finclude/crypto/akcipher.h crypto_akcipher_sign

!Finclude/crypto/akcipher.h crypto_akcipher_verify

   </sect1>

  </chapter>

  <chapter id="Code"><title>Code Examples</title>

   <sect1><title>Code Example For Asynchronous Block Cipher Operation</title>

   <sect1><title>Code Example For Symmetric Key Cipher Operation</title>

    <programlisting>

struct tcrypt_result {

};

/* tie all data structures together */

struct ablkcipher_def {

struct skcipher_def {

	struct scatterlist sg;

	struct crypto_ablkcipher *tfm;

	struct ablkcipher_request *req;

	struct crypto_skcipher *tfm;

	struct skcipher_request *req;

	struct tcrypt_result result;

};

/* Callback function */

static void test_ablkcipher_cb(struct crypto_async_request *req, int error)

static void test_skcipher_cb(struct crypto_async_request *req, int error)

{

	struct tcrypt_result *result = req->data;

}

/* Perform cipher operation */

static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk,

static unsigned int test_skcipher_encdec(struct skcipher_def *sk,

					 int enc)

{

	int rc = 0;

	if (enc)

		rc = crypto_ablkcipher_encrypt(ablk->req);

		rc = crypto_skcipher_encrypt(sk->req);

	else

		rc = crypto_ablkcipher_decrypt(ablk->req);

		rc = crypto_skcipher_decrypt(sk->req);

	switch (rc) {

	case 0:

	case -EINPROGRESS:

	case -EBUSY:

		rc = wait_for_completion_interruptible(

			&ablk->result.completion);

		if (!rc && !ablk->result.err) {

			reinit_completion(&ablk->result.completion);

			&sk->result.completion);

		if (!rc && !sk->result.err) {

			reinit_completion(&sk->result.completion);

			break;

		}

	default:

		pr_info("ablkcipher encrypt returned with %d result %d\n",

		       rc, ablk->result.err);

		pr_info("skcipher encrypt returned with %d result %d\n",

			rc, sk->result.err);

		break;

	}

	init_completion(&ablk->result.completion);

	init_completion(&sk->result.completion);

	return rc;

}

/* Initialize and trigger cipher operation */

static int test_ablkcipher(void)

static int test_skcipher(void)

{

	struct ablkcipher_def ablk;

	struct crypto_ablkcipher *ablkcipher = NULL;

	struct ablkcipher_request *req = NULL;

	struct skcipher_def sk;

	struct crypto_skcipher *skcipher = NULL;

	struct skcipher_request *req = NULL;

	char *scratchpad = NULL;

	char *ivdata = NULL;

	unsigned char key[32];

	int ret = -EFAULT;

	ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0);

	if (IS_ERR(ablkcipher)) {

		pr_info("could not allocate ablkcipher handle\n");

		return PTR_ERR(ablkcipher);

	skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0);

	if (IS_ERR(skcipher)) {

		pr_info("could not allocate skcipher handle\n");

		return PTR_ERR(skcipher);

	}

	req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL);

	req = skcipher_request_alloc(skcipher, GFP_KERNEL);

	if (IS_ERR(req)) {

		pr_info("could not allocate request queue\n");

		ret = PTR_ERR(req);

		goto out;

	}

	ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,

					test_ablkcipher_cb,

					&ablk.result);

	skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,

				      test_skcipher_cb,

				      &sk.result);

	/* AES 256 with random key */

	get_random_bytes(&key, 32);

	if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) {

	if (crypto_skcipher_setkey(skcipher, key, 32)) {

		pr_info("key could not be set\n");

		ret = -EAGAIN;

		goto out;

	}

	get_random_bytes(scratchpad, 16);

	ablk.tfm = ablkcipher;

	ablk.req = req;

	sk.tfm = skcipher;

	sk.req = req;

	/* We encrypt one block */

	sg_init_one(&ablk.sg, scratchpad, 16);

	ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata);

	init_completion(&ablk.result.completion);

	sg_init_one(&sk.sg, scratchpad, 16);

	skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata);

	init_completion(&sk.result.completion);

	/* encrypt data */

	ret = test_ablkcipher_encdec(&ablk, 1);

	ret = test_skcipher_encdec(&sk, 1);

	if (ret)

		goto out;

	pr_info("Encryption triggered successfully\n");

out:

	if (ablkcipher)

		crypto_free_ablkcipher(ablkcipher);

	if (skcipher)

		crypto_free_skcipher(skcipher);

	if (req)

		ablkcipher_request_free(req);

		skcipher_request_free(req);

	if (ivdata)

		kfree(ivdata);

	if (scratchpad)

    </programlisting>

   </sect1>

   <sect1><title>Code Example For Synchronous Block Cipher Operation</title>

    <programlisting>

static int test_blkcipher(void)

{

	struct crypto_blkcipher *blkcipher = NULL;

	char *cipher = "cbc(aes)";

	// AES 128

	charkey =

"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";

	chariv =

"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";

	unsigned int ivsize = 0;

	char *scratchpad = NULL; // holds plaintext and ciphertext

	struct scatterlist sg;

	struct blkcipher_desc desc;

	int ret = -EFAULT;

	blkcipher = crypto_alloc_blkcipher(cipher, 0, 0);

	if (IS_ERR(blkcipher)) {

		printk("could not allocate blkcipher handle for %s\n", cipher);

		return -PTR_ERR(blkcipher);

	}

	if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) {

		printk("key could not be set\n");

		ret = -EAGAIN;

		goto out;

	}

	ivsize = crypto_blkcipher_ivsize(blkcipher);

	if (ivsize) {

		if (ivsize != strlen(iv))

			printk("IV length differs from expected length\n");

		crypto_blkcipher_set_iv(blkcipher, iv, ivsize);

	}

	scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL);

	if (!scratchpad) {

		printk("could not allocate scratchpad for %s\n", cipher);

		goto out;

	}

	/* get some random data that we want to encrypt */

	get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher));

	desc.flags = 0;

	desc.tfm = blkcipher;

	sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher));

	/* encrypt data in place */

	crypto_blkcipher_encrypt(&desc, &sg, &sg,

				 crypto_blkcipher_blocksize(blkcipher));

	/* decrypt data in place

	 * crypto_blkcipher_decrypt(&desc, &sg, &sg,

	 */			 crypto_blkcipher_blocksize(blkcipher));

	printk("Cipher operation completed\n");

	return 0;

out:

	if (blkcipher)

		crypto_free_blkcipher(blkcipher);

	if (scratchpad)

		kzfree(scratchpad);

	return ret;

}

    </programlisting>

   </sect1>

   <sect1><title>Code Example For Use of Operational State Memory With SHASH</title>

    <programlisting>

Here's an example of how to use the API:

	#include <linux/crypto.h>

	#include <crypto/ahash.h>

	#include <linux/err.h>

	#include <linux/scatterlist.h>

	struct scatterlist sg[2];

	char result[128];

	struct crypto_hash *tfm;

	struct hash_desc desc;

	struct crypto_ahash *tfm;

	struct ahash_request *req;

	tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC);

	tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);

	if (IS_ERR(tfm))

		fail();

	/* ... set up the scatterlists ... */

	desc.tfm = tfm;

	desc.flags = 0;

	req = ahash_request_alloc(tfm, GFP_ATOMIC);

	if (!req)

		fail();

	ahash_request_set_callback(req, 0, NULL, NULL);

	ahash_request_set_crypt(req, sg, result, 2);

	if (crypto_hash_digest(&desc, sg, 2, result))

	if (crypto_ahash_digest(req))

		fail();

	crypto_free_hash(tfm);

	ahash_request_free(req);

	crypto_free_ahash(tfm);

Many real examples are available in the regression test module (tcrypt.c).

BCM6368 Random number generator

Required properties:

- compatible : should be "brcm,bcm6368-rng"

- reg : Specifies base physical address and size of the registers

- clocks : phandle to clock-controller plus clock-specifier pair

- clock-names : "ipsec" as a clock name

Example:

	random: rng@10004180 {

		compatible = "brcm,bcm6368-rng";

		reg = <0x10004180 0x14>;

		clocks = <&periph_clk 18>;

		clock-names = "ipsec";

	};

* Microchip PIC32 Random Number Generator

The PIC32 RNG provides a pseudo random number generator which can be seeded by

another true random number generator.

Required properties:

- compatible : should be "microchip,pic32mzda-rng"

- reg : Specifies base physical address and size of the registers.

- clocks: clock phandle.

Example:

	rng: rng@1f8e6000 {

		compatible = "microchip,pic32mzda-rng";

		reg = <0x1f8e6000 0x1000>;

		clocks = <&PBCLK5>;

	};

HWRNG support for the n2_rng driver

Required properties:

- reg		: base address to sample from

- compatible	: should contain one of the following

	RNG versions:

	- 'SUNW,n2-rng' for Niagara 2 Platform (SUN UltraSPARC T2 CPU)

	- 'SUNW,vf-rng' for Victoria Falls Platform (SUN UltraSPARC T2 Plus CPU)

	- 'SUNW,kt-rng' for Rainbow/Yosemite Falls Platform (SUN SPARC T3/T4), (UltraSPARC KT/Niagara 3 - development names)

	more recent systems (after Oracle acquisition of SUN)

	- 'ORCL,m4-rng' for SPARC T5/M5

	- 'ORCL,m7-rng' for SPARC T7/M7

Examples:

/* linux LDOM on SPARC T5-2 */

Node 0xf029a4f4

	.node:  f029a4f4

	rng-#units:  00000002

	compatible: 'ORCL,m4-rng'

	reg:  0000000e

	name: 'random-number-generator'

/* solaris on SPARC M7-8 */

Node 0xf028c08c

	rng-#units:  00000003

	compatible: 'ORCL,m7-rng'

	reg:  0000000e

	name:  'random-number-generator'

PS: see as well prtconfs.git by DaveM