€•ïm      Œ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/libcrypto”Œ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/libcrypto”Œ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/libcrypto”Œ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/libcrypto”Œ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/libcrypto”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/pt_BR/crypto/libcrypto”Œ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/libcrypto”Œ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Œcomment”“”)”}”(hŒ)SPDX-License-Identifier: GPL-2.0-or-later”h]”hŒ)SPDX-License-Identifier: GPL-2.0-or-later”…””}”hh·sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1hµhhh²hh³Œ>/var/lib/git/docbuild/linux/Documentation/crypto/libcrypto.rst”h´KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒCrypto library”h]”hŒCrypto library”…””}”(hhÏh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhhÊh²hh³hÇh´KubhŒ	paragraph”“”)”}”(hŒn``lib/crypto/`` provides faster and easier access to cryptographic algorithms
than the traditional crypto API.”h]”(hŒliteral”“”)”}”(hŒ``lib/crypto/``”h]”hŒlib/crypto/”…””}”(hhåh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhhßubhŒ_ provides faster and easier access to cryptographic algorithms
than the traditional crypto API.”…””}”(hhßh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KhhÊh²hubhÞ)”}”(hŒ„Each cryptographic algorithm is supported via a set of dedicated functions.
"Crypto agility", where needed, is left to calling code.”h]”hŒˆEach cryptographic algorithm is supported via a set of dedicated functions.
â€œCrypto agilityâ€, where needed, is left to calling code.”…””}”(hhýh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K
hhÊh²hubhÞ)”}”(hŒìThe crypto library functions are intended to be boring and straightforward, and
to follow familiar conventions.  Their primary documentation is their (fairly
extensive) kernel-doc.  This page just provides some extra high-level context.”h]”hŒìThe crypto library functions are intended to be boring and straightforward, and
to follow familiar conventions.  Their primary documentation is their (fairly
extensive) kernel-doc.  This page just provides some extra high-level context.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KhhÊh²hubhÞ)”}”(hX  Note that the crypto library isn't entirely new.  ``lib/`` has contained some
crypto functions since 2005.  Rather, it's just an approach that's been expanded
over time as it's been found to work well.  It also largely just matches how the
kernel already does things elsewhere.”h]”(hŒ4Note that the crypto library isnâ€™t entirely new.  ”…””}”(hj  h²hh³Nh´Nubhä)”}”(hŒ``lib/``”h]”hŒlib/”…””}”(hj!  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj  ubhŒá has contained some
crypto functions since 2005.  Rather, itâ€™s just an approach thatâ€™s been expanded
over time as itâ€™s been found to work well.  It also largely just matches how the
kernel already does things elsewhere.”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KhhÊh²hubhÉ)”}”(hhh]”(hÎ)”}”(hŒScope and intended audience”h]”hŒScope and intended audience”…””}”(hj<  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj9  h²hh³hÇh´KubhÞ)”}”(hX(  The crypto library documentation is primarily meant for kernel developers who
need to use a particular cryptographic algorithm(s) in kernel code.  For
example, "I just need to compute a SHA-256 hash."  A secondary audience is
developers working on the crypto algorithm implementations themselves.”h]”hX,  The crypto library documentation is primarily meant for kernel developers who
need to use a particular cryptographic algorithm(s) in kernel code.  For
example, â€œI just need to compute a SHA-256 hash.â€  A secondary audience is
developers working on the crypto algorithm implementations themselves.”…””}”(hjJ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khj9  h²hubhÞ)”}”(hXÅ  If you're looking for more general information about cryptography, like the
differences between the different crypto algorithms or how to select an
appropriate algorithm, you should refer to external sources which cover that
type of information much more comprehensively.  If you need help selecting
algorithms for a new kernel feature that doesn't already have its algorithms
predefined, please reach out to ``linux-crypto@vger.kernel.org`` for advice.”h]”(hX  If youâ€™re looking for more general information about cryptography, like the
differences between the different crypto algorithms or how to select an
appropriate algorithm, you should refer to external sources which cover that
type of information much more comprehensively.  If you need help selecting
algorithms for a new kernel feature that doesnâ€™t already have its algorithms
predefined, please reach out to ”…””}”(hjX  h²hh³Nh´Nubhä)”}”(hŒ ``linux-crypto@vger.kernel.org``”h]”hŒlinux-crypto@vger.kernel.org”…””}”(hj`  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjX  ubhŒ for advice.”…””}”(hjX  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khj9  h²hubeh}”(h]”Œscope-and-intended-audience”ah ]”h"]”Œscope and intended audience”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KubhÉ)”}”(hhh]”(hÎ)”}”(hŒCode organization”h]”hŒCode organization”…””}”(hjƒ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj€  h²hh³hÇh´K&ubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ9``lib/crypto/*.c``: the crypto algorithm implementations
”h]”hÞ)”}”(hŒ8``lib/crypto/*.c``: the crypto algorithm implementations”h]”(hä)”}”(hŒ``lib/crypto/*.c``”h]”hŒlib/crypto/*.c”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjœ  ubhŒ&: the crypto algorithm implementations”…””}”(hjœ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K(hj˜  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hj“  h²hh³hÇh´Nubj—  )”}”(hX#  ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms.
It is here rather than somewhere in ``arch/`` partly because this allows
generic and architecture-optimized code to be easily built into a single
loadable module (when the algorithm is set to 'm' in the kconfig).
”h]”hÞ)”}”(hX"  ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms.
It is here rather than somewhere in ``arch/`` partly because this allows
generic and architecture-optimized code to be easily built into a single
loadable module (when the algorithm is set to 'm' in the kconfig).”h]”(hä)”}”(hŒ``lib/crypto/$(SRCARCH)/``”h]”hŒlib/crypto/$(SRCARCH)/”…””}”(hjÆ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjÂ  ubhŒX: architecture-specific code for crypto algorithms.
It is here rather than somewhere in ”…””}”(hjÂ  h²hh³Nh´Nubhä)”}”(hŒ	``arch/``”h]”hŒarch/”…””}”(hjØ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjÂ  ubhŒ« partly because this allows
generic and architecture-optimized code to be easily built into a single
loadable module (when the algorithm is set to â€˜mâ€™ in the kconfig).”…””}”(hjÂ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K*hj¾  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hj“  h²hh³hÇh´Nubj—  )”}”(hŒ=``lib/crypto/tests/``: KUnit tests for the crypto algorithms
”h]”hÞ)”}”(hŒ<``lib/crypto/tests/``: KUnit tests for the crypto algorithms”h]”(hä)”}”(hŒ``lib/crypto/tests/``”h]”hŒlib/crypto/tests/”…””}”(hjþ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjú  ubhŒ': KUnit tests for the crypto algorithms”…””}”(hjú  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K/hjö  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hj“  h²hh³hÇh´Nubj—  )”}”(hŒ```include/crypto/``: crypto headers, for both the crypto library and the
traditional crypto API
”h]”hÞ)”}”(hŒ_``include/crypto/``: crypto headers, for both the crypto library and the
traditional crypto API”h]”(hä)”}”(hŒ``include/crypto/``”h]”hŒinclude/crypto/”…””}”(hj$  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj   ubhŒL: crypto headers, for both the crypto library and the
traditional crypto API”…””}”(hj   h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K1hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hj“  h²hh³hÇh´Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j‘  h³hÇh´K(hj€  h²hubhÞ)”}”(hŒâGenerally, there is one kernel module per algorithm.  Sometimes related
algorithms are grouped into one module.  There is intentionally no common
framework, though there are some utility functions that multiple algorithms use.”h]”hŒâGenerally, there is one kernel module per algorithm.  Sometimes related
algorithms are grouped into one module.  There is intentionally no common
framework, though there are some utility functions that multiple algorithms use.”…””}”(hjJ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K4hj€  h²hubhÞ)”}”(hX  Each algorithm module is controlled by a tristate kconfig symbol
``CRYPTO_LIB_$(ALGORITHM)``.  As is the norm for library functions in the
kernel, these are hidden symbols which don't show up in the kconfig menu.
Instead, they are just selected by all the kconfig symbols that need them.”h]”(hŒAEach algorithm module is controlled by a tristate kconfig symbol
”…””}”(hjX  h²hh³Nh´Nubhä)”}”(hŒ``CRYPTO_LIB_$(ALGORITHM)``”h]”hŒCRYPTO_LIB_$(ALGORITHM)”…””}”(hj`  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjX  ubhŒÅ.  As is the norm for library functions in the
kernel, these are hidden symbols which donâ€™t show up in the kconfig menu.
Instead, they are just selected by all the kconfig symbols that need them.”…””}”(hjX  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K8hj€  h²hubhÞ)”}”(hX  Many of the algorithms have multiple implementations: a generic implementation
and architecture-optimized implementation(s).  Each module initialization
function, or initcall in the built-in case, automatically enables the best
implementation based on the available CPU features.”h]”hX  Many of the algorithms have multiple implementations: a generic implementation
and architecture-optimized implementation(s).  Each module initialization
function, or initcall in the built-in case, automatically enables the best
implementation based on the available CPU features.”…””}”(hjx  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K=hj€  h²hubhÞ)”}”(hX  Note that the crypto library doesn't use the ``crypto/``,
``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories.  These
directories are used by the traditional crypto API.  When possible, algorithms
in the traditional crypto API are implemented by calls into the library.”h]”(hŒ/Note that the crypto library doesnâ€™t use the ”…””}”(hj†  h²hh³Nh´Nubhä)”}”(hŒ``crypto/``”h]”hŒcrypto/”…””}”(hjŽ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj†  ubhŒ,
”…””}”(hj†  h²hh³Nh´Nubhä)”}”(hŒ``arch/$(SRCARCH)/crypto/``”h]”hŒarch/$(SRCARCH)/crypto/”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj†  ubhŒ, or ”…””}”(hj†  h²hh³Nh´Nubhä)”}”(hŒ``drivers/crypto/``”h]”hŒdrivers/crypto/”…””}”(hj²  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj†  ubhŒ¬ directories.  These
directories are used by the traditional crypto API.  When possible, algorithms
in the traditional crypto API are implemented by calls into the library.”…””}”(hj†  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KBhj€  h²hubeh}”(h]”Œcode-organization”ah ]”h"]”Œcode organization”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´K&ubhÉ)”}”(hhh]”(hÎ)”}”(hŒ
Advantages”h]”hŒ
Advantages”…””}”(hjÕ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjÒ  h²hh³hÇh´KHubhÞ)”}”(hŒJSome of the advantages of the library over the traditional crypto API are:”h]”hŒJSome of the advantages of the library over the traditional crypto API are:”…””}”(hjã  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KJhjÒ  h²hubj’  )”}”(hhh]”(j—  )”}”(hXq  The library functions tend to be much easier to use.  For example, a hash
value can be computed using only a single function call.  Most of the library
functions always succeed and return void, eliminating the need to write
error-handling code.  Most also accept standard virtual addresses, rather than
scatterlists which are difficult and less efficient to work with.
”h]”hÞ)”}”(hXp  The library functions tend to be much easier to use.  For example, a hash
value can be computed using only a single function call.  Most of the library
functions always succeed and return void, eliminating the need to write
error-handling code.  Most also accept standard virtual addresses, rather than
scatterlists which are difficult and less efficient to work with.”h]”hXp  The library functions tend to be much easier to use.  For example, a hash
value can be computed using only a single function call.  Most of the library
functions always succeed and return void, eliminating the need to write
error-handling code.  Most also accept standard virtual addresses, rather than
scatterlists which are difficult and less efficient to work with.”…””}”(hjø  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KLhjô  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubj—  )”}”(hX3  The library functions are usually faster, especially for short inputs.  They
call the crypto algorithms directly without inefficient indirect calls, memory
allocations, string parsing, lookups in an algorithm registry, and other
unnecessary API overhead.  Architecture-optimized code is enabled by default.
”h]”hÞ)”}”(hX2  The library functions are usually faster, especially for short inputs.  They
call the crypto algorithms directly without inefficient indirect calls, memory
allocations, string parsing, lookups in an algorithm registry, and other
unnecessary API overhead.  Architecture-optimized code is enabled by default.”h]”hX2  The library functions are usually faster, especially for short inputs.  They
call the crypto algorithms directly without inefficient indirect calls, memory
allocations, string parsing, lookups in an algorithm registry, and other
unnecessary API overhead.  Architecture-optimized code is enabled by default.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KRhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubj—  )”}”(hŒÙThe library functions use standard link-time dependencies instead of
error-prone dynamic loading by name.  There's no need for workarounds such as
forcing algorithms to be built-in or adding module soft dependencies.
”h]”hÞ)”}”(hŒØThe library functions use standard link-time dependencies instead of
error-prone dynamic loading by name.  There's no need for workarounds such as
forcing algorithms to be built-in or adding module soft dependencies.”h]”hŒÚThe library functions use standard link-time dependencies instead of
error-prone dynamic loading by name.  Thereâ€™s no need for workarounds such as
forcing algorithms to be built-in or adding module soft dependencies.”…””}”(hj(  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KWhj$  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubj—  )”}”(hŒÖThe library focuses on the approach that works the best on the vast majority
of systems: CPU-based implementations of the crypto algorithms, utilizing
on-CPU acceleration (such as AES instructions) when available.
”h]”hÞ)”}”(hŒÕThe library focuses on the approach that works the best on the vast majority
of systems: CPU-based implementations of the crypto algorithms, utilizing
on-CPU acceleration (such as AES instructions) when available.”h]”hŒÕThe library focuses on the approach that works the best on the vast majority
of systems: CPU-based implementations of the crypto algorithms, utilizing
on-CPU acceleration (such as AES instructions) when available.”…””}”(hj@  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K[hj<  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubj—  )”}”(hŒHThe library uses standard KUnit tests, rather than custom ad-hoc tests.
”h]”hÞ)”}”(hŒGThe library uses standard KUnit tests, rather than custom ad-hoc tests.”h]”hŒGThe library uses standard KUnit tests, rather than custom ad-hoc tests.”…””}”(hjX  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K_hjT  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubj—  )”}”(hŒµThe library tends to have higher assurance implementations of the crypto
algorithms.  This is both due to its simpler design and because more of its
code is being regularly tested.
”h]”hÞ)”}”(hŒ´The library tends to have higher assurance implementations of the crypto
algorithms.  This is both due to its simpler design and because more of its
code is being regularly tested.”h]”hŒ´The library tends to have higher assurance implementations of the crypto
algorithms.  This is both due to its simpler design and because more of its
code is being regularly tested.”…””}”(hjp  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kahjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubj—  )”}”(hŒThe library supports features that don't fit into the rigid framework of the
traditional crypto API, for example interleaved hashing and XOFs.
”h]”hÞ)”}”(hŒŽThe library supports features that don't fit into the rigid framework of the
traditional crypto API, for example interleaved hashing and XOFs.”h]”hŒThe library supports features that donâ€™t fit into the rigid framework of the
traditional crypto API, for example interleaved hashing and XOFs.”…””}”(hjˆ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kehj„  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjñ  h²hh³hÇh´Nubeh}”(h]”h ]”h"]”h$]”h&]”jH  jI  uh1j‘  h³hÇh´KLhjÒ  h²hubeh}”(h]”Œ
advantages”ah ]”h"]”Œ
advantages”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KHubhÉ)”}”(hhh]”(hÎ)”}”(hŒWhen to use it”h]”hŒWhen to use it”…””}”(hj­  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjª  h²hh³hÇh´KiubhÞ)”}”(hŒÚIn-kernel users should use the library (rather than the traditional crypto API)
whenever possible.  Many subsystems have already been converted.  It usually
simplifies their code significantly and improves performance.”h]”hŒÚIn-kernel users should use the library (rather than the traditional crypto API)
whenever possible.  Many subsystems have already been converted.  It usually
simplifies their code significantly and improves performance.”…””}”(hj»  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kkhjª  h²hubhÞ)”}”(hŒúSome kernel features allow userspace to provide an arbitrary string that selects
an arbitrary algorithm from the traditional crypto API by name.  These features
generally will have to keep using the traditional crypto API for backwards
compatibility.”h]”hŒúSome kernel features allow userspace to provide an arbitrary string that selects
an arbitrary algorithm from the traditional crypto API by name.  These features
generally will have to keep using the traditional crypto API for backwards
compatibility.”…””}”(hjÉ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kohjª  h²hubhÞ)”}”(hXq  Note: new kernel features shouldn't support every algorithm, but rather make a
deliberate choice about what algorithm(s) to support.  History has shown that
making a deliberate, thoughtful choice greatly simplifies code maintenance,
reduces the chance for mistakes (such as using an obsolete, insecure, or
inappropriate algorithm), and makes your feature easier to use.”h]”hXs  Note: new kernel features shouldnâ€™t support every algorithm, but rather make a
deliberate choice about what algorithm(s) to support.  History has shown that
making a deliberate, thoughtful choice greatly simplifies code maintenance,
reduces the chance for mistakes (such as using an obsolete, insecure, or
inappropriate algorithm), and makes your feature easier to use.”…””}”(hj×  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kthjª  h²hubeh}”(h]”Œwhen-to-use-it”ah ]”h"]”Œwhen to use it”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KiubhÉ)”}”(hhh]”(hÎ)”}”(hŒTesting”h]”hŒTesting”…””}”(hjð  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjí  h²hh³hÇh´K{ubhÞ)”}”(hŒÁThe crypto library uses standard KUnit tests.  Like many of the kernel's other
KUnit tests, they are included in the set of tests that is run by
``tools/testing/kunit/kunit.py run --alltests``.”h]”(hŒ“The crypto library uses standard KUnit tests.  Like many of the kernelâ€™s other
KUnit tests, they are included in the set of tests that is run by
”…””}”(hjþ  h²hh³Nh´Nubhä)”}”(hŒ/``tools/testing/kunit/kunit.py run --alltests``”h]”hŒ+tools/testing/kunit/kunit.py run --alltests”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhjþ  ubhŒ.”…””}”(hjþ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K}hjí  h²hubhÞ)”}”(hŒ†A ``.kunitconfig`` file is also provided to run just the crypto library tests.
For example, here's how to run them in user-mode Linux:”h]”(hŒA ”…””}”(hj  h²hh³Nh´Nubhä)”}”(hŒ``.kunitconfig``”h]”hŒ.kunitconfig”…””}”(hj&  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhj  ubhŒv file is also provided to run just the crypto library tests.
For example, hereâ€™s how to run them in user-mode Linux:”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khjí  h²hubhŒliteral_block”“”)”}”(hŒ:tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/”h]”hŒ:tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/”…””}”hj@  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆŒforce”‰Œlanguage”Œsh”Œhighlight_args”}”uh1j>  h³hÇh´K„hjí  h²hubhÞ)”}”(hŒàMany of the crypto algorithms have architecture-optimized implementations.
Testing those requires building an appropriate kernel and running the tests
either in QEMU or on appropriate hardware.  Here's one example with QEMU:”h]”hŒâMany of the crypto algorithms have architecture-optimized implementations.
Testing those requires building an appropriate kernel and running the tests
either in QEMU or on appropriate hardware.  Hereâ€™s one example with QEMU:”…””}”(hjS  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kˆhjí  h²hubj?  )”}”(hŒ]tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ --arch=arm64 --make_options LLVM=1”h]”hŒ]tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ --arch=arm64 --make_options LLVM=1”…””}”hja  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjN  ‰jO  Œsh”jQ  }”uh1j>  h³hÇh´KŒhjí  h²hubhÞ)”}”(hŒ‹Depending on the code being tested, flags may need to be passed to QEMU to
emulate the correct type of hardware for the code to be reached.”h]”hŒ‹Depending on the code being tested, flags may need to be passed to QEMU to
emulate the correct type of hardware for the code to be reached.”…””}”(hjq  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khjí  h²hubhÞ)”}”(hŒƒSince correctness is essential in cryptographic code, new architecture-optimized
code is accepted only if it can be tested in QEMU.”h]”hŒƒSince correctness is essential in cryptographic code, new architecture-optimized
code is accepted only if it can be tested in QEMU.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K“hjí  h²hubhÞ)”}”(hX/  Note: the crypto library also includes FIPS 140 self-tests.  These are
lightweight, are designed specifically to meet FIPS 140 requirements, and exist
*only* to meet those requirements.  Normal testing done by kernel developers and
integrators should use the much more comprehensive KUnit tests instead.”h]”(hŒ—Note: the crypto library also includes FIPS 140 self-tests.  These are
lightweight, are designed specifically to meet FIPS 140 requirements, and exist
”…””}”(hj  h²hh³Nh´NubhŒemphasis”“”)”}”(hŒ*only*”h]”hŒonly”…””}”(hj—  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j•  hj  ubhŒ’ to meet those requirements.  Normal testing done by kernel developers and
integrators should use the much more comprehensive KUnit tests instead.”…””}”(hj  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K–hjí  h²hubeh}”(h]”Œtesting”ah ]”h"]”Œtesting”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´K{ubhÉ)”}”(hhh]”(hÎ)”}”(hŒAPI documentation”h]”hŒAPI documentation”…””}”(hjº  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj·  h²hh³hÇh´KœubhŒcompound”“”)”}”(hhh]”h Œtoctree”“”)”}”(hhh]”h}”(h]”h ]”h"]”h$]”h&]”hŒcrypto/libcrypto”Œentries”]”(NŒcrypto/libcrypto-blockcipher”†”NŒcrypto/libcrypto-hash”†”NŒcrypto/libcrypto-signature”†”NŒcrypto/libcrypto-utils”†”NŒcrypto/sha3”†”eŒincludefiles”]”(jÛ  jÝ  jß  já  jã  eŒmaxdepth”KŒcaption”NŒglob”‰Œhidden”‰Œincludehidden”‰Œnumbered”K Œ
titlesonly”‰Œ
rawentries”]”uh1jÍ  h³hÇh´KžhjÊ  ubah}”(h]”h ]”Œtoctree-wrapper”ah"]”h$]”h&]”uh1jÈ  hj·  h²hh³hÇh´Nubeh}”(h]”Œapi-documentation”ah ]”h"]”Œapi documentation”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´Kœubeh}”(h]”Œcrypto-library”ah ]”h"]”Œcrypto library”ah$]”h&]”uh1hÈhhh²hh³hÇh´Kubeh}”(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”j*  Œ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”}”(j  j  j}  jz  jÏ  jÌ  j§  j¤  jê  jç  j´  j±  jü  jù  uŒ	nametypes”}”(j  ‰j}  ‰jÏ  ‰j§  ‰jê  ‰j´  ‰jü  ‰uh}”(j  hÊjz  j9  jÌ  j€  j¤  jÒ  jç  jª  j±  jí  jù  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.