aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Documentation/DocBook/Makefile2
-rw-r--r--Documentation/DocBook/crypto-API.tmpl2092
2 files changed, 1 insertions, 2093 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index caab9039362f..c75e5d6b8fa8 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -13,7 +13,7 @@ DOCBOOKS := z8530book.xml \
13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ 13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15 80211.xml sh.xml regulator.xml w1.xml \ 15 80211.xml sh.xml regulator.xml w1.xml \
16 writing_musb_glue_layer.xml crypto-API.xml iio.xml 16 writing_musb_glue_layer.xml iio.xml
17 17
18ifeq ($(DOCBOOKS),) 18ifeq ($(DOCBOOKS),)
19 19
diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl
deleted file mode 100644
index 088b79c341ff..000000000000
--- a/Documentation/DocBook/crypto-API.tmpl
+++ /dev/null
@@ -1,2092 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="KernelCryptoAPI">
6 <bookinfo>
7 <title>Linux Kernel Crypto API</title>
8
9 <authorgroup>
10 <author>
11 <firstname>Stephan</firstname>
12 <surname>Mueller</surname>
13 <affiliation>
14 <address>
15 <email>smueller@chronox.de</email>
16 </address>
17 </affiliation>
18 </author>
19 <author>
20 <firstname>Marek</firstname>
21 <surname>Vasut</surname>
22 <affiliation>
23 <address>
24 <email>marek@denx.de</email>
25 </address>
26 </affiliation>
27 </author>
28 </authorgroup>
29
30 <copyright>
31 <year>2014</year>
32 <holder>Stephan Mueller</holder>
33 </copyright>
34
35
36 <legalnotice>
37 <para>
38 This documentation is free software; you can redistribute
39 it and/or modify it under the terms of the GNU General Public
40 License as published by the Free Software Foundation; either
41 version 2 of the License, or (at your option) any later
42 version.
43 </para>
44
45 <para>
46 This program is distributed in the hope that it will be
47 useful, but WITHOUT ANY WARRANTY; without even the implied
48 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
49 See the GNU General Public License for more details.
50 </para>
51
52 <para>
53 You should have received a copy of the GNU General Public
54 License along with this program; if not, write to the Free
55 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
56 MA 02111-1307 USA
57 </para>
58
59 <para>
60 For more details see the file COPYING in the source
61 distribution of Linux.
62 </para>
63 </legalnotice>
64 </bookinfo>
65
66 <toc></toc>
67
68 <chapter id="Intro">
69 <title>Kernel Crypto API Interface Specification</title>
70
71 <sect1><title>Introduction</title>
72
73 <para>
74 The kernel crypto API offers a rich set of cryptographic ciphers as
75 well as other data transformation mechanisms and methods to invoke
76 these. This document contains a description of the API and provides
77 example code.
78 </para>
79
80 <para>
81 To understand and properly use the kernel crypto API a brief
82 explanation of its structure is given. Based on the architecture,
83 the API can be separated into different components. Following the
84 architecture specification, hints to developers of ciphers are
85 provided. Pointers to the API function call documentation are
86 given at the end.
87 </para>
88
89 <para>
90 The kernel crypto API refers to all algorithms as "transformations".
91 Therefore, a cipher handle variable usually has the name "tfm".
92 Besides cryptographic operations, the kernel crypto API also knows
93 compression transformations and handles them the same way as ciphers.
94 </para>
95
96 <para>
97 The kernel crypto API serves the following entity types:
98
99 <itemizedlist>
100 <listitem>
101 <para>consumers requesting cryptographic services</para>
102 </listitem>
103 <listitem>
104 <para>data transformation implementations (typically ciphers)
105 that can be called by consumers using the kernel crypto
106 API</para>
107 </listitem>
108 </itemizedlist>
109 </para>
110
111 <para>
112 This specification is intended for consumers of the kernel crypto
113 API as well as for developers implementing ciphers. This API
114 specification, however, does not discuss all API calls available
115 to data transformation implementations (i.e. implementations of
116 ciphers and other transformations (such as CRC or even compression
117 algorithms) that can register with the kernel crypto API).
118 </para>
119
120 <para>
121 Note: The terms "transformation" and cipher algorithm are used
122 interchangeably.
123 </para>
124 </sect1>
125
126 <sect1><title>Terminology</title>
127 <para>
128 The transformation implementation is an actual code or interface
129 to hardware which implements a certain transformation with precisely
130 defined behavior.
131 </para>
132
133 <para>
134 The transformation object (TFM) is an instance of a transformation
135 implementation. There can be multiple transformation objects
136 associated with a single transformation implementation. Each of
137 those transformation objects is held by a crypto API consumer or
138 another transformation. Transformation object is allocated when a
139 crypto API consumer requests a transformation implementation.
140 The consumer is then provided with a structure, which contains
141 a transformation object (TFM).
142 </para>
143
144 <para>
145 The structure that contains transformation objects may also be
146 referred to as a "cipher handle". Such a cipher handle is always
147 subject to the following phases that are reflected in the API calls
148 applicable to such a cipher handle:
149 </para>
150
151 <orderedlist>
152 <listitem>
153 <para>Initialization of a cipher handle.</para>
154 </listitem>
155 <listitem>
156 <para>Execution of all intended cipher operations applicable
157 for the handle where the cipher handle must be furnished to
158 every API call.</para>
159 </listitem>
160 <listitem>
161 <para>Destruction of a cipher handle.</para>
162 </listitem>
163 </orderedlist>
164
165 <para>
166 When using the initialization API calls, a cipher handle is
167 created and returned to the consumer. Therefore, please refer
168 to all initialization API calls that refer to the data
169 structure type a consumer is expected to receive and subsequently
170 to use. The initialization API calls have all the same naming
171 conventions of crypto_alloc_*.
172 </para>
173
174 <para>
175 The transformation context is private data associated with
176 the transformation object.
177 </para>
178 </sect1>
179 </chapter>
180
181 <chapter id="Architecture"><title>Kernel Crypto API Architecture</title>
182 <sect1><title>Cipher algorithm types</title>
183 <para>
184 The kernel crypto API provides different API calls for the
185 following cipher types:
186
187 <itemizedlist>
188 <listitem><para>Symmetric ciphers</para></listitem>
189 <listitem><para>AEAD ciphers</para></listitem>
190 <listitem><para>Message digest, including keyed message digest</para></listitem>
191 <listitem><para>Random number generation</para></listitem>
192 <listitem><para>User space interface</para></listitem>