linux/Documentation/crypto/api-intro.txt
<<
ion>3.1/spa > 3.1/form> 3.1a ion>3. href="../linux+v3.7.5/Documenta" /crypto/api-intro.txt">ion>3.1img src="../.sta" c/gfx/right.png" alt=">>">io1/spa > io1spa class="lxr_search">ion>ion>3.1input typ> hidden" nam> navtarget" pion> ">ion>3.1input typ> text" nam> search" id search">ion>3.1butt submit">Search 3.1/form> 1/spa > io1spa class="lxr_prefs"> 3.1a href="+prefs?return=Documenta" /crypto/api-intro.txt"ion>3. onclick="return ajax_prefs();">ion>3.Prefs 3.1/a>io1/spa > n>3. .1/div> n>3. .1form ac" ="ajax+*" method="post" onsubmit="return false;">io1input typ> hidden" nam> ajax_lookup" id ajax_lookup" pion> ">in>3. .1/form> in>3. .1div class="headingbott
n>3.
n>3. 3. .1div id search_results" class="search_results" 3> n>3. .1/div> 1div id content"> 1div id file_contents">

 L1">. .11/a>i
 L2">. .21/a>                    Scatterlist Cryptographic APIi
 L3">. .31/a>                   i
 L4">. .41/a>INTRODUCTIONi
 L5">. .51/a>i
 L6">. .61/a>The Scatterlist Crypto API takes page vectors (scatterlists) asi
 L7">. .71/a>arguments, and works directly on pages.  In some cases (e.g. ECBi
 L8">. .81/a>mode ciphers), this will allow for pages to be encrypted in-placei
 L9">. .91/a>with no copying.i
 L10">. optia>i
 L11">. 111/a>One of the initial goals of this design was to readily support IPsec,i
 L12">. 121/a>so that processing can be applied to paged skb's without the needi
 L13">. 131/a>for lineariza"
	 .i
 L14">. 14tia>i
 L15">. 151/a>i
 L16">. 161/a>DETAILSi
 L17">. 171/a>i
 L18">. 181/a>At the lowest level are algorithms, which register dynamically with thei
 L19">. 191/a>API.i
 L20">. 2ptia>i
 L21">. 211/a>'Transforms' are user-instantiated objects, which maintain sta"e, handle alli
 L22">. 221/a>of the implementa"
	  logic (e.g. manipula"
ng page vectors) and provide an i
 L23">. 231/a>abstrac"
	  to the underlying algorithms.  However, at the user i
 L24">. 24tia>level they are very simple.i
 L25">. 251/a>i
 L26">. 261/a>Conceptually, the API layering looks like this:i
 L27">. 271/a>i
 L28">. 281/a>  [transform api]  (user interface)i
 L29">. 291/a>  [transform ops]  (per-typ> logic gon> e.g. cipher.c, compress.c)i
 L30">. 301/a>  [algorithm api]  (for registering algorithms)i
 L31">. 311/a>  i
 L32">. 321/a>The idea is to make the user interface and algorithm registra"
	  APIi
 L33">. 331/a>very simple, while hiding the cor> logic from both.  Many good ideasi
 L34">. 34tia>from existing APIs such as Cryptoapi and Nettle have been adapted for this.i
 L35">. 351/a>i
 L36">. 361/a>The API currently supports five main typ>s of transforms: AEAD (Authenticatedi
 L37">. 371/a>Encrypt
	  with Associated Data), Block Ciphers, Ciphers, Compressors andi
 L38">. 381/a>Hashes.i
 L39">. 391/a>i
 L40">. 401/a>Please note that Block Ciphers is somewhat of a misnomer.  It is in facti
 L41">. 411/a>meant to support all ciphers including stream ciphers.  The differencei
 L42">. 421/a>between Block Ciphers and Ciphers is that the latter opera">s on exactlyi
 L43">. 431/a>one block while the former can opera"> on an arbitrary amount of data,i
 L44">. 44tia>subject to block size requirements (i.e., non-stream ciphers can onlyi
 L45">. 451/a>process multiples of blocks).i
 L46">. 461/a>i
 L47">. 471/a>Support for hardware crypto devices via an asynchronous interface isi
 L48">. 481/a>under development.i
 L49">. 491/a>i
 L50">. 501/a>Here's an example of how to use the API:i
 L51">. 511/a>i
 L52">. 521/a>        #include <linux/crypto.h>i
 L53">. 531/a>        #include <linux/err.h>i
 L54">. 541/a>        #include <linux/scatterlist.h>i
 L55">. 551/a>        i
 L56">. 561/a>        struct scatterlist sg[2];i
 L57">. 571/a>        char result[128];i
 L58">. 581/a>        struct crypto_hash *tfm;i
 L59">. 591/a>        struct hash_desc desc;i
 L60">. 601/a>        i
 L61">. 611/a>        tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC);i
 L62">. 621/a>        if (IS_ERR(tfm))i
 L63">. 631/a>                fail();i
 L64">. 641/a>                i
 L65">. 651/a>        /* ... set up the scatterlists ... */i
 L66">. 661/a>i
 L67">. 671/a>        desc.tfm = tfm;i
 L68">. 681/a>        desc.flags = 0;i
 L69">. 691/a>        i
 L70">. 701/a>        if (crypto_hash_digest(&desc, sg, 2, result))i
 L71">. 711/a>                fail();i
 L72">. 721/a>        i
 L73">. 731/a>        crypto_free_hash(tfm);i
 L74">. 74tia>i
 L75">. 751/a>    i
 L76">. 761/a>Many real examples are available in the regress
	  test module (tcrypt.c).i
 L77">. 771/a>i
 L78">. 781/a>i
 L79">. 791/a>DEVELOPER NOTESi
 L80">. 8ptia>i
 L81">. 811/a>Transforms may only be allocated in user context, and cryptographici
 L82">. 821/a>methods may only be called from softirq and user contexts.  Fori
 L83">. 831/a>transforms with a setkey method it too should only be called fromi
 L84">. 84tia>user context.i
 L85">. 851/a>i
 L86">. 861/a>When using the API for ciphers, performance will be 25"
mal if eachi
 L87">. 871/a>scatterlist contains data which is a multiple of the cipher's blocki
 L88">. 881/a>size (typically 8 bytes).  This prevents having to do any copyingi
 L89">. 891/a>across non-aligned page fragment boundaries.i
 L90">. 9ptia>i
 L91">. 911/a>i
 L92">. 921/a>ADDING NEW ALGORITHMSi
 L93">. 931/a>i
 L94">. 941/a>When submitting a new algorithm for inclus
	 , a mandatory requirementi
 L95">. 951/a>is that at least a few test vectors from known sources (preferablyi
 L96">. 961/a>standards) be included.i
 L97">. 971/a>i
 L98">. 981/a>Converting existing well known code is preferred, as it is mor> likelyi
 L99">. 991/a>to have been reviewed and widely tested.  If submitting code from LGPLi
 L100">.1001/a>sources, please consider changing the license to GPL (see sec"
	  3 ofi
 L101">.1011/a>the LGPL).i
 L102">.1021/a>i
 L103">.1031/a>Algorithms submitted must also be generally patent-free (e.g. IDEAi
 L104">.1041/a>will not be included in the mainline until around 2011), and be basedi
 L105">.1051/a>on a recognized standard and/or have been subjected to appropriatei
 L106">.1061/a>peer review.i
 L107">.1071/a>i
 L108">.1081/a>Also check for any RFCs which may rela"> to the use of specific algorithms,i
 L109">.1091/a>as well as general applica"
	  notes such as RFC2451 ("The ESP CBC-Modei
 L110">.1optia>Cipher Algorithms").i
 L111">.1111/a>i
 L112">.1121/a>It's a good idea to avoid using lots of macros and use inlined func"
	 si
 L113">.1131/a>instead, as gcc does a good job with inlining, while excessive use ofi
 L114">.114tia>macros can cause compila"
	  problems on some pla"forms.i
 L115">.1151/a>i
 L116">.1161/a>Also check the TODO list at the web site listed below to see what peoplei
 L117">.1171/a>might already be working 	 .i
 L118">.1181/a>i
 L119">.1191/a>i
 L120">.12ptia>BUGSi
 L121">.1211/a>i
 L122">.1221/a>Send bug reports to:i
 L123">.1231/a>linux-crypto@vger.kernel.orgi
 L124">.124tia>Cc: Herbert Xu <herbert@gondor.apana.org.au>,i
 L125">.1251/a>    David S. Miller <davem@redhat.com>i
 L126">.1261/a>i
 L127">.1271/a>i
 L128">.1281/a>FURTHER INFORMATIONi
 L129">.1291/a>i
 L130">.1301/a>For further patches and various upda">s, including the current TODOi
 L131">.1311/a>list, see:i
 L132">.1321/a>http://gondor.apana.org.au/~herbert/crypto/1/a>i
 L133">.1331/a>i
 L134">.134tia>i
 L135">.1351/a>AUTHORSi
 L136">.1361/a>i
 L137">.1371/a>Jam>s Morrisi
 L138">.1381/a>David S. Milleri
 L139">.1391/a>Herbert Xui
 L140">.14ptia>i
 L141">.1411/a>i
 L142">.1421/a>CREDITSi
 L143">.1431/a>i
 L144">.144tia>The follow
ng people provided inpionable feedback during the developmenti
 L145">.1451/a>of the API:i
 L146">.1461/a>i
 L147">.1471/a>  Alexey Kuznetzovi
 L148">.1481/a>  Rusty Russelli
 L149">.1491/a>  Herbert Valerio Riedeli
 L150">.1501/a>  Jeff Garziki
 L151">.1511/a>  Michael Richardsoni
 L152">.1521/a>  Andrew Mortoni
 L153">.1531/a>  Ingo Oeseri
 L154">.1541/a>  Christoph Hellwigi
 L155">.1551/a>i
 L156">.1561/a>Port
	 s of this API were derived from the follow
ng projects:i
 L157">.1571/a>  i
 L158">.1581/a>  Kerneli Cryptoapi (http://www.kerneli.org/1/a>)i
 L159">.1591/a>    Alexander Kjeldaasi
 L160">.1601/a>    Herbert Valerio Riedeli
 L161">.1611/a>    Kyle McMartini
 L162">.1621/a>    Jean-Luc Cookei
 L163">.1631/a>    David Brysoni
 L164">.1641/a>    Clemens Fruhwirthi
 L165">.1651/a>    Tobias R
ngstromi
 L166">.1661/a>    Harald Weltei
 L167">.1671/a>i
 L168">.1681/a>and;i
 L169">.1691/a>  i
 L170">.1701/a>  Nettle (http://www.lysator.liu.se/~nisse/nettle/1/a>)i
 L171">.1711/a>    Niels Mölleri
 L172">.1721/a>i
 L173">.1731/a>Original developers of the crypto algorithms:i
 L174">.174tia>i
 L175">.1751/a>  Dana L. How (DES)i
 L176">.1761/a>  Andrew Tridgell and Steve French (MD4)i
 L177">.1771/a>  Colin Plumb (MD5)i
 L178">.1781/a>  Steve Reid (SHA1)i
 L179">.1791/a>  Jean-Luc Cooke (SHA256, SHA384, SHA512)i
 L180">.1801/a>  Kazunori Miyazawa / USAGI (HMAC)i
 L181">.1811/a>  Matthew Skala (Twofish)i
 L182">.1821/a>  Dag Arne Osvik (Serpent)i
 L183">.1831/a>  Brian Gladman (AES)i
 L184">.1841/a>  Kartikey Mahendra Bhatt (CAST6)i
 L185">.1851/a>  Jon Oberheide (ARC4)i
 L186">.1861/a>  Jouni Malinen (Michael MIC)i
 L187">.1871/a>  NTT(Nippon Telegraph and Telephone Corpora"
	 ) (Cam>llia)i
 L188">.1881/a>i
 L189">.1891/a>SHA1 algorithm contributors:i
 L190">.1901/a>  Jean-Francois Divei
 L191">.1911/a>  i
 L192">.1921/a>DES algorithm contributors:i
 L193">.1931/a>  Raimar Falkei
 L194">.1941/a>  Gisle Sælensmindei
 L195">.1951/a>  Niels Mölleri
 L196">.1961/a>i
 L197">.1971/a>Blowfish algorithm contributors:i
 L198">.1981/a>  Herbert Valerio Riedeli
 L199">.1991/a>  Kyle McMartini
 L200">.20ptia>i
 L201">.2011/a>Twofish algorithm contributors:i
 L202">.2021/a>  Werner Kochi
 L203">.2031/a>  Marc Mutzi
 L204">.204tia>i
 L205">.2051/a>SHA256/384/512 algorithm contributors:i
 L206">.2061/a>  Andrew McDonaldi
 L207">.2071/a>  Kyle McMartini
 L208">.2081/a>  Herbert Valerio Riedeli
 L209">.2091/a>  i
 L210">.2optia>AES algorithm contributors:i
 L211">.2111/a>  Alexander Kjeldaasi
 L212">.2121/a>  Herbert Valerio Riedeli
 L213">.2131/a>  Kyle McMartini
 L214">.2141/a>  Adam J. Richteri
 L215">.2151/a>  Fruhwirth Clemens (i586)i
 L216">.2161/a>  Linus Torvalds (i586)i
 L217">.2171/a>i
 L218">.2181/a>CAST5 algorithm contributors:i
 L219">.2191/a>  Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).i
 L220">.22ptia>i
 L221">.2211/a>TEA/XTEA algorithm contributors:i
 L222">.2221/a>  Aaron Grothei
 L223">.2231/a>  Michael Ringei
 L224">.224tia>i
 L225">.2251/a>Khazad algorithm contributors:i
 L226">.2261/a>  Aaron Grothei
 L227">.2271/a>i
 L228">.2281/a>Whirlpool algorithm contributors:i
 L229">.2291/a>  Aaron Grothei
 L230">.2301/a>  Jean-Luc Cookei
 L231">.2311/a>i
 L232">.2321/a>Anubis algorithm contributors:i
 L233">.2331/a>  Aaron Grothei
 L234">.234tia>i
 L235">.2351/a>Tiger algorithm contributors:i
 L236">.2361/a>  Aaron Grothei
 L237">.2371/a>i
 L238">.2381/a>VIA PadLock contributors:i
 L239">.2391/a>  Michal Ludvigi
 L240">.24ptia>i
 L241">.2411/a>Cam>llia algorithm contributors:i
 L242">.2421/a>  NTT(Nippon Telegraph and Telephone Corpora"
	 ) (Cam>llia)i
 L243">.2431/a>i
 L244">.244tia>Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>i
 L245">.2451/a>i
 L246">.2461/a>Please send any credits upda">s or correc"
	 s to:i
 L247">.2471/a>Herbert Xu <herbert@gondor.apana.org.au>i
 L248">.2481/a>i
 L249">.2491/a>
1/div> 1div class="footer"> The original LXR software by the LXR community1/a>, this experimental vers by lxr@linux.no1/a>. 1/div> 1div class="subfooter"> lxr.linux.no kindly hosted by Redpill Linpro AS1/a>, provider of Linux consulting and opera" s services since 1995. 1/div> 1/body> 1/html>