summaryrefslogtreecommitdiff
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2016-03-17 11:22:54 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2016-03-17 11:22:54 -0700
commit70477371dc350746d10431d74f0f213a8d59924c (patch)
tree6271978b6e4ee4b1e6f22775ad7fc0930c09d3ee /Documentation/DocBook
parent09fd671ccb2475436bd5f597f751ca4a7d177aea (diff)
parent34074205bb9f04b416efb3cbedcd90f418c86200 (diff)
Merge branch 'linus' of git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6
Pull crypto update from Herbert Xu: "Here is the crypto update for 4.6: API: - Convert remaining crypto_hash users to shash or ahash, also convert blkcipher/ablkcipher users to skcipher. - Remove crypto_hash interface. - Remove crypto_pcomp interface. - Add crypto engine for async cipher drivers. - Add akcipher documentation. - Add skcipher documentation. Algorithms: - Rename crypto/crc32 to avoid name clash with lib/crc32. - Fix bug in keywrap where we zero the wrong pointer. Drivers: - Support T5/M5, T7/M7 SPARC CPUs in n2 hwrng driver. - Add PIC32 hwrng driver. - Support BCM6368 in bcm63xx hwrng driver. - Pack structs for 32-bit compat users in qat. - Use crypto engine in omap-aes. - Add support for sama5d2x SoCs in atmel-sha. - Make atmel-sha available again. - Make sahara hashing available again. - Make ccp hashing available again. - Make sha1-mb available again. - Add support for multiple devices in ccp. - Improve DMA performance in caam. - Add hashing support to rockchip" * 'linus' of git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6: (116 commits) crypto: qat - remove redundant arbiter configuration crypto: ux500 - fix checks of error code returned by devm_ioremap_resource() crypto: atmel - fix checks of error code returned by devm_ioremap_resource() crypto: qat - Change the definition of icp_qat_uof_regtype hwrng: exynos - use __maybe_unused to hide pm functions crypto: ccp - Add abstraction for device-specific calls crypto: ccp - CCP versioning support crypto: ccp - Support for multiple CCPs crypto: ccp - Remove check for x86 family and model crypto: ccp - memset request context to zero during import lib/mpi: use "static inline" instead of "extern inline" lib/mpi: avoid assembler warning hwrng: bcm63xx - fix non device tree compatibility crypto: testmgr - allow rfc3686 aes-ctr variants in fips mode. crypto: qat - The AE id should be less than the maximal AE number lib/mpi: Endianness fix crypto: rockchip - add hash support for crypto engine in rk3288 crypto: xts - fix compile errors crypto: doc - add skcipher API documentation crypto: doc - update AEAD AD handling ...
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/crypto-API.tmpl242
1 files changed, 98 insertions, 144 deletions
diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl
index 07df23ea06e4..348619fcafb8 100644
--- a/Documentation/DocBook/crypto-API.tmpl
+++ b/Documentation/DocBook/crypto-API.tmpl
@@ -348,10 +348,7 @@
<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
@@ -485,6 +482,9 @@
<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 /
decompression instead of performing the operation on one
@@ -597,7 +597,7 @@ kernel crypto API | IPSEC Layer
v v
+-----------+ +-----------+
| | | |
-| ablkcipher| | ahash |
+| skcipher | | ahash |
| (ctr) | ---+ | (ghash) |
+-----------+ | +-----------+
|
@@ -658,7 +658,7 @@ kernel crypto API | IPSEC Layer
<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>
@@ -669,7 +669,7 @@ kernel crypto API | IPSEC Layer
</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>
@@ -677,7 +677,7 @@ kernel crypto API | IPSEC Layer
<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>
@@ -706,7 +706,7 @@ kernel crypto API | IPSEC Layer
<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>
@@ -904,15 +904,14 @@ kernel crypto API | Caller
</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.
@@ -921,16 +920,15 @@ kernel crypto API | Caller
<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.
@@ -945,14 +943,13 @@ kernel crypto API | Caller
<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>
@@ -1692,7 +1689,28 @@ read(opfd, out, outlen);
!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
@@ -1704,7 +1722,7 @@ read(opfd, out, outlen);
!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
@@ -1733,10 +1751,9 @@ read(opfd, out, outlen);
!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
@@ -1762,19 +1779,6 @@ read(opfd, out, outlen);
!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/hash.h hash_alg_common
@@ -1825,15 +1829,36 @@ read(opfd, out, outlen);
!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 {
@@ -1842,15 +1867,15 @@ 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-&gt;data;
@@ -1862,15 +1887,15 @@ static void test_ablkcipher_cb(struct crypto_async_request *req, int error)
}
/* Perform cipher operation */
-static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk,
- int enc)
+static unsigned int test_skcipher_encdec(struct skcipher_def *sk,
+ int enc)
{
int rc = 0;
if (enc)
- rc = crypto_ablkcipher_encrypt(ablk-&gt;req);
+ rc = crypto_skcipher_encrypt(sk-&gt;req);
else
- rc = crypto_ablkcipher_decrypt(ablk-&gt;req);
+ rc = crypto_skcipher_decrypt(sk-&gt;req);
switch (rc) {
case 0:
@@ -1878,52 +1903,52 @@ static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk,
case -EINPROGRESS:
case -EBUSY:
rc = wait_for_completion_interruptible(
- &amp;ablk-&gt;result.completion);
- if (!rc &amp;&amp; !ablk-&gt;result.err) {
- reinit_completion(&amp;ablk-&gt;result.completion);
+ &amp;sk-&gt;result.completion);
+ if (!rc &amp;&amp; !sk-&gt;result.err) {
+ reinit_completion(&amp;sk-&gt;result.completion);
break;
}
default:
- pr_info("ablkcipher encrypt returned with %d result %d\n",
- rc, ablk-&gt;result.err);
+ pr_info("skcipher encrypt returned with %d result %d\n",
+ rc, sk-&gt;result.err);
break;
}
- init_completion(&amp;ablk-&gt;result.completion);
+ init_completion(&amp;sk-&gt;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,
- &amp;ablk.result);
+ skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
+ test_skcipher_cb,
+ &amp;sk.result);
/* AES 256 with random key */
get_random_bytes(&amp;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;
@@ -1945,26 +1970,26 @@ static int test_ablkcipher(void)
}
get_random_bytes(scratchpad, 16);
- ablk.tfm = ablkcipher;
- ablk.req = req;
+ sk.tfm = skcipher;
+ sk.req = req;
/* We encrypt one block */
- sg_init_one(&amp;ablk.sg, scratchpad, 16);
- ablkcipher_request_set_crypt(req, &amp;ablk.sg, &amp;ablk.sg, 16, ivdata);
- init_completion(&amp;ablk.result.completion);
+ sg_init_one(&amp;sk.sg, scratchpad, 16);
+ skcipher_request_set_crypt(req, &amp;sk.sg, &amp;sk.sg, 16, ivdata);
+ init_completion(&amp;sk.result.completion);
/* encrypt data */
- ret = test_ablkcipher_encdec(&amp;ablk, 1);
+ ret = test_skcipher_encdec(&amp;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)
@@ -1974,77 +1999,6 @@ out:
</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(&amp;sg, scratchpad, crypto_blkcipher_blocksize(blkcipher));
-
- /* encrypt data in place */
- crypto_blkcipher_encrypt(&amp;desc, &amp;sg, &amp;sg,
- crypto_blkcipher_blocksize(blkcipher));
-
- /* decrypt data in place
- * crypto_blkcipher_decrypt(&amp;desc, &amp;sg, &amp;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>