PROVIDER-DIGEST(7ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

🌸 PROVIDER-DIGEST(7ossl) 💅

okay bestie, buckle up — this is provider-digest, and it's literally the manual page for the digest library ↔ provider functions. that <-> is doing a lot of heavy lifting, iykyk. this is 7ossl, so it's a provider-level page, not your cute little everyday command. 🎀

✨ NAME ✨

provider-digest — the digest library <-> provider functions. that's the whole vibe, no cap. 🦋

🌈 SYNOPSIS 🌈

ok so this is the part where libcrypto and your provider hold hands. look at all these signatures, they are not actual functions, they're function signatures for OSSL_DISPATCH arrays. don't come for me, that's just how it is 💀

#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>

/*
 * Digests support the following function signatures in OSSL_DISPATCH arrays.
 * (The function signatures are not actual functions).
 */

/* Context management */
void *OSSL_FUNC_digest_newctx(void *provctx);
void OSSL_FUNC_digest_freectx(void *dctx);
void *OSSL_FUNC_digest_dupctx(void *dctx);
void OSSL_FUNC_digest_copyctx(void *voutctx, void *vinctx);

/* Digest generation */
int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]);
int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl);
int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl,
                           size_t outsz);
int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl,
                            unsigned char *out, size_t *outl, size_t outsz);

/* Digest parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx);

/* Digest operation parameter descriptors */
const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx,
                                                       void *provctx);
const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx,
                                                       void *provctx);

/* Digest parameters */
int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]);

/* Digest operation parameters */
int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]);
int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]);

like, yes, they're all here. every single one. we don't skip. 🫶

💖 DESCRIPTION 💖

so real talk: this documentation is primarily aimed at provider authors. if that's not you, go peek at provider(7) for the bigger picture, bestie.

the DIGEST operation is what lets providers implement digest algorithms and then make them available to applications through the API functions EVP_DigestInit_ex(3), EVP_DigestUpdate(3) and EVP_DigestFinal(3) — plus all the other related functions that come along for the ride. ✨

all the "functions" we're talking about here get passed as function pointers between libcrypto and the provider, inside OSSL_DISPATCH(3) arrays, via OSSL_ALGORITHM(3) arrays that the provider's provider_query_operation() function returns (peep "Provider Functions" in provider-base(7) for that one).

every single one of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a lil helper function that grabs the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_FUNC_{name}. so for example, the "function" OSSL_FUNC_digest_newctx() comes with these two besties:

typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_digest_newctx_fn
    OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf);

and the OSSL_DISPATCH(3) arrays are indexed by numbers that show up as macros in openssl-core_dispatch.h(7), like this:

OSSL_FUNC_digest_newctx               OSSL_FUNC_DIGEST_NEWCTX
OSSL_FUNC_digest_freectx              OSSL_FUNC_DIGEST_FREECTX
OSSL_FUNC_digest_dupctx               OSSL_FUNC_DIGEST_DUPCTX
OSSL_FUNC_digest_copyctx              OSSL_FUNC_DIGEST_COPYCTX

OSSL_FUNC_digest_init                 OSSL_FUNC_DIGEST_INIT
OSSL_FUNC_digest_update               OSSL_FUNC_DIGEST_UPDATE
OSSL_FUNC_digest_final                OSSL_FUNC_DIGEST_FINAL
OSSL_FUNC_digest_digest               OSSL_FUNC_DIGEST_DIGEST

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

OSSL_FUNC_digest_gettable_params      OSSL_FUNC_DIGEST_GETTABLE_PARAMS
OSSL_FUNC_digest_gettable_ctx_params  OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS
OSSL_FUNC_digest_settable_ctx_params  OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS

now, important: a digest algorithm implementation may not implement all of these functions. to actually be usable, you want all or none of OSSL_FUNC_digest_newctx, OSSL_FUNC_digest_freectx, OSSL_FUNC_digest_init, OSSL_FUNC_digest_update, OSSL_FUNC_digest_final and OSSL_FUNC_digest_get_params implemented. yes, all or none, that's not a drill. everything else? optional, do it if you feel like it 💅

🧚 Context Management Functions 🧚

  • OSSL_FUNC_digest_newctx() — should create and return a pointer to a provider-side structure that holds context info during a digest operation. a pointer to this context gets passed back in a bunch of the other digest operation function calls. the provctx parameter is the provider context generated during provider initialisation (see provider(7)). main character energy, honestly 👑
  • OSSL_FUNC_digest_freectx() — gets handed a pointer to the provider-side digest context in the dctx parameter. this function should free any resources associated with that context. clean up your room, bestie 🧹
  • OSSL_FUNC_digest_dupctx() — should duplicate the provider-side digest context in the dctx parameter and return the duplicate copy. two of them. twins. 🫶
  • OSSL_FUNC_digest_copyctx() — should copy the provider-side digest context in the vinctx parameter over to the voutctx parameter, which is another provider-side context. this one gets used in EVP_MD_CTX_copy_ex to speed up HMAC operations in PBKDF2 — glow-up via performance ✨. it's optional, and dupctx will be used instead if there's no EVP_MD_CTX_copy_ex function.

🔥 Digest Generation Functions 🔥

  • OSSL_FUNC_digest_init() — initialises a digest operation, given a newly created provider-side digest context in the dctx parameter. if params isn't NULL, it should be set on the context kinda like how you'd use OSSL_FUNC_digest_set_ctx_params().
  • OSSL_FUNC_digest_update() — gets called to feed in data that's gonna be digested, as part of a digest operation you already initialised. the dctx parameter holds a pointer to a previously initialised provider-side context. OSSL_FUNC_digest_update() should digest inl bytes of data at the location that in points to. and it may be called multiple times for a single digest operation — feed it, feed it again, it's chill 🍓
  • OSSL_FUNC_digest_final() — generates the digest that got started through earlier OSSL_FUNC_digest_init() and OSSL_FUNC_digest_update() calls. the dctx parameter holds a pointer to the provider-side context. the digest should be written to *out and the digest's length to *outl. and the digest should not exceed outsz bytes — respect the boundary, fr fr.
  • OSSL_FUNC_digest_digest() — the "oneshot" digest function 🎯. no provider-side digest context gets used here. instead, the provider context that was created during provider initialisation gets passed in the provctx parameter (see provider(7)). inl bytes at in should be digested and the result stored at out. the length of the digest should be stored in *outl, which should not exceed outsz bytes. one and done.

🎀 Digest Parameters 🎀

go check OSSL_PARAM(3) for more deets on the parameters structure all these functions use.

  • OSSL_FUNC_digest_get_params() — gets the details of the algorithm implementation and stores them in params.
  • OSSL_FUNC_digest_set_ctx_params() — sets digest operation parameters for the provider-side digest context dctx to params. any parameter settings are additional to whatever was set before. and passing NULL for params should return true.
  • OSSL_FUNC_digest_get_ctx_params() — gets digest operation details out of the given provider-side digest context dctx and stores them in params. passing NULL for params should return true. (yes the original says "details details", she's quirky like that 💀)
  • OSSL_FUNC_digest_gettable_params() — returns a constant OSSL_PARAM(3) array holding descriptors of the parameters that OSSL_FUNC_digest_get_params() can handle.
  • OSSL_FUNC_digest_gettable_ctx_params() and OSSL_FUNC_digest_settable_ctx_params() — both return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_digest_get_ctx_params() and OSSL_FUNC_digest_set_ctx_params() can handle, respectively. the array is based on the current state of the provider-side context if dctx is not NULL, and on the provider-side algorithm provctx otherwise. iykyk 🌈

the parameters that built-in digests currently recognise with this function are below. ngl, not all parameters are relevant to, or even understood by, all digests — so don't assume ✋

  • "blocksize" (OSSL_DIGEST_PARAM_BLOCK_SIZE) <unsigned integer> — the digest block size. the length of the "blocksize" parameter should not exceed that of a size_t.
  • "size" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer> — the digest output size. the length of the "size" parameter should not exceed that of a size_t.
  • "flags" (OSSL_DIGEST_PARAM_FLAGS) <unsigned integer> — diverse flags describing exceptional behaviour for the digest. here's the whole flag family 👇
    • EVP_MD_FLAG_ONESHOT — this digest method can only handle one block of input.
    • EVP_MD_FLAG_XOF — this digest method is an extensible-output function (XOF). slay, flexible output ✨
    • EVP_MD_FLAG_DIGALGID_NULL — when setting up a DigestAlgorithmIdentifier, this flag will have the parameter set to NULL by default. use this for PKCS#1. note: if combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.
    • EVP_MD_FLAG_DIGALGID_ABSENT — when setting up a DigestAlgorithmIdentifier, this flag will have the parameter left absent by default. note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.
    • EVP_MD_FLAG_DIGALGID_CUSTOM — custom DigestAlgorithmIdentifier handling via ctrl, with EVP_MD_FLAG_DIGALGID_ABSENT as default. note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden. currently unused 🙈

the length of the "flags" parameter should equal that of an unsigned long int.

🦋 Digest Context Parameters 🦋

  • OSSL_FUNC_digest_set_ctx_params() — sets digest parameters associated with the given provider-side digest context dctx to params. any parameter settings are additional to whatever was previously set. see OSSL_PARAM(3) for more deets on the parameters structure.
  • OSSL_FUNC_digest_get_ctx_params() — gets details of the currently set parameter values associated with the give provider-side digest context dctx and stores them in params. see OSSL_PARAM(3) for more deets on the parameters structure. (yes, "the give provider side", we love a typo moment 😭)

👑 RETURN VALUES 👑

  • 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. that's the whole scoring system, pass/fail 💀
  • OSSL_FUNC_digest_size() — should return the digest size.
  • OSSL_FUNC_digest_block_size() — should return the block size of the underlying digest algorithm.

and that's where part one leaves us bestie — more incoming, do not touch that dial 🎀✨

💀 BUGS 💀

ok so there's one little thing, and it's giving "known limitation, not a bug per se, but ur girl's gotta tell you" 😭

The EVP_Q_digest(), EVP_Digest() and EVP_DigestFinal_ex() API calls do not expect the digest size to be larger than EVP_MAX_MD_SIZE. Like, that's just not a vibe they're built for.

Which means: any algorithm that produces bigger digests than that is literally unusable with those API calls. Not "kinda awkward", not "works with a warning" — unusable. Periodt. So if you're out here inventing a chonky 300-byte digest and wondering why EVP_Digest() is acting brand new… that's why bestie 🫠

🌈 SEE ALSO 🌈

okay the reading list is long and honestly kind of iconic, so buckle up and go meet the whole fam 🎀

(yes, EVP_MD-KECCAK(7) and EVP_MD-SHAKE(7) are chilling there with no comma between them in the original — I'm not gonna gaslight you and pretend otherwise, that's just how it's printed 💅)

🕰️ HISTORY 🕰️

a lil lore drop for the timeline girlies ✨

  • The provider DIGEST interface was introduced in OpenSSL 3.0.
  • OSSL_FUNC_digest_copyctx() was added in 3.5 version.

so yeah, if you're on something ancient and OSSL_FUNC_digest_copyctx() isn't showing up, that's not you being bad at this — the feature literally wasn't born yet 🙈

Copyright 2019-2025 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>.

like pls respect the license, it's the bare minimum and it's free 💜

okay that's the whole page bestie, you made it to the end 🎉 go forth and digest responsibly 🦋

source 3.5.6 ✨ dated 2026-04-07 ✨ PROVIDER-DIGEST(7ossl) — slay, bye 💅🎀

📦 where this page comes from