EVP_MD_CTX_CTRL(3)

NAME
EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, EVP_MD_CTX_md_data - configure EVP message digest contexts

SYNOPSIS
libcrypto
#include <openssl/evp.h>
int
EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int command, int p1, void* p2);
void
EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);
void
EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
int
EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
EVP_PKEY_CTX *
EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx);
void
EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);
void *
EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);

DESCRIPTION
EVP_MD_CTX_ctrl() performs the digest-specific control command with the command-specific arguments p1 and p2 on ctx, which needs to already be set up with EVP_DigestInit_ex(3) before calling this function. Other restrictions may apply depending on the control command and digest implementation.

If the command is EVP_MD_CTRL_MICALG, p1 is ignored and p2 is an output argument of the type char **p2. A string specifying the digest Message Integrity Check algorithm is allocated and a pointer to this string is returned in *p2. It is the responsibility of the caller to free(3) *p2 when it is no longer needed. This command is used by SMIME_write_CMS(3) and SMIME_write_PKCS7(3) when creating S/MIME multipart/signed messages as specified in RFC 3851.

EVP_MD_CTX_set_flags() sets and EVP_MD_CTX_clear_flags() clears all the flag bits in ctx that are set in the flags argument. EVP_MD_CTX_test_flags() tests which of the flag bits that are set in the flags argument are also set in ctx. Possible flag bits are:

EVP_MD_CTX_FLAG_NO_INIT
    Instruct EVP_DigestInit_ex(3) and functions calling it not to initialise the internal data that is specific to the digest method and its implementation.

EVP_MD_CTX_FLAG_ONESHOT
    Instruct the digest to optimize for one update only, if possible. For digest algorithms built into the library, this flag usually has no effect.

EVP_MD_CTX_pkey_ctx() returns the EVP_PKEY_CTX assigned to ctx. The returned pointer should not be freed by the caller.

EVP_MD_CTX_set_pkey_ctx() assigns pctx to ctx. This is normally used to provide a customized EVP_PKEY_CTX to EVP_DigestSignInit(3) or EVP_DigestVerifyInit(3). The caller retains ownership of the pctx passed to this function and is responsible for freeing it when it is no longer needed.

If the ctx already contains a EVP_PKEY_CTX when this function is called, that old EVP_PKEY_CTX is freed if it was created internally, but if it was also installed with EVP_MD_CTX_set_pkey_ctx(), the pointer to the old EVP_PKEY_CTX is merely replaced by the new pointer and ownership of the old EVP_PKEY_CTX remains with the previous caller.

Passing a NULL pointer for the pctx argument is also allowed. In that case, any EVP_PKEY_CTX already assigned to ctx is dissociated from it as described above, but no new EVP_PKEY_CTX is assigned.

EVP_MD_CTX_md_data() returns the digest method private data of ctx. The space is allocated with a size determined at compile time. The size is not exposed by an API.

RETURN VALUES
EVP_MD_CTX_ctrl() returns 1 for success or 0 for failure.

EVP_MD_CTX_test_flags() returns the bitwise OR of the flags argument and the flags set in ctx.

EVP_MD_CTX_pkey_ctx() and EVP_MD_CTX_md_data() return pointers to storage owned by ctx.

SEE ALSO
evp(3), EVP_DigestInit(3), EVP_MD_nid(3)

HISTORY
EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), and EVP_MD_CTX_test_flags(), first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2.

EVP_MD_CTX_ctrl() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 5.7.

EVP_MD_CTX_pkey_ctx() and EVP_MD_CTX_md_data() first appeared in OpenSSL 1.1.0 and EVP_MD_CTX_set_pkey_ctx() in OpenSSL 1.1.1. These functions have been available since OpenBSD 7.1.