From: Simo Sorce Date: Thu, 20 Nov 2025 19:08:56 +0000 (-0500) Subject: Add documentation for digest serialization X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a010fde5b6566d283c83f6590d88fbf3b681fd0d;p=thirdparty%2Fopenssl.git Add documentation for digest serialization Documents EVP_MD_CTX_[s|des]erialize functions. Signed-off-by: Simo Sorce Reviewed-by: Shane Lontis Reviewed-by: Tomas Mraz Reviewed-by: Dmitry Belyavskiy (Merged from https://github.com/openssl/openssl/pull/28837) --- diff --git a/CHANGES.md b/CHANGES.md index 8a04fadc9c5..31ec4adf526 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -88,6 +88,14 @@ OpenSSL 4.0 *Barry Fussell and Helen Zhang* + * Added `EVP_MD_CTX_serialize()`/`EVP_MD_CTX_deserialize()` functions. These + functions allow to export the internal state of a Digest and re-import it + later to continue a computation from a specific checkpoint. Only SHA-2 and + the SHA-3 family (Keccak, SHAKE, SHA-3) of functions currently support this + functionality + + *Simo Sorce* + OpenSSL 3.6 ----------- diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index 804a76f73b2..c7392018bef 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -13,6 +13,7 @@ EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, EVP_DigestSqueeze, +EVP_MD_CTX_serialize, EVP_MD_CTX_deserialize, EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, @@ -65,6 +66,8 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen); int EVP_DigestSqueeze(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen); + int EVP_MD_CTX_serialize(EVP_MD_CTX *ctx, unsigned char *out, size_t *outlen); + int EVP_MD_CTX_deserialize(EVP_MD_CTX *ctx, const unsigned char *in, size_t inlen); EVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in); int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); @@ -319,6 +322,24 @@ Similar to EVP_DigestFinalXOF() but allows multiple calls to be made to squeeze variable length output data. EVP_DigestFinalXOF() should not be called after this. +=item EVP_MD_CTX_serialize() and EVP_MD_CTX_deserialize() + +EVP_MD_CTX_serialize() serializes the state of the digest context I +and stores it in I, unless I is NULL. +Otherwise the maximum necessary size of the output buffer is written to +the I parameter. If I is not NULL then before the call the +I parameter must contain the length of the I buffer. If the +call is successful the data is written to I and the amount of data +written to I. + +EVP_MD_CTX_deserialize() deserializes the data from I of size I +into the digest context I. + +These functions do not guarantee importability of state exported by a +different OpenSSL version and does not guarantee interoperability between +different providers. Some providers may not allow export/import across +process boundaries. + =item EVP_MD_CTX_dup() Can be used to duplicate the message digest state from I. This is useful @@ -632,7 +653,9 @@ EVP_DigestInit_ex(), EVP_DigestInit(), EVP_DigestUpdate(), EVP_DigestFinal_ex(), -EVP_DigestFinalXOF(), and +EVP_DigestFinalXOF(), +EVP_MD_CTX_serialize(), +EVP_MD_CTX_deserialize(), and EVP_DigestFinal() return 1 for @@ -863,6 +886,9 @@ to be aliases for EVP_MD_CTX_get_size_ex(), previously they were aliases for EVP_MD_get_size which returned a constant value. This is required for XOF digests since they do not have a fixed size. +The EVP_MD_CTX_serialize() and EVP_MD_CTX_deserialize() functions were added in +OpenSSL 4.0. + =head1 COPYRIGHT Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index c44de648dcd..5620812e3fc 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -30,6 +30,10 @@ provider-digest - The digest library E-E provider functions int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl, unsigned char *out, size_t *outl, size_t outsz); + /* Digest state serialization */ + int OSSL_FUNC_digest_serialize(void *dctx, unsigned char *out, size_t *outl); + int OSSL_FUNC_digest_deserialize(void *dctx, const unsigned char *in, size_t inl); + /* Digest parameter descriptors */ const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx); @@ -84,6 +88,9 @@ macros in L, as follows: OSSL_FUNC_digest_final OSSL_FUNC_DIGEST_FINAL OSSL_FUNC_digest_digest OSSL_FUNC_DIGEST_DIGEST + OSSL_FUNC_digest_serialize OSSL_FUNC_DIGEST_SERIALIZE + OSSL_FUNC_digest_deserialize OSSL_FUNC_DIGEST_DESERIALIZE + OSSL_FUNC_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS OSSL_FUNC_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS OSSL_FUNC_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS @@ -152,6 +159,26 @@ I bytes at I should be digested and the result should be stored at I. The length of the digest should be stored in I<*outl> which should not exceed I bytes. +=head2 Digest State Serialization Functions + +OSSL_FUNC_digest_serialize() serializes the state of the digest context I. +If I is NULL, then the maximum necessary size for the output buffer is +written to I<*outl>. +If I is not NULL, then I<*outl> is assumed to contain the length of the +I buffer. If the call is successful, the serialized data is written +to I and the amount of data written is stored in I<*outl>. + +OSSL_FUNC_digest_deserialize() deserializes the data from I of size I +into the digest context I. +The context I should be initialized before calling this function. +After a successful deserialization, the context is ready to be used for +any subsequent digest operations. + +The content of the state and its validity (over time, process lifetime, etc) are +completely in control of the provider. The documentation for each provider +should state what guarantees it can offer in terms of recovering the state of a +serialized blob. + =head2 Digest Parameters See L for further details on the parameters structure used by @@ -254,9 +281,11 @@ See L for further details on the parameters structure. OSSL_FUNC_digest_newctx() and OSSL_FUNC_digest_dupctx() should return the newly created provider side digest context, or NULL on failure. -OSSL_FUNC_digest_init(), OSSL_FUNC_digest_update(), OSSL_FUNC_digest_final(), OSSL_FUNC_digest_digest(), -OSSL_FUNC_digest_set_params() and OSSL_FUNC_digest_get_params() should return 1 for success or -0 on error. +OSSL_FUNC_digest_init(), OSSL_FUNC_digest_update(), OSSL_FUNC_digest_final(), +OSSL_FUNC_digest_digest(), OSSL_FUNC_digest_get_params(), +OSSL_FUNC_digest_set_ctx_params(), OSSL_FUNC_digest_get_ctx_params(), +OSSL_FUNC_digest_serialize(), and OSSL_FUNC_digest_deserialize() should return 1 for +success or 0 on error. OSSL_FUNC_digest_size() should return the digest size.