LIFE_CYCLE-DIGEST(7ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 LIFE_CYCLE-DIGEST

okay so first things first — the manual name is LIFE_CYCLE-DIGEST (section 7ossl), and it's an OpenSSL page, and it is entirely about the life-cycle of a message digest. no tea, no drama, just a whole glow-up journey from "doesn't exist" to "freed". it's giving caterpillar-to-butterfly but for cryptographic hash objects. 🦋✨

💖 NAME

life_cycle-digest — the digest algorithm life-cycle. yes bestie, that's the whole name. short and iconic.

🌸 DESCRIPTION

Every single message digest (MD) moves through a bunch of stages in its life, like a little character arc. here's the whole cast, in order: 🎀

  • start — this is the MD before it has been allocated. the blank slate, the pre-canon era. it's the starting state for any life-cycle transition.
  • newed — the MD after it has been allocated. it exists now!! it has a home. 🏠
  • initialised — the MD is set up and capable of processing input. it's got its outfit on and it's ready.
  • updated — the MD is set up and capable of processing additional input or generating output. multitasking queen behavior, honestly.
  • finaled — the MD has generated output. for an XOF digest, this state means it has generated a single-shot output.
  • squeezed — for an XOF digest, the MD has generated output and, key detail, it can be called multiple times to generate more output. also the output length is variable for each call. so it just keeps giving, we love that for it. 💅
  • freed — this state is entered when the MD is freed. it is the terminal state for all life-cycle transitions. goodbye, we hardly knew ye. 😭

✨ State Transition Diagram ✨

the usual life-cycle of a MD is illustrated like this (the ASCII art has been through some things, lowkey — it's scrambled in transmission, but here it is exactly as-is, so squint and vibe):

                                     +--------------------+
                                     |       start        |
                                     +--------------------+
                                       |
   EVP_MD_CTX_reset
                                       | EVP_MD_CTX_new
   +-------------------------------------------------+
                                       v                          v
   |
                 EVP_MD_CTX_reset    + - - - - - - - - - - - - - - - - - -
   - - - - +    EVP_MD_CTX_reset            |
               +-------------------> '                   newed
   ' <--------------------+         |
               |                     + - - - - - - - - - - - - - - - - - -
   - - - - +                      |         |
               |                       |
   |         |
               |                       | EVP_DigestInit
   |         |
               |                       v
   |         |
               |   EVP_DigestInit    + - - - - - - - - - - - - - - - - - -
   - - - - +                      |         |
              +----+-------------------> '                initialised
   ' <+  EVP_DigestInit   |         |
              |    |                     + - - - - - - - - - - - - - - - - - -
   - - - - +  |                   |         |
              |    |                       |                     ^
   |                   |         |
              |    |                       | EVP_DigestUpdate    |
   EVP_DigestInit         |                   |         |
              |    |                       v                     |
   |                   |         |
              |    |
       +---------------------------------------------+  |                   |
   |
              |    +-------------------- |
   |  |                   |         |
              |                          |
   |  |                   |         |
              |      EVP_DigestUpdate    |
   |  |                   |         |
              |    +-------------------- |
   |  |                   |         |
              |    |                     |                   updated
   |  |                   |         |
              |    +-------------------> |
   |  |                   |         |
              |                          |
   |  |                   |         |
              |                          |
   |  |                   |         |
         +----+------------------------- |
   | -+-------------------+----+    |
         |    |
       +---------------------------------------------+  |                   |
   |    |
         |    |                            |
   |                   |    |    |
         |    |                            | EVP_DigestSqueeze
       +-------------------+                   |    |    |
         |    |                            v                          |
   |    |    |
         |    |      EVP_DigestSqueeze
       +---------------------------------------------+                      |
   |    |
         |    |    +-------------------- |
   |                      |    |    |
         |    |    |                     |                  squeezed
   |                      |    |    |
         |    |    +-------------------> |
   | ---------------------+    |    |
         |    |
       +---------------------------------------------+
   |    |
         |    |                                                       |
   |    |
         |    |
       +---------------------------------------+    |    |
   |    |
         |    |    |
   |    |
         +---------------------------------+                     |    |
       EVP_MD_CTX_free                       |         |
                                                                 |    v
       |         |
                                                                 |
       +------------------+  EVP_MD_CTX_free     |         |
                                                                 |  |
       freed       | <--------------------+         |
                                                                 |
       +------------------+                                |
                                                                 |
       |
                                                                 +------------------------------------------------------+

🔥 Formal State Transitions 🔥

this section defines all of the legal state transitions. this is the canonical list. no improvising, bestie — this is the source of truth:

 Function Call                --------------------- Current State
-----------------------------------
                              start   newed    initialised   updated
finaled     squeezed   freed
 EVP_MD_CTX_new               newed
 EVP_DigestInit                    initialised initialised initialised
initialised  initialised
 EVP_DigestUpdate                                updated     updated
 EVP_DigestFinal                                             finaled
 EVP_DigestFinalXOF                                          finaled
 EVP_DigestSqueeze                                           squeezed
squeezed
 EVP_MD_CTX_free              freed   freed       freed       freed
freed
 EVP_MD_CTX_reset                     newed       newed       newed
newed
 EVP_MD_CTX_get_params                newed    initialised   updated
 EVP_MD_CTX_set_params                newed    initialised   updated
 EVP_MD_CTX_gettable_params           newed    initialised   updated
 EVP_MD_CTX_settable_params           newed    initialised   updated
 EVP_MD_CTX_copy_ex                   newed    initialised   updated
squeezed

and here's what each of those rows is actually saying, in human: 🌈

  • EVP_MD_CTX_new — lands you in newed.
  • EVP_MD_CTX_reset — sends you back to newed (the table shows newed four times across the columns, so yeah, it resets you right back to the freshly-allocated vibe).
  • EVP_DigestInit — ends you in initialised. the row lists initialised five times, which is the "from basically anywhere, you can init" energy.
  • EVP_DigestUpdate — takes you to updated.
  • EVP_DigestFinal — takes you to finaled.
  • EVP_DigestFinalXOF — takes you to finaled too.
  • EVP_DigestSqueeze — takes you to squeezed, and it's listed twice because you can squeeze and squeeze again. iconic honestly.
  • EVP_MD_CTX_free — takes you to freed. that's the end of the line, periodt.
  • EVP_MD_CTX_get_params — leaves you in newed, initialised or updated (no state change, just peeking 👀).
  • EVP_MD_CTX_set_params — again, newed, initialised or updated.
  • EVP_MD_CTX_gettable_params — newed, initialised or updated.
  • EVP_MD_CTX_settable_params — newed, initialised or updated.
  • EVP_MD_CTX_copy_ex — newed, initialised, updated or squeezed.

🎀 NOTES

at some point, the EVP layer will begin enforcing the transitions described herein. so like... these aren't just suggestions forever. be on your best behavior. 🙈

🫶 SEE ALSO

Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

okay and finally the cute sign-off: this whole thing is version 3.5.6, dated 2026-04-07, and the page is LIFE_CYCLE-DIGEST(7ossl). that's it, that's the page, thanks for coming to my ted talk, mwah 💜🎀✨

📦 where this page comes from