path: root/Documentation/DocBook/crypto-API.tmpl

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="KernelCryptoAPI">
 <bookinfo>
  <title>Linux Kernel Crypto API</title>

  <authorgroup>
   <author>
    <firstname>Stephan</firstname>
    <surname>Mueller</surname>
    <affiliation>
     <address>
      <email>smueller@chronox.de</email>
     </address>
    </affiliation>
   </author>
   <author>
    <firstname>Marek</firstname>
    <surname>Vasut</surname>
    <affiliation>
     <address>
      <email>marek@denx.de</email>
     </address>
    </affiliation>
   </author>
  </authorgroup>

  <copyright>
   <year>2014</year>
   <holder>Stephan Mueller</holder>
  </copyright>


  <legalnotice>
   <para>
     This documentation is free software; you can redistribute
     it and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later
     version.
   </para>

   <para>
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     See the GNU General Public License for more details.
   </para>

   <para>
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
     MA 02111-1307 USA
   </para>

   <para>
     For more details see the file COPYING in the source
     distribution of Linux.
   </para>
  </legalnotice>
 </bookinfo>

 <toc></toc>

 <chapter id="Intro">
  <title>Kernel Crypto API Interface Specification</title>

   <sect1><title>Introduction</title>

    <para>
     The kernel crypto API offers a rich set of cryptographic ciphers as
     well as other data transformation mechanisms and methods to invoke
     these. This document contains a description of the API and provides
     example code.
    </para>

    <para>
     To understand and properly use the kernel crypto API a brief
     explanation of its structure is given. Based on the architecture,
     the API can be separated into different components. Following the
     architecture specification, hints to developers of ciphers are
     provided. Pointers to the API function call  documentation are
     given at the end.
    </para>

    <para>
     The kernel crypto API refers to all algorithms as "transformations".
     Therefore, a cipher handle variable usually has the name "tfm".
     Besides cryptographic operations, the kernel crypto API also knows
     compression transformations and handles them the same way as ciphers.
    </para>

    <para>
     The kernel crypto API serves the following entity types:

     <itemizedlist>
      <listitem>
       <para>consumers requesting cryptographic services</para>
      </listitem>
      <listitem>
      <para>data transformation implementations (typically ciphers)
       that can be called by consumers using the kernel crypto
       API</para>
      </listitem>
     </itemizedlist>
    </para>

    <para>
     This specification is intended for consumers of the kernel crypto
     API as well as for developers implementing ciphers. This API
     specification, however, does not discusses all API calls available
     to data transformation implementations (i.e. implementations of
     ciphers and other transformations (such as CRC or even compression
     algorithms) that can register with the kernel crypto API).
    </para>

    <para>
     Note: The terms "transformation" and cipher algorithm are used
     interchangably.
    </para>
   </sect1>

   <sect1><title>Terminology</title>
    <para>
     The transformation implementation is an actual code or interface
     to hardware which implements a certain transformation with precisely
     defined behavior.
    </para>

    <para>
     The transformation object (TFM) is an instance of a transformation
     implementation. There can be multiple transformation objects
     associated with a single transformation implementation. Each of
     those transformation objects is held by a crypto API consumer or
     another transformation. Transformation object is allocated when a
     crypto API consumer requests a transformation implementation.
     The consumer is then provided with a structure, which contains
     a transformation object (TFM).
    </para>

    <para>
     The structure that contains transformation objects may also be
     referred to as a "cipher handle". Such a cipher handle is always
     subject to the following phases that are reflected in the API calls
     applicable to such a cipher handle:
    </para>

    <orderedlist>
     <listitem>
      <para>Initialization of a cipher handle.</para>
     </listitem>
     <listitem>
      <para>Execution of all intended cipher operations applicable
      for the handle where the cipher handle must be furnished to
      every API call.</para>
     </listitem>
     <listitem>
      <para>Destruction of a cipher handle.</para>
     </listitem>
    </orderedlist>

    <para>
     When using the initialization API calls, a cipher handle is
     created and returned to the consumer. Therefore, please refer
     to all initialization API calls that refer to the data
     structure type a consumer is expected to receive and subsequently
     to use. The initialization API calls have all the same naming
     conventions of crypto_alloc_*.
    </para>

    <para>
     The transformation context is private data associated with
     the transformation object.
    </para>
   </sect1>
  </chapter>

  <chapter id="Architecture"><title>Kernel Crypto API Architecture</title>
   <sect1><title>Cipher algorithm types</title>
    <para>
     The kernel crypto API provides different API calls for the
     following cipher types:

     <itemizedlist>
      <listitem><para>Symmetric ciphers</para></listitem>
      <listitem><para>AEAD ciphers</para></listitem>
      <listitem><para>Message digest, including keyed message digest</para></listitem>
      <listitem><para>Random number generation</para></listitem>
      <listitem><para>User space interface</para></listitem>
     </itemizedlist>
    </para>
   </sect1>

   <sect1><title>Ciphers And Templates</title>
    <para>
     The kernel crypto API provides implementations of single block
     ciphers and message digests. In addition, the kernel crypto API
     provides numerous "templates" that can be used in conjunction
     with the single block ciphers and message digests. Templates
     include all types of block chaining mode, the HMAC mechanism, etc.
    </para>

    <para>
     Single block ciphers and message digests can either be directly
     used by a caller or invoked together with a template to form
     multi-block ciphers or keyed message digests.
    </para>

    <para>
     A single block cipher may even be called with multiple templates.
     However, templates cannot be used without a single cipher.
    </para>

    <para>
     See /proc/crypto and search for "name". For example:

     <itemizedlist>
      <listitem><para>aes</para></listitem>
      <listitem><para&g