€•°Ë      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ'/translations/zh_CN/crypto/architecture”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/zh_TW/crypto/architecture”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/it_IT/crypto/architecture”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/ja_JP/crypto/architecture”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/ko_KR/crypto/architecture”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/sp_SP/crypto/architecture”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒKernel Crypto API Architecture”h]”hŒKernel Crypto API Architecture”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒA/var/lib/git/docbuild/linux/Documentation/crypto/architecture.rst”h Kubh¢)”}”(hhh]”(h§)”}”(hŒCipher algorithm types”h]”hŒCipher algorithm types”…””}”(hhºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh·hžhhŸh¶h KubhŒ	paragraph”“”)”}”(hŒRThe kernel crypto API provides different API calls for the following
cipher types:”h]”hŒRThe kernel crypto API provides different API calls for the following
cipher types:”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒSymmetric ciphers
”h]”hÉ)”}”(hŒSymmetric ciphers”h]”hŒSymmetric ciphers”…””}”(hhãhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K
hhßubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhhÚhžhhŸh¶h NubhÞ)”}”(hŒAEAD ciphers
”h]”hÉ)”}”(hŒAEAD ciphers”h]”hŒAEAD ciphers”…””}”(hhûhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh÷ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhhÚhžhhŸh¶h NubhÞ)”}”(hŒ/Message digest, including keyed message digest
”h]”hÉ)”}”(hŒ.Message digest, including keyed message digest”h]”hŒ.Message digest, including keyed message digest”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhhÚhžhhŸh¶h NubhÞ)”}”(hŒRandom number generation
”h]”hÉ)”}”(hŒRandom number generation”h]”hŒRandom number generation”…””}”(hj+  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj'  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhhÚhžhhŸh¶h NubhÞ)”}”(hŒUser space interface
”h]”hÉ)”}”(hŒUser space interface”h]”hŒUser space interface”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj?  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhhÚhžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1hØhŸh¶h K
hh·hžhubeh}”(h]”Œcipher-algorithm-types”ah ]”h"]”Œcipher algorithm types”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒCiphers And Templates”h]”hŒCiphers And Templates”…””}”(hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjg  hžhhŸh¶h KubhÉ)”}”(hX<  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.”h]”hX@  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.”…””}”(hjx  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khjg  hžhubhÉ)”}”(hŒª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.”h]”hŒª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.”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khjg  hžhubhÉ)”}”(hŒ|A single block cipher may even be called with multiple templates.
However, templates cannot be used without a single cipher.”h]”hŒ|A single block cipher may even be called with multiple templates.
However, templates cannot be used without a single cipher.”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K!hjg  hžhubhÉ)”}”(hŒ4See /proc/crypto and search for "name". For example:”h]”hŒ8See /proc/crypto and search for â€œnameâ€. For example:”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K$hjg  hžhubhÙ)”}”(hhh]”(hÞ)”}”(hŒaes
”h]”hÉ)”}”(hŒaes”h]”hŒaes”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K&hj³  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒ	ecb(aes)
”h]”hÉ)”}”(hŒecb(aes)”h]”hŒecb(aes)”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K(hjË  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒ
cmac(aes)
”h]”hÉ)”}”(hŒ	cmac(aes)”h]”hŒ	cmac(aes)”…””}”(hjç  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K*hjã  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒ	ccm(aes)
”h]”hÉ)”}”(hŒccm(aes)”h]”hŒccm(aes)”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K,hjû  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒrfc4106(gcm(aes))
”h]”hÉ)”}”(hŒrfc4106(gcm(aes))”h]”hŒrfc4106(gcm(aes))”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K.hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒsha1
”h]”hÉ)”}”(hŒsha1”h]”hŒsha1”…””}”(hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K0hj+  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒhmac(sha1)
”h]”hÉ)”}”(hŒ
hmac(sha1)”h]”hŒ
hmac(sha1)”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K2hjC  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h NubhÞ)”}”(hŒauthenc(hmac(sha1),cbc(aes))
”h]”hÉ)”}”(hŒauthenc(hmac(sha1),cbc(aes))”h]”hŒauthenc(hmac(sha1),cbc(aes))”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K4hj[  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj°  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j]  j^  uh1hØhŸh¶h K&hjg  hžhubhÉ)”}”(hŒUIn these examples, "aes" and "sha1" are the ciphers and all others are
the templates.”h]”hŒ]In these examples, â€œaesâ€ and â€œsha1â€ are the ciphers and all others are
the templates.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K6hjg  hžhubeh}”(h]”Œciphers-and-templates”ah ]”h"]”Œciphers and templates”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ&Synchronous And Asynchronous Operation”h]”hŒ&Synchronous And Asynchronous Operation”…””}”(hj’  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K:ubhÉ)”}”(hŒKThe kernel crypto API provides synchronous and asynchronous API
operations.”h]”hŒKThe kernel crypto API provides synchronous and asynchronous API
operations.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K<hj  hžhubhÉ)”}”(hX…  When using the synchronous API operation, the caller invokes a cipher
operation which is performed synchronously by the kernel crypto API.
That means, the caller waits until the cipher operation completes.
Therefore, the kernel crypto API calls work like regular function calls.
For synchronous operation, the set of API calls is small and
conceptually similar to any other crypto library.”h]”hX…  When using the synchronous API operation, the caller invokes a cipher
operation which is performed synchronously by the kernel crypto API.
That means, the caller waits until the cipher operation completes.
Therefore, the kernel crypto API calls work like regular function calls.
For synchronous operation, the set of API calls is small and
conceptually similar to any other crypto library.”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K?hj  hžhubhÉ)”}”(hXz  Asynchronous operation is provided by the kernel crypto API which
implies that the invocation of a cipher operation will complete almost
instantly. That invocation triggers the cipher operation but it does not
signal its completion. Before invoking a cipher operation, the caller
must provide a callback function the kernel crypto API can invoke to
signal the completion of the cipher operation. Furthermore, the caller
must ensure it can handle such asynchronous events by applying
appropriate locking around its data. The kernel crypto API does not
perform any special serialization operation to protect the caller's data
integrity.”h]”hX|  Asynchronous operation is provided by the kernel crypto API which
implies that the invocation of a cipher operation will complete almost
instantly. That invocation triggers the cipher operation but it does not
signal its completion. Before invoking a cipher operation, the caller
must provide a callback function the kernel crypto API can invoke to
signal the completion of the cipher operation. Furthermore, the caller
must ensure it can handle such asynchronous events by applying
appropriate locking around its data. The kernel crypto API does not
perform any special serialization operation to protect the callerâ€™s data
integrity.”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KFhj  hžhubeh}”(h]”Œ&synchronous-and-asynchronous-operation”ah ]”h"]”Œ&synchronous and asynchronous operation”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K:ubh¢)”}”(hhh]”(h§)”}”(hŒ)Crypto API Cipher References And Priority”h]”hŒ)Crypto API Cipher References And Priority”…””}”(hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÒ  hžhhŸh¶h KRubhÉ)”}”(hŒ\A cipher is referenced by the caller with a string. That string has the
following semantics:”h]”hŒ\A cipher is referenced by the caller with a string. That string has the
following semantics:”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KThjÒ  hžhubhŒliteral_block”“”)”}”(hŒtemplate(single block cipher)”h]”hŒtemplate(single block cipher)”…””}”hjó  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jñ  hŸh¶h KYhjÒ  hžhubhÉ)”}”(hŒ¹where "template" and "single block cipher" is the aforementioned
template and single block cipher, respectively. If applicable,
additional templates may enclose other templates, such as”h]”hŒÁwhere â€œtemplateâ€ and â€œsingle block cipherâ€ is the aforementioned
template and single block cipher, respectively. If applicable,
additional templates may enclose other templates, such as”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K\hjÒ  hžhubjò  )”}”(hŒ*template1(template2(single block cipher)))”h]”hŒ*template1(template2(single block cipher)))”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jñ  hŸh¶h KbhjÒ  hžhubhÉ)”}”(hXª  The kernel crypto API may provide multiple implementations of a template
or a single block cipher. For example, AES on newer Intel hardware has
the following implementations: AES-NI, assembler implementation, or
straight C. Now, when using the string "aes" with the kernel crypto API,
which cipher implementation is used? The answer to that question is the
priority number assigned to each cipher implementation by the kernel
crypto API. When a caller uses the string to refer to a cipher during
initialization of a cipher handle, the kernel crypto API looks up all
implementations providing an implementation with that name and selects
the implementation with the highest priority.”h]”hX®  The kernel crypto API may provide multiple implementations of a template
or a single block cipher. For example, AES on newer Intel hardware has
the following implementations: AES-NI, assembler implementation, or
straight C. Now, when using the string â€œaesâ€ with the kernel crypto API,
which cipher implementation is used? The answer to that question is the
priority number assigned to each cipher implementation by the kernel
crypto API. When a caller uses the string to refer to a cipher during
initialization of a cipher handle, the kernel crypto API looks up all
implementations providing an implementation with that name and selects
the implementation with the highest priority.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KehjÒ  hžhubhÉ)”}”(hX‡  Now, a caller may have the need to refer to a specific cipher
implementation and thus does not want to rely on the priority-based
selection. To accommodate this scenario, the kernel crypto API allows
the cipher implementation to register a unique name in addition to
common names. When using that unique name, a caller is therefore always
sure to refer to the intended cipher implementation.”h]”hX‡  Now, a caller may have the need to refer to a specific cipher
implementation and thus does not want to rely on the priority-based
selection. To accommodate this scenario, the kernel crypto API allows
the cipher implementation to register a unique name in addition to
common names. When using that unique name, a caller is therefore always
sure to refer to the intended cipher implementation.”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KphjÒ  hžhubhÉ)”}”(hX:  The list of available ciphers is given in /proc/crypto. However, that
list does not specify all possible permutations of templates and
ciphers. Each block listed in /proc/crypto may contain the following
information -- if one of the components listed as follows are not
applicable to a cipher, it is not displayed:”h]”hX:  The list of available ciphers is given in /proc/crypto. However, that
list does not specify all possible permutations of templates and
ciphers. Each block listed in /proc/crypto may contain the following
information -- if one of the components listed as follows are not
applicable to a cipher, it is not displayed:”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KwhjÒ  hžhubhÙ)”}”(hhh]”(hÞ)”}”(hŒÎname: the generic name of the cipher that is subject to the
priority-based selection -- this name can be used by the cipher
allocation API calls (all names listed above are examples for such
generic names)
”h]”hÉ)”}”(hŒÍname: the generic name of the cipher that is subject to the
priority-based selection -- this name can be used by the cipher
allocation API calls (all names listed above are examples for such
generic names)”h]”hŒÍname: the generic name of the cipher that is subject to the
priority-based selection -- this name can be used by the cipher
allocation API calls (all names listed above are examples for such
generic names)”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K}hjL  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒbdriver: the unique name of the cipher -- this name can be used by the
cipher allocation API calls
”h]”hÉ)”}”(hŒadriver: the unique name of the cipher -- this name can be used by the
cipher allocation API calls”h]”hŒadriver: the unique name of the cipher -- this name can be used by the
cipher allocation API calls”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K‚hjd  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒjmodule: the kernel module providing the cipher implementation (or
"kernel" for statically linked ciphers)
”h]”hÉ)”}”(hŒimodule: the kernel module providing the cipher implementation (or
"kernel" for statically linked ciphers)”h]”hŒmmodule: the kernel module providing the cipher implementation (or
â€œkernelâ€ for statically linked ciphers)”…””}”(hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K…hj|  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒ:priority: the priority value of the cipher implementation
”h]”hÉ)”}”(hŒ9priority: the priority value of the cipher implementation”h]”hŒ9priority: the priority value of the cipher implementation”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kˆhj”  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒkrefcnt: the reference count of the respective cipher (i.e. the number
of current consumers of this cipher)
”h]”hÉ)”}”(hŒjrefcnt: the reference count of the respective cipher (i.e. the number
of current consumers of this cipher)”h]”hŒjrefcnt: the reference count of the respective cipher (i.e. the number
of current consumers of this cipher)”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KŠhj¬  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒDselftest: specification whether the self test for the cipher passed
”h]”hÉ)”}”(hŒCselftest: specification whether the self test for the cipher passed”h]”hŒCselftest: specification whether the self test for the cipher passed”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KhjÄ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hX¯  type:

-  skcipher for symmetric key ciphers

-  cipher for single block ciphers that may be used with an
   additional template

-  shash for synchronous message digest

-  ahash for asynchronous message digest

-  aead for AEAD cipher type

-  compression for compression type transformations

-  rng for random number generator

-  kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
   an ECDH or DH implementation
”h]”(hÉ)”}”(hŒtype:”h]”hŒtype:”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KhjÜ  ubhÙ)”}”(hhh]”(hÞ)”}”(hŒ#skcipher for symmetric key ciphers
”h]”hÉ)”}”(hŒ"skcipher for symmetric key ciphers”h]”hŒ"skcipher for symmetric key ciphers”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K‘hjñ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒMcipher for single block ciphers that may be used with an
additional template
”h]”hÉ)”}”(hŒLcipher for single block ciphers that may be used with an
additional template”h]”hŒLcipher for single block ciphers that may be used with an
additional template”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K“hj	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒ%shash for synchronous message digest
”h]”hÉ)”}”(hŒ$shash for synchronous message digest”h]”hŒ$shash for synchronous message digest”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K–hj!  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒ&ahash for asynchronous message digest
”h]”hÉ)”}”(hŒ%ahash for asynchronous message digest”h]”hŒ%ahash for asynchronous message digest”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K˜hj9  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒaead for AEAD cipher type
”h]”hÉ)”}”(hŒaead for AEAD cipher type”h]”hŒaead for AEAD cipher type”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KšhjQ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒ1compression for compression type transformations
”h]”hÉ)”}”(hŒ0compression for compression type transformations”h]”hŒ0compression for compression type transformations”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kœhji  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒ rng for random number generator
”h]”hÉ)”}”(hŒrng for random number generator”h]”hŒrng for random number generator”…””}”(hj…  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kžhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubhÞ)”}”(hŒ]kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
an ECDH or DH implementation
”h]”hÉ)”}”(hŒ\kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
an ECDH or DH implementation”h]”hŒ\kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
an ECDH or DH implementation”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K hj™  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjî  ubeh}”(h]”h ]”h"]”h$]”h&]”j]  j^  uh1hØhŸh¶h K‘hjÜ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸNh NubhÞ)”}”(hŒ(blocksize: blocksize of cipher in bytes
”h]”hÉ)”}”(hŒ'blocksize: blocksize of cipher in bytes”h]”hŒ'blocksize: blocksize of cipher in bytes”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K£hj½  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒkeysize: key size in bytes
”h]”hÉ)”}”(hŒkeysize: key size in bytes”h]”hŒkeysize: key size in bytes”…””}”(hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¥hjÕ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒivsize: IV size in bytes
”h]”hÉ)”}”(hŒivsize: IV size in bytes”h]”hŒivsize: IV size in bytes”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K§hjí  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒAseedsize: required size of seed data for random number generator
”h]”hÉ)”}”(hŒ@seedsize: required size of seed data for random number generator”h]”hŒ@seedsize: required size of seed data for random number generator”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K©hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒ.digestsize: output size of the message digest
”h]”hÉ)”}”(hŒ-digestsize: output size of the message digest”h]”hŒ-digestsize: output size of the message digest”…””}”(hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K«hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h NubhÞ)”}”(hŒgeniv: IV generator (obsolete)
”h]”hÉ)”}”(hŒgeniv: IV generator (obsolete)”h]”hŒgeniv: IV generator (obsolete)”…””}”(hj9  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K­hj5  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjI  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j]  j^  uh1hØhŸh¶h K}hjÒ  hžhubeh}”(h]”Œ)crypto-api-cipher-references-and-priority”ah ]”h"]”Œ)crypto api cipher references and priority”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KRubh¢)”}”(hhh]”(h§)”}”(hŒ	Key Sizes”h]”hŒ	Key Sizes”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj[  hžhhŸh¶h K°ubhÉ)”}”(hXh  When allocating a cipher handle, the caller only specifies the cipher
type. Symmetric ciphers, however, typically support multiple key sizes
(e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined
with the length of the provided key. Thus, the kernel crypto API does
not provide a separate way to select the particular symmetric cipher key
size.”h]”hXh  When allocating a cipher handle, the caller only specifies the cipher
type. Symmetric ciphers, however, typically support multiple key sizes
(e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined
with the length of the provided key. Thus, the kernel crypto API does
not provide a separate way to select the particular symmetric cipher key
size.”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K²hj[  hžhubeh}”(h]”Œ	key-sizes”ah ]”h"]”Œ	key sizes”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K°ubh¢)”}”(hhh]”(h§)”}”(hŒ Cipher Allocation Type And Masks”h]”hŒ Cipher Allocation Type And Masks”…””}”(hj…  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj‚  hžhhŸh¶h KºubhÉ)”}”(hŒÈThe different cipher handle allocation functions allow the specification
of a type and mask flag. Both parameters have the following meaning (and
are therefore not covered in the subsequent sections).”h]”hŒÈThe different cipher handle allocation functions allow the specification
of a type and mask flag. Both parameters have the following meaning (and
are therefore not covered in the subsequent sections).”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¼hj‚  hžhubhÉ)”}”(hŒíThe type flag specifies the type of the cipher algorithm. The caller
usually provides a 0 when the caller wants the default handling.
Otherwise, the caller may provide the following selections which match
the aforementioned cipher types:”h]”hŒíThe type flag specifies the type of the cipher algorithm. The caller
usually provides a 0 when the caller wants the default handling.
Otherwise, the caller may provide the following selections which match
the aforementioned cipher types:”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÀhj‚  hžhubhÙ)”}”(hhh]”(hÞ)”}”(hŒ+CRYPTO_ALG_TYPE_CIPHER Single block cipher
”h]”hÉ)”}”(hŒ*CRYPTO_ALG_TYPE_CIPHER Single block cipher”h]”hŒ*CRYPTO_ALG_TYPE_CIPHER Single block cipher”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÅhj²  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒICRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data
(MAC)
”h]”hÉ)”}”(hŒHCRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data
(MAC)”h]”hŒHCRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data
(MAC)”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÇhjÊ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ`CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as
an ECDH or DH implementation
”h]”hÉ)”}”(hŒ_CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as
an ECDH or DH implementation”h]”hŒ_CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as
an ECDH or DH implementation”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÊhjâ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ(CRYPTO_ALG_TYPE_HASH Raw message digest
”h]”hÉ)”}”(hŒ'CRYPTO_ALG_TYPE_HASH Raw message digest”h]”hŒ'CRYPTO_ALG_TYPE_HASH Raw message digest”…””}”(hjþ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÍhjú  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ3CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash
”h]”hÉ)”}”(hŒ2CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash”h]”hŒ2CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÏhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ4CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash
”h]”hÉ)”}”(hŒ3CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash”h]”hŒ3CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÑhj*  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ-CRYPTO_ALG_TYPE_RNG Random Number Generation
”h]”hÉ)”}”(hŒ,CRYPTO_ALG_TYPE_RNG Random Number Generation”h]”hŒ,CRYPTO_ALG_TYPE_RNG Random Number Generation”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÓhjB  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ+CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher
”h]”hÉ)”}”(hŒ*CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher”h]”hŒ*CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÕhjZ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hŒ)CRYPTO_ALG_TYPE_SIG Asymmetric signature
”h]”hÉ)”}”(hŒ(CRYPTO_ALG_TYPE_SIG Asymmetric signature”h]”hŒ(CRYPTO_ALG_TYPE_SIG Asymmetric signature”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K×hjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h NubhÞ)”}”(hX$  CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
decompression instead of performing the operation on one segment
only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.
”h]”hÉ)”}”(hX#  CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
decompression instead of performing the operation on one segment
only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.”h]”hX#  CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
decompression instead of performing the operation on one segment
only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.”…””}”(hjŽ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÙhjŠ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhj¯  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j]  j^  uh1hØhŸh¶h KÅhj‚  hžhubhÉ)”}”(hŒÇThe mask flag restricts the type of cipher. The only allowed flag is
CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.”h]”hŒÇThe mask flag restricts the type of cipher. The only allowed flag is
CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kßhj‚  hžhubhÉ)”}”(hXa  When the caller provides a mask and type specification, the caller
limits the search the kernel crypto API can perform for a suitable
cipher implementation for the given cipher name. That means, even when a
caller uses a cipher name that exists during its initialization call,
the kernel crypto API may not select it due to the used type and mask
field.”h]”hXa  When the caller provides a mask and type specification, the caller
limits the search the kernel crypto API can perform for a suitable
cipher implementation for the given cipher name. That means, even when a
caller uses a cipher name that exists during its initialization call,
the kernel crypto API may not select it due to the used type and mask
field.”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kãhj‚  hžhubeh}”(h]”Œ cipher-allocation-type-and-masks”ah ]”h"]”Œ cipher allocation type and masks”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kºubh¢)”}”(hhh]”(h§)”}”(hŒ'Internal Structure of Kernel Crypto API”h]”hŒ'Internal Structure of Kernel Crypto API”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÌ  hžhhŸh¶h KëubhÉ)”}”(hŒêThe kernel crypto API has an internal structure where a cipher
implementation may use many layers and indirections. This section shall
help to clarify how the kernel crypto API uses various components to
implement the complete cipher.”h]”hŒêThe kernel crypto API has an internal structure where a cipher
implementation may use many layers and indirections. This section shall
help to clarify how the kernel crypto API uses various components to
implement the complete cipher.”…””}”(hjÝ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KíhjÌ  hžhubhÉ)”}”(hŒÉThe following subsections explain the internal structure based on
existing cipher implementations. The first section addresses the most
complex scenario where all other scenarios form a logical subset.”h]”hŒÉThe following subsections explain the internal structure based on
existing cipher implementations. The first section addresses the most
complex scenario where all other scenarios form a logical subset.”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KòhjÌ  hžhubh¢)”}”(hhh]”(h§)”}”(hŒGeneric AEAD Cipher Structure”h]”hŒGeneric AEAD Cipher Structure”…””}”(hjü  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjù  hžhhŸh¶h K÷ubhÉ)”}”(hŒªThe following ASCII art decomposes the kernel crypto API layers when
using the AEAD cipher with the automated IV generation. The shown
example is used by the IPSEC layer.”h]”hŒªThe following ASCII art decomposes the kernel crypto API layers when
using the AEAD cipher with the automated IV generation. The shown
example is used by the IPSEC layer.”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kùhjù  hžhubhÉ)”}”(hŒ»For other use cases of AEAD ciphers, the ASCII art applies as well, but
the caller may not use the AEAD cipher with a separate IV generator. In
this case, the caller must generate the IV.”h]”hŒ»For other use cases of AEAD ciphers, the ASCII art applies as well, but
the caller may not use the AEAD cipher with a separate IV generator. In
this case, the caller must generate the IV.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kýhjù  hžhubhÉ)”}”(hX   The depicted example decomposes the AEAD cipher of GCM(AES) based on the
generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c,
seqiv.c). The generic implementation serves as an example showing the
complete logic of the kernel crypto API.”h]”hX   The depicted example decomposes the AEAD cipher of GCM(AES) based on the
generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c,
seqiv.c). The generic implementation serves as an example showing the
complete logic of the kernel crypto API.”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjù  hžhubhÉ)”}”(hX<  It is possible that some streamlined cipher implementations (like
AES-NI) provide implementations merging aspects which in the view of the
kernel crypto API cannot be decomposed into layers any more. In case of
the AES-NI implementation, the CTR mode, the GHASH implementation and
the AES cipher are all merged into one cipher implementation registered
with the kernel crypto API. In this case, the concept described by the
following ASCII art applies too. However, the decomposition of GCM into
the individual sub-components by the kernel crypto API is not done any
more.”h]”hX<  It is possible that some streamlined cipher implementations (like
AES-NI) provide implementations merging aspects which in the view of the
kernel crypto API cannot be decomposed into layers any more. In case of
the AES-NI implementation, the CTR mode, the GHASH implementation and
the AES cipher are all merged into one cipher implementation registered
with the kernel crypto API. In this case, the concept described by the
following ASCII art applies too. However, the decomposition of GCM into
the individual sub-components by the kernel crypto API is not done any
more.”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjù  hžhubhÉ)”}”(hX  Each block in the following ASCII art is an independent cipher instance
obtained from the kernel crypto API. Each block is accessed by the
caller or by other blocks using the API functions defined by the kernel
crypto API for the cipher implementation type.”h]”hX  Each block in the following ASCII art is an independent cipher instance
obtained from the kernel crypto API. Each block is accessed by the
caller or by other blocks using the API functions defined by the kernel
crypto API for the cipher implementation type.”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjù  hžhubhÉ)”}”(hŒbThe blocks below indicate the cipher type as well as the specific logic
implemented in the cipher.”h]”hŒbThe blocks below indicate the cipher type as well as the specific logic
implemented in the cipher.”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjù  hžhubhÉ)”}”(hŒÓThe ASCII art picture also indicates the call structure, i.e. who calls
which component. The arrows point to the invoked block where the caller
uses the API applicable to the cipher type specified for the block.”h]”hŒÓThe ASCII art picture also indicates the call structure, i.e. who calls
which component. The arrows point to the invoked block where the caller
uses the API applicable to the cipher type specified for the block.”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjù  hžhubjò  )”}”(hX;  kernel crypto API                                |   IPSEC Layer
                                                 |
+-----------+                                    |
|           |            (1)
|   aead    | <-----------------------------------  esp_output
|  (seqiv)  | ---+
+-----------+    |
                 | (2)
+-----------+    |
|           | <--+                (2)
|   aead    | <-----------------------------------  esp_input
|   (gcm)   | ------------+
+-----------+             |
      | (3)               | (5)
      v                   v
+-----------+       +-----------+
|           |       |           |
|  skcipher |       |   ahash   |
|   (ctr)   | ---+  |  (ghash)  |
+-----------+    |  +-----------+
                 |
+-----------+    | (4)
|           | <--+
|   cipher  |
|   (aes)   |
+-----------+”h]”hX;  kernel crypto API                                |   IPSEC Layer
                                                 |
+-----------+                                    |
|           |            (1)
|   aead    | <-----------------------------------  esp_output
|  (seqiv)  | ---+
+-----------+    |
                 | (2)
+-----------+    |
|           | <--+                (2)
|   aead    | <-----------------------------------  esp_input
|   (gcm)   | ------------+
+-----------+             |
      | (3)               | (5)
      v                   v
+-----------+       +-----------+
|           |       |           |
|  skcipher |       |   ahash   |
|   (ctr)   | ---+  |  (ghash)  |
+-----------+    |  +-----------+
                 |
+-----------+    | (4)
|           | <--+
|   cipher  |
|   (aes)   |
+-----------+”…””}”hjl  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jñ  hŸh¶h Mhjù  hžhubhÉ)”}”(hX+  The following call sequence is applicable when the IPSEC layer triggers
an encryption operation with the esp_output function. During
configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes)))
as the cipher for ESP. The following call sequence is now depicted in
the ASCII art above:”h]”hX+  The following call sequence is applicable when the IPSEC layer triggers
an encryption operation with the esp_output function. During
configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes)))
as the cipher for ESP. The following call sequence is now depicted in
the ASCII art above:”…””}”(hjz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M<hjù  hžhubhŒenumerated_list”“”)”}”(hhh]”(hÞ)”}”(hŒ‘esp_output() invokes crypto_aead_encrypt() to trigger an
encryption operation of the AEAD cipher with IV generator.

The SEQIV generates the IV.
”h]”(hÉ)”}”(hŒsesp_output() invokes crypto_aead_encrypt() to trigger an
encryption operation of the AEAD cipher with IV generator.”h]”hŒsesp_output() invokes crypto_aead_encrypt() to trigger an
encryption operation of the AEAD cipher with IV generator.”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MBhj  ubhÉ)”}”(hŒThe SEQIV generates the IV.”h]”hŒThe SEQIV generates the IV.”…””}”(hjŸ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MEhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjŠ  hžhhŸh¶h NubhÞ)”}”(hX2  Now, SEQIV uses the AEAD API function calls to invoke the associated
AEAD cipher. In our case, during the instantiation of SEQIV, the
cipher handle for GCM is provided to SEQIV. This means that SEQIV
invokes AEAD cipher operations with the GCM cipher handle.

During instantiation of the GCM handle, the CTR(AES) and GHASH
ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
are retained for later use.

The GCM implementation is responsible to invoke the CTR mode AES and
the GHASH cipher in the right manner to implement the GCM
specification.
”h]”(hÉ)”}”(hX  Now, SEQIV uses the AEAD API function calls to invoke the associated
AEAD cipher. In our case, during the instantiation of SEQIV, the
cipher handle for GCM is provided to SEQIV. This means that SEQIV
invokes AEAD cipher operations with the GCM cipher handle.”h]”hX  Now, SEQIV uses the AEAD API function calls to invoke the associated
AEAD cipher. In our case, during the instantiation of SEQIV, the
cipher handle for GCM is provided to SEQIV. This means that SEQIV
invokes AEAD cipher operations with the GCM cipher handle.”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MGhj³  ubhÉ)”}”(hŒžDuring instantiation of the GCM handle, the CTR(AES) and GHASH
ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
are retained for later use.”h]”hŒžDuring instantiation of the GCM handle, the CTR(AES) and GHASH
ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
are retained for later use.”…””}”(hjÅ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MLhj³  ubhÉ)”}”(hŒThe GCM implementation is responsible to invoke the CTR mode AES and
the GHASH cipher in the right manner to implement the GCM
specification.”h]”hŒThe GCM implementation is responsible to invoke the CTR mode AES and
the GHASH cipher in the right manner to implement the GCM
specification.”…””}”(hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MPhj³  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjŠ  hžhhŸh¶h NubhÞ)”}”(hXÁ  The GCM AEAD cipher type implementation now invokes the SKCIPHER API
with the instantiated CTR(AES) cipher handle.

During instantiation of the CTR(AES) cipher, the CIPHER type
implementation of AES is instantiated. The cipher handle for AES is
retained.

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.
”h]”(hÉ)”}”(hŒrThe GCM AEAD cipher type implementation now invokes the SKCIPHER API
with the instantiated CTR(AES) cipher handle.”h]”hŒrThe GCM AEAD cipher type implementation now invokes the SKCIPHER API
with the instantiated CTR(AES) cipher handle.”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MThjç  ubhÉ)”}”(hŒŠDuring instantiation of the CTR(AES) cipher, the CIPHER type
implementation of AES is instantiated. The cipher handle for AES is
retained.”h]”hŒŠDuring instantiation of the CTR(AES) cipher, the CIPHER type
implementation of AES is instantiated. The cipher handle for AES is
retained.”…””}”(hjù  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MWhjç  ubhÉ)”}”(hŒÀ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.”h]”hŒÀ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.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M[hjç  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjŠ  hžhhŸh¶h NubhÞ)”}”(hŒeThe SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
cipher handle to encrypt one block.
”h]”hÉ)”}”(hŒdThe SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
cipher handle to encrypt one block.”h]”hŒdThe SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
cipher handle to encrypt one block.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M_hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjŠ  hžhhŸh¶h NubhÞ)”}”(hŒ\The GCM AEAD implementation also invokes the GHASH cipher
implementation via the AHASH API.
”h]”hÉ)”}”(hŒ[The GCM AEAD implementation also invokes the GHASH cipher
implementation via the AHASH API.”h]”hŒ[The GCM AEAD implementation also invokes the GHASH cipher
implementation via the AHASH API.”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mbhj3  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjŠ  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jˆ  hjù  hžhhŸh¶h MBubhÉ)”}”(hŒœWhen the IPSEC layer triggers the esp_input() function, the same call
sequence is followed with the only difference that the operation starts
with step (2).”h]”hŒœWhen the IPSEC layer triggers the esp_input() function, the same call
sequence is followed with the only difference that the operation starts
with step (2).”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mehjù  hžhubeh}”(h]”Œgeneric-aead-cipher-structure”ah ]”h"]”Œgeneric aead cipher structure”ah$]”h&]”uh1h¡hjÌ  hžhhŸh¶h K÷ubh¢)”}”(hhh]”(h§)”}”(hŒGeneric Block Cipher Structure”h]”hŒGeneric Block Cipher Structure”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjl  hžhhŸh¶h MjubhÉ)”}”(hŒ[Generic block ciphers follow the same concept as depicted with the ASCII
art picture above.”h]”hŒ[Generic block ciphers follow the same concept as depicted with the ASCII
art picture above.”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mlhjl  hžhubhÉ)”}”(hŒË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 SKCIPHER block chaining mode is CBC.”h]”hŒË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 SKCIPHER block chaining mode is CBC.”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mohjl  hžhubeh}”(h]”Œgeneric-block-cipher-structure”ah ]”h"]”Œgeneric block cipher structure”ah$]”h&]”uh1h¡hjÌ  hžhhŸh¶h Mjubh¢)”}”(hhh]”(h§)”}”(hŒ&Generic Keyed Message Digest Structure”h]”hŒ&Generic Keyed Message Digest Structure”…””}”(hj¤  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj¡  hžhhŸh¶h MtubhÉ)”}”(hŒnKeyed message digest implementations again follow the same concept as
depicted in the ASCII art picture above.”h]”hŒnKeyed message digest implementations again follow the same concept as
depicted in the ASCII art picture above.”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mvhj¡  hžhubhÉ)”}”(hŒ‚For example, HMAC(SHA256) is implemented with hmac.c and
sha256_generic.c. The following ASCII art illustrates the
implementation:”h]”hŒ‚For example, HMAC(SHA256) is implemented with hmac.c and
sha256_generic.c. The following ASCII art illustrates the
implementation:”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Myhj¡  hžhubjò  )”}”(hX5  kernel crypto API            |       Caller
                             |
+-----------+         (1)    |
|           | <------------------  some_function
|   ahash   |
|   (hmac)  | ---+
+-----------+    |
                 | (2)
+-----------+    |
|           | <--+
|   shash   |
|  (sha256) |
+-----------+”h]”hX5  kernel crypto API            |       Caller
                             |
+-----------+         (1)    |
|           | <------------------  some_function
|   ahash   |
|   (hmac)  | ---+
+-----------+    |
                 | (2)
+-----------+    |
|           | <--+
|   shash   |
|  (sha256) |
+-----------+”…””}”hjÎ  sbah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1jñ  hŸh¶h M€hj¡  hžhubhÉ)”}”(hŒSThe following call sequence is applicable when a caller triggers an HMAC
operation:”h]”hŒSThe following call sequence is applicable when a caller triggers an HMAC
operation:”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj¡  hžhubj‰  )”}”(hhh]”(hÞ)”}”(hXj  The AHASH API functions are invoked by the caller. The HMAC
implementation performs its operation as needed.

During initialization of the HMAC cipher, the SHASH cipher type of
SHA256 is instantiated. The cipher handle for the SHA256 instance is
retained.

At one time, the HMAC implementation requires a SHA256 operation
where the SHA256 cipher handle is used.
”h]”(hÉ)”}”(hŒlThe AHASH API functions are invoked by the caller. The HMAC
implementation performs its operation as needed.”h]”hŒlThe AHASH API functions are invoked by the caller. The HMAC
implementation performs its operation as needed.”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M“hjí  ubhÉ)”}”(hŒ‘During initialization of the HMAC cipher, the SHASH cipher type of
SHA256 is instantiated. The cipher handle for the SHA256 instance is
retained.”h]”hŒ‘During initialization of the HMAC cipher, the SHASH cipher type of
SHA256 is instantiated. The cipher handle for the SHA256 instance is
retained.”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M–hjí  ubhÉ)”}”(hŒhAt one time, the HMAC implementation requires a SHA256 operation
where the SHA256 cipher handle is used.”h]”hŒhAt one time, the HMAC implementation requires a SHA256 operation
where the SHA256 cipher handle is used.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mšhjí  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjê  hžhhŸh¶h NubhÞ)”}”(hŒjThe HMAC instance now invokes the SHASH API with the SHA256 cipher
handle to calculate the message digest.”h]”hÉ)”}”(hŒjThe HMAC instance now invokes the SHASH API with the SHA256 cipher
handle to calculate the message digest.”h]”hŒjThe HMAC instance now invokes the SHASH API with the SHA256 cipher
handle to calculate the message digest.”…””}”(hj%	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj!	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝhjê  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jQ  jR  jS  hjT  jU  uh1jˆ  hj¡  hžhhŸh¶h M“ubeh}”(h]”Œ&generic-keyed-message-digest-structure”ah ]”h"]”Œ&generic keyed message digest structure”ah$]”h&]”uh1h¡hjÌ  hžhhŸh¶h Mtubeh}”(h]”Œ'internal-structure-of-kernel-crypto-api”ah ]”h"]”Œ'internal structure of kernel crypto api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Këubeh}”(h]”Œkernel-crypto-api-architecture”ah ]”h"]”Œkernel crypto api architecture”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jz	  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jT	  jQ	  jd  ja  jŒ  j‰  jÏ  jÌ  jX  jU  j  j|  jÉ  jÆ  jL	  jI	  ji  jf  jž  j›  jD	  jA	  uŒ	nametypes”}”(jT	  ‰jd  ‰jŒ  ‰jÏ  ‰jX  ‰j  ‰jÉ  ‰jL	  ‰ji  ‰jž  ‰jD	  ‰uh}”(jQ	  h£ja  h·j‰  jg  jÌ  j  jU  jÒ  j|  j[  jÆ  j‚  jI	  jÌ  jf  jù  j›  jl  jA	  j¡  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.