€•>`Œsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ0/translations/zh_CN/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ0/translations/zh_TW/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ0/translations/it_IT/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ0/translations/ja_JP/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ0/translations/ko_KR/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ0/translations/pt_BR/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ0/translations/sp_SP/crypto/libcrypto-zeroization”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _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”…””}”hh·sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1hµhhh²hh³ŒJ/var/lib/git/docbuild/linux/Documentation/crypto/libcrypto-zeroization.rst”h´KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒCrypto Key Zeroization”h]”hŒCrypto Key Zeroization”…””}”(hhÏh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œid1”uh1hÍhhÊh²hh³hÇh´KubhŒ paragraph”“”)”}”(hŒVThis document describes the conventions for zeroizing crypto structures in the kernel.”h]”hŒVThis document describes the conventions for zeroizing crypto structures in the kernel.”…””}”(hháh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´KhhÊh²hubhà)”}”(hXNote: the kernel follows traditional cryptographic terminology by using the term "zeroizing" to mean erasing sensitive parameters to prevent their disclosure if the system is later compromised. This distinguishes it from zeroing memory for other purposes such as initialization.”h]”hXNote: the kernel follows traditional cryptographic terminology by using the term “zeroizing†to mean erasing sensitive parameters to prevent their disclosure if the system is later compromised. This distinguishes it from zeroing memory for other purposes such as initialization.”…””}”(hhïh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K hhÊh²hubhŒtopic”“”)”}”(hŒ Contents ”h]”(hÎ)”}”(hŒContents”h]”hŒContents”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhhÿh³hÇh´KubhŒ bullet_list”“”)”}”(hhh]”hŒ list_item”“”)”}”(hhh]”(hà)”}”(hhh]”hŒ reference”“”)”}”(hhh]”hŒCrypto Key Zeroization”…””}”(hj h²hh³Nh´Nubah}”(h]”hÞah ]”h"]”h$]”h&]”Œrefid”Œcrypto-key-zeroization”uh1jhjubah}”(h]”h ]”h"]”h$]”h&]”uh1hßhjubj)”}”(hhh]”(j)”}”(hhh]”hà)”}”(hhh]”j)”}”(hhh]”hŒOverview”…””}”(hj>h²hh³Nh´Nubah}”(h]”Œid2”ah ]”h"]”h$]”h&]”Œrefid”Œoverview”uh1jhj;ubah}”(h]”h ]”h"]”h$]”h&]”uh1hßhj8ubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj5ubj)”}”(hhh]”hà)”}”(hhh]”j)”}”(hhh]”hŒWhat to zeroize”…””}”(hj`h²hh³Nh´Nubah}”(h]”Œid3”ah ]”h"]”h$]”h&]”Œrefid”Œwhat-to-zeroize”uh1jhj]ubah}”(h]”h ]”h"]”h$]”h&]”uh1hßhjZubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj5ubj)”}”(hhh]”hà)”}”(hhh]”j)”}”(hhh]”hŒZeroization helpers”…””}”(hj‚h²hh³Nh´Nubah}”(h]”Œid4”ah ]”h"]”h$]”h&]”Œrefid”Œzeroization-helpers”uh1jhjubah}”(h]”h ]”h"]”h$]”h&]”uh1hßhj|ubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj5ubj)”}”(hhh]”hà)”}”(hhh]”j)”}”(hhh]”hŒ)Using __cleanup for automatic zeroization”…””}”(hj¤h²hh³Nh´Nubah}”(h]”Œid5”ah ]”h"]”h$]”h&]”Œrefid”Œ'using-cleanup-for-automatic-zeroization”uh1jhj¡ubah}”(h]”h ]”h"]”h$]”h&]”uh1hßhjžubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj5ubj)”}”(hhh]”hà)”}”(hhh]”j)”}”(hhh]”hŒ Automatic vs. manual zeroization”…””}”(hjÆh²hh³Nh´Nubah}”(h]”Œid6”ah ]”h"]”h$]”h&]”Œrefid”Œautomatic-vs-manual-zeroization”uh1jhjÃubah}”(h]”h ]”h"]”h$]”h&]”uh1hßhjÀubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj5ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jhjubeh}”(h]”h ]”h"]”h$]”h&]”uh1jhjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhhÿh²hh³Nh´Nubeh}”(h]”Œcontents”ah ]”Œcontents”ah"]”Œcontents”ah$]”h&]”uh1hýh³hÇh´KhhÊh²hubhÉ)”}”(hhh]”(hÎ)”}”(hŒOverview”h]”hŒOverview”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”hÝjGuh1hÍhjýh²hh³hÇh´Kubhà)”}”(hX Cryptographic key material and intermediate state (such as HMAC contexts) must be zeroized after use to prevent sensitive data from lingering on the stack or heap, where it could be leaked through memory disclosure vulnerabilities, crash dumps, or cold-boot attacks.”h]”hX Cryptographic key material and intermediate state (such as HMAC contexts) must be zeroized after use to prevent sensitive data from lingering on the stack or heap, where it could be leaked through memory disclosure vulnerabilities, crash dumps, or cold-boot attacks.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´Khjýh²hubhà)”}”(hŒ“For memory that has been allocated with kmalloc() or a similar function, kfree_sensitive() should be used instead of kfree() to release the memory.”h]”hŒ“For memory that has been allocated with kmalloc() or a similar function, kfree_sensitive() should be used instead of kfree() to release the memory.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´Khjýh²hubhà)”}”(hŒêFor other cases, the kernel provides memzero_explicit() for clearing the memory. Unlike plain memset(), memzero_explicit() is guaranteed not to be optimized away by the compiler, even when the memory being cleared appears to be dead.”h]”hŒêFor other cases, the kernel provides memzero_explicit() for clearing the memory. Unlike plain memset(), memzero_explicit() is guaranteed not to be optimized away by the compiler, even when the memory being cleared appears to be dead.”…””}”(hj*h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´Khjýh²hubhà)”}”(hŒThe crypto library builds on memzero_explicit() by providing typed zeroization helpers for each key and context structure. These helpers serve two purposes:”h]”hŒThe crypto library builds on memzero_explicit() by providing typed zeroization helpers for each key and context structure. These helpers serve two purposes:”…””}”(hj8h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K hjýh²hubhŒenumerated_list”“”)”}”(hhh]”(j)”}”(hŒ‚They make __cleanup() annotations possible, so that structures on the stack are automatically zeroized when they go out of scope. ”h]”hà)”}”(hŒThey make __cleanup() annotations possible, so that structures on the stack are automatically zeroized when they go out of scope.”h]”hŒThey make __cleanup() annotations possible, so that structures on the stack are automatically zeroized when they go out of scope.”…””}”(hjOh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K$hjKubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjHh²hh³hÇh´Nubj)”}”(hŒŒThey improve readability by replacing ``memzero_explicit(&key, sizeof(key))`` with a self-documenting call like ``aes_zeroize_key(&key)``. ”h]”hà)”}”(hŒŠThey improve readability by replacing ``memzero_explicit(&key, sizeof(key))`` with a self-documenting call like ``aes_zeroize_key(&key)``.”h]”(hŒ&They improve readability by replacing ”…””}”(hjgh²hh³Nh´NubhŒliteral”“”)”}”(hŒ'``memzero_explicit(&key, sizeof(key))``”h]”hŒ#memzero_explicit(&key, sizeof(key))”…””}”(hjqh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjgubhŒ# with a self-documenting call like ”…””}”(hjgh²hh³Nh´Nubjp)”}”(hŒ``aes_zeroize_key(&key)``”h]”hŒaes_zeroize_key(&key)”…””}”(hjƒh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjgubhŒ.”…””}”(hjgh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K'hjcubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjHh²hh³hÇh´Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jFhjýh²hh³hÇh´K$ubeh}”(h]”jMah ]”h"]”Œoverview”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KubhÉ)”}”(hhh]”(hÎ)”}”(hŒWhat to zeroize”h]”hŒWhat to zeroize”…””}”(hj¶h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”hÝjiuh1hÍhj³h²hh³hÇh´K,ubhà)”}”(hŒ[The following types of structures hold sensitive material and should be zeroized after use:”h]”hŒ[The following types of structures hold sensitive material and should be zeroized after use:”…””}”(hjÄh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K.hj³h²hubj)”}”(hhh]”(j)”}”(hŒ€**Key structures** (e.g. ``struct aes_key``, ``struct hmac_sha256_key``): contain expanded round keys or prepared key material. ”h]”hà)”}”(hŒ**Key structures** (e.g. ``struct aes_key``, ``struct hmac_sha256_key``): contain expanded round keys or prepared key material.”h]”(hŒstrong”“”)”}”(hŒ**Key structures**”h]”hŒKey structures”…””}”(hjßh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÝhjÙubhŒ (e.g. ”…””}”(hjÙh²hh³Nh´Nubjp)”}”(hŒ``struct aes_key``”h]”hŒstruct aes_key”…””}”(hjñh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjÙubhŒ, ”…””}”(hjÙh²hh³Nh´Nubjp)”}”(hŒ``struct hmac_sha256_key``”h]”hŒstruct hmac_sha256_key”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjÙubhŒ8): contain expanded round keys or prepared key material.”…””}”(hjÙh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K1hjÕubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjÒh²hh³hÇh´Nubj)”}”(hŒ–**HMAC/MAC context structures** (e.g. ``struct hmac_sha256_ctx``, ``struct aes_cmac_ctx``): contain inner and outer hash states derived from the key. ”h]”hà)”}”(hŒ•**HMAC/MAC context structures** (e.g. ``struct hmac_sha256_ctx``, ``struct aes_cmac_ctx``): contain inner and outer hash states derived from the key.”h]”(jÞ)”}”(hŒ**HMAC/MAC context structures**”h]”hŒHMAC/MAC context structures”…””}”(hj)h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÝhj%ubhŒ (e.g. ”…””}”(hj%h²hh³Nh´Nubjp)”}”(hŒ``struct hmac_sha256_ctx``”h]”hŒstruct hmac_sha256_ctx”…””}”(hj;h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johj%ubhŒ, ”…””}”(hj%h²hh³Nh´Nubjp)”}”(hŒ``struct aes_cmac_ctx``”h]”hŒstruct aes_cmac_ctx”…””}”(hjMh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johj%ubhŒ<): contain inner and outer hash states derived from the key.”…””}”(hj%h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K4hj!ubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjÒh²hh³hÇh´Nubj)”}”(hŒc**Hash context structures** (e.g. ``struct sha256_ctx``): may contain sensitive data being hashed. ”h]”hà)”}”(hŒb**Hash context structures** (e.g. ``struct sha256_ctx``): may contain sensitive data being hashed.”h]”(jÞ)”}”(hŒ**Hash context structures**”h]”hŒHash context structures”…””}”(hjsh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jÝhjoubhŒ (e.g. ”…””}”(hjoh²hh³Nh´Nubjp)”}”(hŒ``struct sha256_ctx``”h]”hŒstruct sha256_ctx”…””}”(hj…h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjoubhŒ+): may contain sensitive data being hashed.”…””}”(hjoh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K8hjkubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjÒh²hh³hÇh´Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jh³hÇh´K1hj³h²hubhà)”}”(hŒ¯Not all of these require explicit cleanup by callers. Many ``..._final()`` functions already zeroize their context internally (see `Automatic vs. manual zeroization`_ below).”h]”(hŒ_zeroize_(struct _ *p);”h]”hŒ9_zeroize_(struct _ *p);”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jh³hÇh´KFhjçh²hubhà)”}”(hŒ For example::”h]”hŒ For example:”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´KHhjçh²hubj)”}”(hXvoid aes_zeroize_key(struct aes_key *key); void aes_zeroize_enckey(struct aes_enckey *key); void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx); void aes_cmac_zeroize_key(struct aes_cmac_key *key); void aes_cmac_zeroize_ctx(struct aes_cmac_ctx *ctx);”h]”hXvoid aes_zeroize_key(struct aes_key *key); void aes_zeroize_enckey(struct aes_enckey *key); void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx); void aes_cmac_zeroize_key(struct aes_cmac_key *key); void aes_cmac_zeroize_ctx(struct aes_cmac_ctx *ctx);”…””}”hj$sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jh³hÇh´KJhjçh²hubhà)”}”(hŒvEach helper is a ``static inline`` function in the algorithm's header that wraps ``memzero_explicit()``, for example::”h]”(hŒEach helper is a ”…””}”(hj2h²hh³Nh´Nubjp)”}”(hŒ``static inline``”h]”hŒ static inline”…””}”(hj:h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johj2ubhŒ1 function in the algorithm’s header that wraps ”…””}”(hj2h²hh³Nh´Nubjp)”}”(hŒ``memzero_explicit()``”h]”hŒmemzero_explicit()”…””}”(hjLh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johj2ubhŒ, for example:”…””}”(hj2h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´KPhjçh²hubj)”}”(hŒxstatic inline void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx) { memzero_explicit(ctx, sizeof(*ctx)); }”h]”hŒxstatic inline void hmac_sha256_zeroize_ctx(struct hmac_sha256_ctx *ctx) { memzero_explicit(ctx, sizeof(*ctx)); }”…””}”hjdsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jh³hÇh´KShjçh²hubeh}”(h]”j‘ah ]”h"]”Œzeroization helpers”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KAubhÉ)”}”(hhh]”(hÎ)”}”(hŒ)Using __cleanup for automatic zeroization”h]”hŒ)Using __cleanup for automatic zeroization”…””}”(hj|h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”hÝj­uh1hÍhjyh²hh³hÇh´KZubhà)”}”(hŒÖThe preferred way to zeroize stack-allocated key and context structures is with the __cleanup() attribute. This ensures zeroization happens on all exit paths, including error returns and early exits. For example::”h]”hŒÕThe preferred way to zeroize stack-allocated key and context structures is with the __cleanup() attribute. This ensures zeroization happens on all exit paths, including error returns and early exits. For example:”…””}”(hjŠh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K\hjyh²hubj)”}”(hXšstatic int my_aesxts_setkey(..., const u8 *key, unsigned int len) { struct crypto_aes_ctx aes __cleanup(aes_zeroize_ctx); ... /* Only half of the key data is cipher key */ keylen = (len >> 1); ret = aes_expandkey(&aes, key, keylen); if (ret) return ret; ... do something with the cipher key ... /* The other half is the tweak key */ ret = aes_expandkey(&aes, (u8 *)(key + keylen), keylen); if (ret) return ret; /* <-- Could leak cipher key without __cleanup */ ... do something with the tweak key ... /* No need for memzero_explicit() at the end thanks to the __cleanup */ return 0; }”h]”hXšstatic int my_aesxts_setkey(..., const u8 *key, unsigned int len) { struct crypto_aes_ctx aes __cleanup(aes_zeroize_ctx); ... /* Only half of the key data is cipher key */ keylen = (len >> 1); ret = aes_expandkey(&aes, key, keylen); if (ret) return ret; ... do something with the cipher key ... /* The other half is the tweak key */ ret = aes_expandkey(&aes, (u8 *)(key + keylen), keylen); if (ret) return ret; /* <-- Could leak cipher key without __cleanup */ ... do something with the tweak key ... /* No need for memzero_explicit() at the end thanks to the __cleanup */ return 0; }”…””}”hj˜sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jh³hÇh´K`hjyh²hubhà)”}”(hX.Note that __cleanup() attributes should not be used in functions that use "goto" statements. The benefit of cleanup helpers is the removal of "gotos", and that "goto" statements can jump between scopes, so the expectation is that usage of "goto" and cleanup helpers is never mixed in the same function.”h]”hX>Note that __cleanup() attributes should not be used in functions that use “goto†statements. The benefit of cleanup helpers is the removal of “gotosâ€, and that “goto†statements can jump between scopes, so the expectation is that usage of “goto†and cleanup helpers is never mixed in the same function.”…””}”(hj¦h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´Kxhjyh²hubeh}”(h]”j³ah ]”h"]”Œ)using __cleanup for automatic zeroization”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KZubhÉ)”}”(hhh]”(hÎ)”}”(hŒ Automatic vs. manual zeroization”h]”hŒ Automatic vs. manual zeroization”…””}”(hj¾h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”hÝjÏuh1hÍhj»h²hh³hÇh´Kubhà)”}”(hŒ±Many ``..._final()`` functions in the crypto library automatically zeroize their context before returning. When this is the case, the kernel-doc for the function documents it::”h]”(hŒMany ”…””}”(hjÌh²hh³Nh´Nubjp)”}”(hŒ``..._final()``”h]”hŒ ..._final()”…””}”(hjÔh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjÌubhŒœ functions in the crypto library automatically zeroize their context before returning. When this is the case, the kernel-doc for the function documents it:”…””}”(hjÌh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´Khj»h²hubj)”}”(hŒKAfter finishing, this zeroizes @ctx. So the caller does not need to do it.”h]”hŒKAfter finishing, this zeroizes @ctx. So the caller does not need to do it.”…””}”hjìsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jh³hÇh´K…hj»h²hubhà)”}”(hXIn these cases, callers on simple code paths (where ``..._final()`` is always reached) do not need to add __cleanup() or explicit zeroization. However, __cleanup() is still recommended whenever there are error paths that bypass ``..._final()``, as it ensures zeroization on all paths.”h]”(hŒ4In these cases, callers on simple code paths (where ”…””}”(hjúh²hh³Nh´Nubjp)”}”(hŒ``..._final()``”h]”hŒ ..._final()”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjúubhŒ¡ is always reached) do not need to add __cleanup() or explicit zeroization. However, __cleanup() is still recommended whenever there are error paths that bypass ”…””}”(hjúh²hh³Nh´Nubjp)”}”(hŒ``..._final()``”h]”hŒ ..._final()”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johjúubhŒ), as it ensures zeroization on all paths.”…””}”(hjúh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´K‡hj»h²hubhà)”}”(hXFor algorithms where ``..._final()`` does *not* zeroize the context (such as the SHAKE XOFs, where ``shake_squeeze()`` can be called multiple times), callers must explicitly zeroize the context by calling the appropriate helper or using __cleanup(), for example::”h]”(hŒFor algorithms where ”…””}”(hj,h²hh³Nh´Nubjp)”}”(hŒ``..._final()``”h]”hŒ ..._final()”…””}”(hj4h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johj,ubhŒ does ”…””}”(hj,h²hh³Nh´NubhŒemphasis”“”)”}”(hŒ*not*”h]”hŒnot”…””}”(hjHh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jFhj,ubhŒ4 zeroize the context (such as the SHAKE XOFs, where ”…””}”(hj,h²hh³Nh´Nubjp)”}”(hŒ``shake_squeeze()``”h]”hŒshake_squeeze()”…””}”(hjZh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1johj,ubhŒ can be called multiple times), callers must explicitly zeroize the context by calling the appropriate helper or using __cleanup(), for example:”…””}”(hj,h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hßh³hÇh´KŒhj»h²hubj)”}”(hŒÃstruct shake_ctx ctx __cleanup(shake_zeroize_ctx); shake256_init(&ctx); shake_update(&ctx, data, data_len); shake_squeeze(&ctx, out, out_len); /* ctx is automatically zeroized at end of scope */”h]”hŒÃstruct shake_ctx ctx __cleanup(shake_zeroize_ctx); shake256_init(&ctx); shake_update(&ctx, data, data_len); shake_squeeze(&ctx, out, out_len); /* ctx is automatically zeroized at end of scope */”…””}”hjrsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jh³hÇh´K‘hj»h²hubeh}”(h]”jÕah ]”h"]”Œ automatic vs. manual zeroization”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KŒ referenced”Kubeh}”(h]”j.ah ]”h"]”Œcrypto key zeroization”ah$]”h&]”uh1hÈhhh²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”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”}”Œ automatic vs. manual zeroization”]”jÅasŒrefids”}”Œnameids”}”(jŒj.jújöj°jMjäjojvj‘j¸j³j„jÕuŒ nametypes”}”(jŒ‰jú‰j°‰jä‰jv‰j¸‰j„‰uh}”(j.hÊjöhÿjMjýjoj³j‘jçj³jyjÕj»hÞj jGj>jij`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”“”}”jÀKs…”R”Œparse_messages”]”Œtransform_messages”]”Œ transformer”NŒ include_log”]”Œ decoration”Nh²hub.